From 16551035ea5cc72ebddad9127b1e8a6f8b917bd3 Mon Sep 17 00:00:00 2001 From: yanjustino Date: Fri, 15 Mar 2024 13:23:53 -0300 Subject: [PATCH 1/3] Release Version 3.0 --- .github/workflows/dotnet.yml | 4 +- README.md | 113 +++++++++++++++++- samples/ModelDiagrams/Structures/People.cs | 12 +- src/C4Sharp.Tools/C4Sharp.Tools.csproj | 2 +- src/C4Sharp/C4Sharp.csproj | 2 +- .../Diagrams/Plantuml/PlantumlContext.cs | 23 +++- 6 files changed, 134 insertions(+), 22 deletions(-) diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml index 08e1aef..bb8ed8e 100644 --- a/.github/workflows/dotnet.yml +++ b/.github/workflows/dotnet.yml @@ -7,8 +7,8 @@ on: branches: [ main ] env: - VERSION: 6.3.${{ github.run_number }} - CLI_VERSION: 2.3.${{ github.run_number }} + VERSION: 7.0.${{ github.run_number }} + CLI_VERSION: 3.0.${{ github.run_number }} NUGET_INDEX: https://api.nuget.org/v3/index.json BUILD_TYPE: Release diff --git a/README.md b/README.md index f75bab9..fadfb5e 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,10 @@ This package is available through [Nuget Packages](https://www.nuget.org/package |`C4SHARP`| dotnet library for building diagrams | [![NuGet](https://img.shields.io/nuget/v/C4Sharp.svg)](https://www.nuget.org/packages/C4Sharp) | [![Nuget](https://img.shields.io/nuget/dt/C4Sharp.svg)](https://www.nuget.org/packages/C4Sharp) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/51ea16a0d91548cb9e84bd6ab3e8cb9e)](https://www.codacy.com/gh/8T4/c4sharp/dashboard?utm_source=github.com&utm_medium=referral&utm_content=8T4/c4sharp&utm_campaign=Badge_Grade) | [![.NET](https://github.com/8T4/c4sharp/actions/workflows/dotnet.yml/badge.svg)](https://github.com/8T4/c4sharp/actions/workflows/dotnet.yml) | |`C4SCLI` | cli for compiling C4S projects | [![NuGet](https://img.shields.io/nuget/v/c4scli.svg)](https://www.nuget.org/packages/c4scli) | [![Nuget](https://img.shields.io/nuget/dt/c4scli.svg)](https://www.nuget.org/packages/c4scli) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/51ea16a0d91548cb9e84bd6ab3e8cb9e)](https://www.codacy.com/gh/8T4/c4sharp/dashboard?utm_source=github.com&utm_medium=referral&utm_content=8T4/c4sharp&utm_campaign=Badge_Grade) | [![.NET](https://github.com/8T4/c4sharp/actions/workflows/dotnet.yml/badge.svg)](https://github.com/8T4/c4sharp/actions/workflows/dotnet.yml) | -To build a diagram using the C4S library we need to identify the structures and their relationships through a class that inherits properties directly from DiagramBuildRunner. See the following example of building a container diagram: + +### Create a new diagram from scratch +To build a diagram using the C4S library we need to identify the structures and their relationships through a class that inherits properties directly from `DiagramBuilder` (_ContainerDiagram, ComponentDiagram, ContextDiagram, SequenceDiagram, DeploymentDiagram_). See the following example of building a container diagram: + ```C# public class ContainerDiagramSample : ContainerDiagram @@ -83,13 +86,63 @@ public class ContainerDiagramSample : ContainerDiagram }; } ``` -The following code shows how to compile the diagram: + +### Create a new diagram from existing code + +you can create structures that will be used in the diagram, as in the following example: ```c# -There are two strategies for compiling diagrams in your project: self-compiling and using the `C4SCLI` tool. +//Person +public static Person Customer => new ("customer", "Personal Banking Customer", + "A customer of the bank, with personal bank accounts.", Boundary.External); + +public static Person InternalCustomer => new Person("internalcustomer", "Personal Banking Customer", + "An customer of the bank, with personal bank accounts."); + +public static Person Manager => new ("manager", "Manager Banking Customer", + "A manager of the bank, with personal bank accounts."); + +//SoftwareSystem +public static SoftwareSystem BankingSystem => new("BankingSystem", "Internet Banking System", + "Allows customers to view information about their bank accounts, and make payments."); + +public static SoftwareSystem Mainframe => new("Mainframe", "Mainframe Banking System", + "Stores all of the core banking information about customers, accounts, transactions, etc.", Boundary.External); + +public static SoftwareSystem MailSystem => new ("MailSystem", "E-mail system", + "The internal Microsoft Exchange e-mail system.", Boundary.External); + + +``` + +```c# +public class ContextDiagramSample : ContextDiagram +{ + protected override string Title => "Component diagram for Internet Banking System"; + + protected override IEnumerable Structures => new Structure[] + { + Customer, + BankingSystem, + Mainframe, + MailSystem + }; + + protected override IEnumerable Relationships => new[] + { + Customer > BankingSystem, + Customer < MailSystem | "Sends e-mails to", + BankingSystem > MailSystem | ("Sends e-mails", "SMTP") | Neighbor, + BankingSystem > Mainframe + }; +} +``` +### Compiling the diagram +There are two strategies for compiling diagrams in your project: self-compiling and using the `C4SCLI` tool. +The following code shows how to compile the diagram: -#### a) self-compiling approach: +#### Self-compiling approach: ```c# using C4Sharp.Diagrams; @@ -117,7 +170,7 @@ new PlantumlContext() The result of the previous code is the following diagram: ![img](./docs/images/container-diagram-for-internet-banking-system-c4container.png) -### Using the C4SCLI tool: +#### Using the C4SCLI tool: > [!TIP]\ > The `C4SCLI` can be used in DevOps pipelines, removing the need to manually compile diagrams. For this, install `C4SCLI` tool and execute de the following command: @@ -126,7 +179,7 @@ $ c4scli build [-o ] ``` ### Customizing the diagram - +#### Using Themes Themes are used to customize the diagram. The following code shows how to use the `ParadisoTheme` theme to compile the diagram: ```c# @@ -138,6 +191,52 @@ new PlantumlContext() The result of the previous code is the following diagram: ![img](./docs/images/container-diagram-for-internet-banking-system-v2-c4container.png) +#### Creating a custom theme + +You can create a custom theme by implementing the `ITheme` interface. The following code shows how to create a custom theme: + +```c# +public class DefaultTheme: IDiagramTheme +{ + private const string ComponentBackground = "#85bbf0"; + private const string ComponentBorder = "#78a8d9"; + private const string ComponentText = "#000000"; + + private const string ContainerBackground = "#438dd4"; + private const string ContainerBorder = "#3e82c5"; + private const string ContainerText = "#FFFFFF"; + + private const string PersonBackground = "#0d437b"; + private const string PersonBorder = "#0d437b"; + private const string PersonText = "#FFFFFF"; + + private const string ExternalBackground = "#999999"; + private const string ExternalBorder = "#8a8a8a"; + private const string ExternalText = "#FFFFFF"; + + private const string SystemBackground = "#1a67be"; + private const string SystemBorder = "#175eaa"; + private const string SystemText = "#FFFFFF"; + + public IElementStyle? Style => new ElementStyle() + .UpdateElementStyle(ElementName.System, SystemBackground, SystemText, SystemBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 2) + .UpdateElementStyle(ElementName.ExternalSystem, ExternalBackground, ExternalText, ExternalBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 1) + .UpdateElementStyle(ElementName.Person, PersonBackground, PersonText, PersonBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 2) + .UpdateElementStyle(ElementName.Component, ComponentBackground, ComponentText, ComponentBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 2) + .UpdateElementStyle(ElementName.ExternalComponent, ExternalBackground, ExternalText, ExternalBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 1) + .UpdateElementStyle(ElementName.Container, ContainerBackground, ContainerText, ContainerBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 2) + .UpdateElementStyle(ElementName.ExternalContainer, ExternalBackground, ExternalText, ExternalBorder, false, Shape.RoundedBoxShape, BorderStyle.SolidLine, 1); + + public IBoundaryStyle? BoundaryStyle => new BoundaryStyle() + .UpdateBoundaryStyle(ElementName.System, "#FFFFFF", "#000000", "#000000", false, Shape.RoundedBoxShape) + .UpdateBoundaryStyle(ElementName.Container, "#FFFFFF", "#000000", "#000000", false, Shape.RoundedBoxShape) + .UpdateBoundaryStyle(ElementName.Enterprise, "#FFFFFF", "#000000", "#000000", false, Shape.RoundedBoxShape); + + public IElementTag? Tags { get; } = null; + public IRelationshipTag? RelTags { get; } = null; +} +``` +#### Customizing the diagram through the SetStyle method Using the `C4S` library, you can customize the diagram by implementing the SetStyle() method, as in the following example: @@ -154,6 +253,8 @@ protected override IElementStyle? SetStyle() ![img](./docs/images/c4bank-deposit-area-c4container-bw.png) +### Exporting the diagram to different formats + Now, C4Sharp can compile the [Mermaid](https://github.com/mermaid-js/mermaid) markdown file. For this, you should use the function `UseDiagramMermaidBuilder()`. The following code shows how to compile these files. ```c# diff --git a/samples/ModelDiagrams/Structures/People.cs b/samples/ModelDiagrams/Structures/People.cs index d7bf025..f8dcefd 100644 --- a/samples/ModelDiagrams/Structures/People.cs +++ b/samples/ModelDiagrams/Structures/People.cs @@ -5,12 +5,12 @@ namespace ModelDiagrams.Structures; public static class People { - public static Person Customer => - new ("customer", "Personal Banking Customer", "A customer of the bank, with personal bank accounts.", Boundary.External); + public static Person Customer => new ("customer", "Personal Banking Customer", + "A customer of the bank, with personal bank accounts.", Boundary.External); - public static Person InternalCustomer => - new Person("internalcustomer", "Personal Banking Customer", "An customer of the bank, with personal bank accounts."); + public static Person InternalCustomer => new Person("internalcustomer", "Personal Banking Customer", + "An customer of the bank, with personal bank accounts."); - public static Person Manager => - new ("manager", "Manager Banking Customer", "A manager of the bank, with personal bank accounts."); + public static Person Manager => new ("manager", "Manager Banking Customer", + "A manager of the bank, with personal bank accounts."); } diff --git a/src/C4Sharp.Tools/C4Sharp.Tools.csproj b/src/C4Sharp.Tools/C4Sharp.Tools.csproj index 6d838aa..25fda1f 100644 --- a/src/C4Sharp.Tools/C4Sharp.Tools.csproj +++ b/src/C4Sharp.Tools/C4Sharp.Tools.csproj @@ -14,7 +14,7 @@ https://github.com/8T4/c4sharp git c4, diagrams - 2.3.0 + 3.0.0 https://github.com/8T4/c4sharp/blob/main/LICENSE true true diff --git a/src/C4Sharp/C4Sharp.csproj b/src/C4Sharp/C4Sharp.csproj index 142bb57..c1da2af 100644 --- a/src/C4Sharp/C4Sharp.csproj +++ b/src/C4Sharp/C4Sharp.csproj @@ -11,7 +11,7 @@ https://github.com/8T4/c4sharp git c4, diagrams - 6.3.0 + 7.0.0 https://github.com/8T4/c4sharp/blob/main/LICENSE true true diff --git a/src/C4Sharp/Diagrams/Plantuml/PlantumlContext.cs b/src/C4Sharp/Diagrams/Plantuml/PlantumlContext.cs index 643cf51..602460d 100644 --- a/src/C4Sharp/Diagrams/Plantuml/PlantumlContext.cs +++ b/src/C4Sharp/Diagrams/Plantuml/PlantumlContext.cs @@ -88,7 +88,7 @@ public PlantumlContext UseDiagramMermaidBuilder() /// C4 Diagrams /// public void Export(IEnumerable diagrams, IDiagramTheme? theme = null) => - Export(diagrams.Select(d => d.Build(theme ?? new DefaultTheme()))); + InternalExport(diagrams.Select(d => d.Build(theme ?? new DefaultTheme()))); /// /// It creates a Puml file into the default directory "./c4" @@ -97,12 +97,21 @@ public void Export(IEnumerable diagrams, IDiagramTheme? theme = /// /// C4 Diagrams [Obsolete("Use the method with IDiagramBuilder")] - public void Export(IEnumerable diagrams) + public void Export(IEnumerable diagrams) => + InternalExport(diagrams); + + /// + /// It creates a Puml file into the default directory "./c4" + /// If the attribute of Session GenerateDiagramImages is true + /// It generates png files of the diagram + /// + /// C4 Diagrams + private void InternalExport(IEnumerable diagrams) { var dirPath = Directory.GetCurrentDirectory(); var path = Path.Join(dirPath, C4SharpDirectory.DirectoryName); - Export(path, diagrams); - } + InternalExport(path, diagrams); + } /// /// It creates a Puml file into the default directory "./c4" @@ -118,7 +127,7 @@ public void Export(IEnumerable diagrams) /// /// ReSharper disable once MemberCanBePrivate.Global public void Export(string path, IEnumerable diagrams, IDiagramTheme? theme = null) => - Export(path, diagrams.Select(d => d.Build(theme))); + InternalExport(path, diagrams.Select(d => d.Build(theme))); /// /// It creates a Puml file into the default directory "./c4" @@ -133,7 +142,9 @@ public void Export(string path, IEnumerable diagrams, IDiagramT /// /// ReSharper disable once MemberCanBePrivate.Global [Obsolete("Use the method with IDiagramBuilder")] - public void Export(string path, IEnumerable diagrams) + public void Export(string path, IEnumerable diagrams) => InternalExport(path, diagrams); + + private void InternalExport(string path, IEnumerable diagrams) { var enumerable = diagrams as Diagram[] ?? diagrams.ToArray(); From 60d1adb8ddc890ccbeff27ed096ab7502ccfde42 Mon Sep 17 00:00:00 2001 From: yanjustino Date: Fri, 15 Mar 2024 13:29:12 -0300 Subject: [PATCH 2/3] Fixing ContextDiagram.cs --- src/C4Sharp/Diagrams/Builders/ContextDiagram.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/C4Sharp/Diagrams/Builders/ContextDiagram.cs b/src/C4Sharp/Diagrams/Builders/ContextDiagram.cs index 7159c6a..aa48da8 100644 --- a/src/C4Sharp/Diagrams/Builders/ContextDiagram.cs +++ b/src/C4Sharp/Diagrams/Builders/ContextDiagram.cs @@ -6,7 +6,7 @@ namespace C4Sharp.Diagrams.Builders; public abstract class ContextDiagram: DiagramBuilder { protected override string Title { get; } = "Context Diagram"; - protected override DiagramType DiagramType { get; } = DiagramType.Component; + protected override DiagramType DiagramType { get; } = DiagramType.Context; protected EnterpriseBoundary Bound(string alias, string label, params Structure[] structures) => new(alias, label, structures); From 4098c7351955db4d334e74524fdb7f11a698e98f Mon Sep 17 00:00:00 2001 From: yanjustino Date: Sat, 16 Mar 2024 22:14:57 -0300 Subject: [PATCH 3/3] ajuste --- src/C4Sharp/Elements/ContainerType.cs | 3 +++ src/C4Sharp/Elements/Containers/Pipeline.cs | 7 +++++++ 2 files changed, 10 insertions(+) create mode 100644 src/C4Sharp/Elements/Containers/Pipeline.cs diff --git a/src/C4Sharp/Elements/ContainerType.cs b/src/C4Sharp/Elements/ContainerType.cs index cbfba1a..5115763 100644 --- a/src/C4Sharp/Elements/ContainerType.cs +++ b/src/C4Sharp/Elements/ContainerType.cs @@ -48,6 +48,9 @@ public enum ContainerType [Description("Database")] Database, + + [Description("Pipeline")] + Pipeline, [Description("")] None diff --git a/src/C4Sharp/Elements/Containers/Pipeline.cs b/src/C4Sharp/Elements/Containers/Pipeline.cs new file mode 100644 index 0000000..6366efa --- /dev/null +++ b/src/C4Sharp/Elements/Containers/Pipeline.cs @@ -0,0 +1,7 @@ +namespace C4Sharp.Elements.Containers; + +public record Pipeline(string Alias, string Label, string Technology, string? Description = null) + : Container(Alias, Label, ContainerType.Pipeline, Technology, Description); + +public record Pipeline(string Technology, string? Description = null) + : Container(ContainerType.Pipeline, Technology, Description); \ No newline at end of file