Azure-PlantUML
PlantUML精灵、宏和原型,用于创建包含Azure组件的PlantUML图表。
Azure-PlantUML包括所有Azure服务的符号和有用的宏。 官方的Microsoft Azure架构图标被用作主要来源。此外,缺少的Azure服务符号已手动从Azure.com中提取。
使用Azure-PlantUML可以为您的Azure系统创建视觉上吸引人且易于记忆的PlantUML图表。
还可以将Azure-PlantUML与C4-PlantUML结合使用,以创建A4模型的Azure架构图。
内容
入门
要使用Azure-PlantUML,必须使用特定的!include
。
之后Azure服务宏就可用了。
所有支持的Azure服务列表可以在Azure-PlantUML Azure符号文档中找到。
先决条件
在Azure-PlantUML .puml
文件的顶部,需要包含本仓库dist
文件夹中的AzureCommon.puml
文件。
为了独立于任何互联网连接,您还可以下载AzureCommon.puml
并在本地引用:
!include path/to/AzureCommon.puml
如果您想使用本仓库中始终最新的版本,请使用以下命令:
!includeurl https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist/AzureCommon.puml
下一步是包含Azure-PlantUML中的特定.puml
文件。
每个Azure服务都有一个特定的.puml
文件,其中包含精灵和宏的定义。
还可以包含Azure服务类别的.puml
文件,这些文件包含该类别的所有Azure服务。
!define AzurePuml path/to
!include AzurePuml/AzureCommon.puml
!include AzurePuml/Databases/all.puml
!include AzurePuml/Compute/AzureFunction.puml
或者本仓库中始终更新的版本:
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Databases/all.puml
!includeurl AzurePuml/Compute/AzureFunction.puml
所有支持的Azure符号列表
所有Azure服务名称、类别、多色和单色符号及其.puml
文件可以在Azure-PlantUML Azure符号文档中找到。
Hello World
@startuml Hello World
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Databases/all.puml
!includeurl AzurePuml/Compute/AzureFunction.puml
actor "Person" as personAlias
AzureFunction(functionAlias, "Label", "Technology", "Optional Description")
AzureCosmosDb(cosmosDbAlias, "Label", "Technology", "Optional Description")
personAlias --> functionAlias
functionAlias --> cosmosDbAlias
@enduml
使用情况
如何使用Azure-PlantUML由您决定。
可以使用它构建非常简单的图表,并利用Azure-PlantUML宏。
您也可以决定只使用Azure-PlantUML精灵。
此外,还可以将Azure-PlantUML与C4-PlantUML结合使用,利用C4模型为大型系统创建图表。
基本用法
只需导入必要的.puml
文件,您就可以在所有的PlantUML图表中使用这些宏。
@startuml Basic usage - Stream processing with Azure Stream Analytics
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Analytics/AzureEventHub.puml
!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
left to right direction
agent "Device Simulator" as devices #fff
AzureEventHub(fareDataEventHub, "Fare Data", "PK: Medallion HackLicense VendorId; 3 TUs")
AzureEventHub(tripDataEventHub, "Trip Data", "PK: Medallion HackLicense VendorId; 3 TUs")
AzureStreamAnalyticsJob(streamAnalytics, "Stream Processing", "6 SUs")
AzureCosmosDb(outputCosmosDb, "Output Database", "1,000 RUs")
devices --> fareDataEventHub
devices --> tripDataEventHub
fareDataEventHub --> streamAnalytics
tripDataEventHub --> streamAnalytics
streamAnalytics --> outputCosmosDb
@enduml
原始精灵用法
如果您只想在现有图表中使用PlantUML精灵,这也是可能的。
@startuml Raw usage - Sprites
!pragma revision 1
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureRaw.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
!includeurl AzurePuml/Compute/AzureFunction.puml
component "<color:red><$AzureFunction></color>" as myFunction
database "<color:#0072C6><$AzureCosmosDb></color>" as myCosmosDb
AzureFunction(mySecondFunction, "Stream Processing", "Consumption")
rectangle "<color:AZURE_SYMBOL_COLOR><$AzureCosmosDb></color>" as mySecondCosmosDb
myFunction --> myCosmosDb
mySecondFunction --> mySecondCosmosDb
@enduml
简化模式
有时您的架构图可能包含过多的信息,不适合您的目标受众。我们需要一个管理版本 - 一种可以在管理会议中展示的版本。
请始终在附录中包括技术版本,并确保每个人都知道这只是简化版本。
要启用简化模式,需要包含AzureSimplified.puml
或将其注释掉。
@startuml Two Mode Sample
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
' !includeurl AzurePuml/AzureSimplified.puml
!includeurl AzurePuml/Analytics/AzureEventHub.puml
!includeurl AzurePuml/Compute/AzureFunction.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
!includeurl AzurePuml/Storage/AzureDataLakeStorage.puml
!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml
!includeurl AzurePuml/InternetOfThings/AzureTimeSeriesInsights.puml
!includeurl AzurePuml/Identity/AzureActiveDirectoryB2C.puml
!includeurl AzurePuml/DevOps/AzureApplicationInsights.puml
LAYOUT_LEFT_RIGHT
AzureEventHub(rawEventsHubAlias, "原始事件中心", "PK: 奖章出租车执照供应商Id; 3 TUs") AzureDataLakeStorage(datalakeAlias, "数据湖", "GRS") AzureStreamAnalyticsJob(streamAnalyticsAlias, "聚合事件", "6 SUs") AzureFunction(stateFunctionAlias, "状态处理器", "C#, 消耗计划") AzureEventHub(aggregatedEventsHubAlias, "聚合中心", "6 TUs") AzureCosmosDb(stateDBAlias, "状态数据库", "SQL API, 1000 RUs") AzureTimeSeriesInsights(timeSeriesAlias, "时间序列", "2 数据处理单元")
rawEventsHubAlias ---> datalakeAlias rawEventsHubAlias --> streamAnalyticsAlias rawEventsHubAlias ---> stateFunctionAlias streamAnalyticsAlias --> aggregatedEventsHubAlias aggregatedEventsHubAlias --> timeSeriesAlias stateFunctionAlias --> stateDBAlias
@enduml
![简化样本 - 两种模式](https://yellow-cdn.veclightyear.com/35dd4d3f/308875a1-0607-46b7-8c1b-e787ea328a41.puml)
![正常样本 - 两种模式](https://yellow-cdn.veclightyear.com/35dd4d3f/3ec32620-ea92-44c0-aae5-f93f5c951c04.puml)
### 与 C4-PlantUML 结合使用
我们的建议是将 Azure-PlantUML 与 [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) 结合使用。
查看 [高级范例](#高级范例) 部分,了解 Azure-PlantUML 的完整功能。
## 高级范例
以下高级范例来自官方 [Azure 文档](https://docs.microsoft.com/en-us/azure/) 和 [Azure 架构中心](https://docs.microsoft.com/en-us/azure/architecture/) 的再现。
所有这些都是结合 [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) 使用 [C4 模型](https://c4model.com/) 创建的:
> "一种让软件开发团队能够在不同细节级别上有效沟通其软件架构的方法,向不同类型的受众讲述不同的故事,无论是进行前期设计还是回顾性记录现有代码库”
### C4 集成
要一起使用 **Azure-PlantUML** 和 [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML),你需要包含 `AzureC4Integration.puml`。
```csharp
@startuml
!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/AzureC4Integration.puml
!includeurl AzurePuml/Databases/AzureRedisCache.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
....
@enduml
Azure IoT 参考架构:有状态流处理
Azure 参考架构:高度可扩展的 Web 应用
原文:Azure 参考架构
Visual Studio Code 的片段
由于 Visual Studio Code 中对 PlantUML 的支持非常优秀,使用 PlantUML 扩展名,你还可以在 dist/.vscode/snippets/diagram.json 中找到 Azure-PlantUML 的代码片段。
可以直接将其保存到 VS Code 中:创建您自己的片段。
或者你可以使用 Project Snippets extension。
现在可以拥有工作区/项目级别的代码片段。
定制化构建
也可以定制化 Azure-PlantUML 的分发生成。
所有细节可以在 Generating the Azure-PlantUML distro documentation 开到
构建与
- .NET 6.0 / C# - 最新 LTS 版 .NET
- YamlDotNet - 用于 YAML 配置解析的 .NET 库
- Json.NET - .NET 库用于 JSON
- Playwright - Playwright Web 测试和自动化框架的 .NET 库
贡献
如果你有任何想法,只需 打开一个 issue 告诉我们你的想法。
如果你想要贡献, 请 fork 此仓库并使用功能分支。
我们热烈欢迎 pull 请求。
许可
这个项目是根据 MIT License 许可的 - 细节见 LICENSE.md 文件
感谢
- AWS-PlantUML - 基础结构
- plantuml-office - 脚本想法
- C4 Model - 为了希望能够改进架构文档化