diff --git a/LICENSE b/LICENSE index ea7d489c..30a40d95 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2018 Ricardo Niepel +Copyright (c) 2018-2019 Ricardo Niepel, 2021-2022 Ricardo Niepel and contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 71797c95..3f5cd922 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Azure-PlantUML -![Basic usage - Stream processing with Azure Stream Analytics](http://www.plantuml.com/plantuml/proxy?idx=0&src=https%3A%2F%2Fraw.githubusercontent.com%2Fplantuml-stdlib%2FAzure-PlantUML%2Fmaster%2Fsamples%2FBasic%2520usage%2520-%2520Stream%2520processing%2520with%2520Azure%2520Stream%2520Analytics.puml) - [PlantUML](http://en.plantuml.com/) sprites, macros and stereotypes for creating PlantUML diagrams with [Azure](https://azure.microsoft.com/en-us/) components. Azure-PlantUML includes symbols and useful macros for all Azure services. @@ -61,7 +59,7 @@ To be independent of any internet connectivity, you can also download `AzureComm If you want to use the always up-to-date version in this repo, use the following: ```c# -!includeurl https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist/AzureCommon.puml +!includeurl https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist/AzureCommon.puml ``` The next step is to include specific `.puml` files from Azure-PlantUML. @@ -78,7 +76,7 @@ It is also possible to include Azure services category `.puml` files, which cont Or the always up-to-date version in this repo: ```c# -!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist +!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 @@ -92,7 +90,7 @@ All Azure services names, categories, colored and monochrom symbols, and their ` ```csharp @startuml Hello World -!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist +!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 @@ -124,10 +122,10 @@ Just import the necessary `.puml` files and you can use the macros in all your P ```csharp @startuml Basic usage - Stream processing with Azure Stream Analytics -!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist +!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/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml left to right direction @@ -136,7 +134,7 @@ 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") -AzureStreamAnalytics(streamAnalytics, "Stream Processing", "6 SUs") +AzureStreamAnalyticsJob(streamAnalytics, "Stream Processing", "6 SUs") AzureCosmosDb(outputCosmosDb, "Output Database", "1,000 RUs") devices --> fareDataEventHub @@ -158,7 +156,7 @@ If you just want to use the PlantUML sprites inside your existing diagrams, this @startuml Raw usage - Sprites !pragma revision 1 -!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist +!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 @@ -191,9 +189,8 @@ To enable the simplified mode `AzureSimplified.puml` needs to be included or can ```csharp @startuml Two Mode Sample -!pragma revision 1 -!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-1/dist +!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist !includeurl AzurePuml/AzureCommon.puml ' !includeurl AzurePuml/AzureSimplified.puml @@ -202,7 +199,7 @@ To enable the simplified mode `AzureSimplified.puml` needs to be included or can !includeurl AzurePuml/Compute/AzureFunction.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml !includeurl AzurePuml/Storage/AzureDataLakeStorage.puml -!includeurl AzurePuml/Analytics/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/InternetOfThings/AzureTimeSeriesInsights.puml !includeurl AzurePuml/Identity/AzureActiveDirectoryB2C.puml !includeurl AzurePuml/DevOps/AzureApplicationInsights.puml @@ -212,7 +209,7 @@ LAYOUT_LEFT_RIGHT AzureEventHub(rawEventsHubAlias, "Raw Event Hub", "PK: Medallion HackLicense VendorId; 3 TUs") AzureDataLakeStorage(datalakeAlias, "Data Lake", "GRS") -AzureStreamAnalytics(streamAnalyticsAlias, "Aggregate Events", "6 SUs") +AzureStreamAnalyticsJob(streamAnalyticsAlias, "Aggregate Events", "6 SUs") AzureFunction(stateFunctionAlias, "State Processor", "C#, Consumption Plan") AzureEventHub(aggregatedEventsHubAlias, "Aggregated Hub", "6 TUs") AzureCosmosDb(stateDBAlias, "State Database", "SQL API, 1000 RUs") @@ -253,7 +250,7 @@ For using **Azure-PlantUML** and [C4-PlantUML](https://github.com/plantuml-stdli !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-1/dist +!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist !includeurl AzurePuml/AzureCommon.puml !includeurl AzurePuml/AzureC4Integration.puml @@ -298,13 +295,14 @@ All details can be found in the [Generating the Azure-PlantUML distro documentat ## Built With -* [dotnet script](https://github.com/filipw/dotnet-script) - C# script runtime +* [.NET 6.0 / C#](https://dotnet.microsoft.com/en-us/download) - The latest LTS version of .NET * [YamlDotNet](https://github.com/aaubry/YamlDotNet) - .NET library for YAML config parsing * [Json.NET](https://github.com/JamesNK/Newtonsoft.Json) - .NET library for JSON +* [Playwright](https://github.com/microsoft/playwright) - .NET library for the Playwright web testing and automation framework ## Contributing -If you have any ideas, just [open an issue](https://github.com/plantuml-stdlib/Azure-PlantUML/issues/new) and tell me what you think. +If you have any ideas, just [open an issue](https://github.com/plantuml-stdlib/Azure-PlantUML/issues/new) and tell us what you think. If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome. @@ -318,4 +316,3 @@ This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md * [AWS-PlantUML](https://github.com/milo-minderbinder/AWS-PlantUML) - for the base structure * [plantuml-office](https://github.com/Roemer/plantuml-office) - for the scripts idea * [C4 Model](https://c4model.com/) - for the hope that it's possible to improve architecture documentations - diff --git a/samples/Basic usage - Stream processing with Azure Stream Analytics.puml b/samples/Basic usage - Stream processing with Azure Stream Analytics.puml index b497e69b..f0a48bf0 100644 --- a/samples/Basic usage - Stream processing with Azure Stream Analytics.puml +++ b/samples/Basic usage - Stream processing with Azure Stream Analytics.puml @@ -1,10 +1,9 @@ @startuml Basic usage - Stream processing with Azure Stream Analytics -!pragma revision 2 !define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/master/dist !includeurl AzurePuml/AzureCommon.puml !includeurl AzurePuml/Analytics/AzureEventHub.puml -!includeurl AzurePuml/Analytics/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml left to right direction @@ -13,7 +12,7 @@ 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") -AzureStreamAnalytics(streamAnalytics, "Stream Processing", "6 SUs") +AzureStreamAnalyticsJob(streamAnalytics, "Stream Processing", "6 SUs") AzureCosmosDb(outputCosmosDb, "Output Database", "1,000 RUs") devices --> fareDataEventHub diff --git a/samples/C4 usage - IoT Reference Architecture - Stateful stream processing.puml b/samples/C4 usage - IoT Reference Architecture - Stateful stream processing.puml index 5746d61f..0cd4629b 100644 --- a/samples/C4 usage - IoT Reference Architecture - Stateful stream processing.puml +++ b/samples/C4 usage - IoT Reference Architecture - Stateful stream processing.puml @@ -7,7 +7,7 @@ !includeurl AzurePuml/AzureCommon.puml !includeurl AzurePuml/AzureC4Integration.puml !includeurl AzurePuml/Compute/AzureFunction.puml -!includeurl AzurePuml/Analytics/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/Analytics/AzureEventHub.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml !includeurl AzurePuml/Storage/AzureBlobStorage.puml @@ -24,7 +24,7 @@ AzureEventHub(eventHubTelemetry, "Device Telemetry", "Standard, 5 TUs, 4 Partiti AzureFunction(telemetryFunction, "Telemetry Processing", "v1, App Service plan P3v2, C#", "transform it into a different format, e.g. joining external information") AzureCosmosDb(warmStorageCosmos, "Warm Storage", "2,000 RUs", "for consumption, e.g. display on a dashboard") -AzureStreamAnalytics(streamAnalytics, "Stream Analytics", "6 SUs", "apply complex queries over time periods, tolerates late (up to 21 days) and out-of-order (up to one hour) events") +AzureStreamAnalyticsJob(streamAnalytics, "Stream Analytics", "6 SUs", "apply complex queries over time periods, tolerates late (up to 21 days) and out-of-order (up to one hour) events") AzureFunction(alertingFunction, "Alerting", "v2, Consumption plan, JS") AzureBlobStorage(coldBlobStorage, "Cold Storage", "General Purpose v2, Cool, RA-GRS", "all incoming data records are archived indefinitely at low cost, and are easily accessible for batch processing") diff --git a/samples/Two Mode Sample - Normal.puml b/samples/Two Mode Sample - Normal.puml index f696ba07..e10725ef 100644 --- a/samples/Two Mode Sample - Normal.puml +++ b/samples/Two Mode Sample - Normal.puml @@ -10,7 +10,7 @@ !includeurl AzurePuml/Compute/AzureFunction.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml !includeurl AzurePuml/Storage/AzureDataLakeStorage.puml -!includeurl AzurePuml/Analytics/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/InternetOfThings/AzureTimeSeriesInsights.puml !includeurl AzurePuml/Identity/AzureActiveDirectoryB2C.puml !includeurl AzurePuml/DevOps/AzureApplicationInsights.puml @@ -20,7 +20,7 @@ LAYOUT_LEFT_RIGHT AzureEventHub(rawEventsHubAlias, "Raw Event Hub", "PK: Medallion HackLicense VendorId; 3 TUs") AzureDataLakeStorage(datalakeAlias, "Data Lake", "GRS") -AzureStreamAnalytics(streamAnalyticsAlias, "Aggregate Events", "6 SUs") +AzureStreamAnalyticsJob(streamAnalyticsAlias, "Aggregate Events", "6 SUs") AzureFunction(stateFunctionAlias, "State Processor", "C#, Consumption Plan") AzureEventHub(aggregatedEventsHubAlias, "Aggregated Hub", "6 TUs") AzureCosmosDb(stateDBAlias, "State Database", "SQL API, 1000 RUs") diff --git a/samples/Two Mode Sample - Simplified.puml b/samples/Two Mode Sample - Simplified.puml index 0f992936..18771d15 100644 --- a/samples/Two Mode Sample - Simplified.puml +++ b/samples/Two Mode Sample - Simplified.puml @@ -10,7 +10,7 @@ !includeurl AzurePuml/Compute/AzureFunction.puml !includeurl AzurePuml/Databases/AzureCosmosDb.puml !includeurl AzurePuml/Storage/AzureDataLakeStorage.puml -!includeurl AzurePuml/Analytics/AzureStreamAnalytics.puml +!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml !includeurl AzurePuml/InternetOfThings/AzureTimeSeriesInsights.puml !includeurl AzurePuml/Identity/AzureActiveDirectoryB2C.puml !includeurl AzurePuml/DevOps/AzureApplicationInsights.puml @@ -20,7 +20,7 @@ LAYOUT_LEFT_RIGHT AzureEventHub(rawEventsHubAlias, "Raw Event Hub", "PK: Medallion HackLicense VendorId; 3 TUs") AzureDataLakeStorage(datalakeAlias, "Data Lake", "GRS") -AzureStreamAnalytics(streamAnalyticsAlias, "Aggregate Events", "6 SUs") +AzureStreamAnalyticsJob(streamAnalyticsAlias, "Aggregate Events", "6 SUs") AzureFunction(stateFunctionAlias, "State Processor", "C#, Consumption Plan") AzureEventHub(aggregatedEventsHubAlias, "Aggregated Hub", "6 TUs") AzureCosmosDb(stateDBAlias, "State Database", "SQL API, 1000 RUs") diff --git a/scripts/GeneratePuml.csproj b/scripts/GeneratePuml.csproj index 6eca1db3..e3d73b95 100644 --- a/scripts/GeneratePuml.csproj +++ b/scripts/GeneratePuml.csproj @@ -8,14 +8,14 @@ - - - - - - - - + + + + + + + + diff --git a/scripts/README.md b/scripts/README.md index 51cfb608..9114e1bd 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -28,7 +28,7 @@ playwright install-deps ## Configure -### Icon files +### Add Icon files Download the [Microsoft Azure architecture icons](https://docs.microsoft.com/en-us/azure/architecture/icons/) and copy all folders from `Azure_Public_Service_Icons_V4\Azure_Public_Service_Icons\Icons` to [source/official](../source/official) @@ -36,7 +36,9 @@ Place any icons that are not part of the Microsoft Azure Architecture bundle int ### Application Settings -Create a new file named `appsettings.json` within the `scripts` directory and save the following contents: +Create a new file named `appsettings.json` within the `scripts` directory and add the following content based on your environment: + +**Windows** ```json { @@ -47,12 +49,42 @@ Create a new file named `appsettings.json` within the `scripts` directory and sa } ``` -### Configuration File: Config.yaml +**Ubuntu** -This configuration file is used to map specific SVG file names to Azure services. -On top each Azure service is mapped to his primary category. +```json +{ + "sourceFolderPath": "../source", + "targetFolderPath": "../dist", + "monochromeColorHex": "#0072C6", + "plantUmlPath": "/usr/share/plantuml/plantuml.jar" +} +``` -## Run +**MacOS** + +```json +{ + "sourceFolderPath": "../source", + "targetFolderPath": "../dist", + "monochromeColorHex": "#0072C6", + "plantUmlPath": "/opt/homebrew/Cellar/plantuml/1.2022.14/libexec/plantuml.jar" +} +``` + +> The path to PlantUML may vary based on the version you are using and how you installed it. Be sure to update the value for `plantUmlPath` accordingly to match your envioronment. + +### Update Config.yaml + +Update this file to add or remove icons in your distro. The `source` attribute represents the svg file name. Logic has been added to the PlantUML generation program to simplify the value used here. Dashes, spaces, and certain prefixes and suffixes are removed when searching for source files. For example, adding **App Service Plan Linux** will work for the following source files: + +* 00046-icon-service-App-Service-Plan-Linux.svg +* App-Service-Plan-Linux_COLOR.svg +* App-Service-Plan-Linux.svg + + +The `target` attribute will be used for the PlantUML element stereotype and all target file names. Keep in mind that services are grouped into categories as reflected in the YAML structure. + +## Generate PlantUML Elements Use `dotnet run` from the `scripts` folder to execute the application. @@ -77,3 +109,7 @@ From a logical point of view, the following happens: 1. In addition to single Azure services PUML files, also a combined PUML file per category is generated 1. A markdown table with all Azure services, their colored and monochrome symbols and the PUML files is generated 1. VSCode snippets for all Azure services for their PlantUML usage are generated + +## Update the Azure Symbols page + +When the program completes, replace the markdown table in [AzureSymbols.md](https://github.com/plantuml-stdlib/Azure-PlantUML/blob/release/2-2/AzureSymbols.md?plain=1#L34) with the contents from `table.md` located in your target folder.