From 4b15c05c66fd7833d6bff81609414b9c2d68781f Mon Sep 17 00:00:00 2001 From: Yan Justino Date: Fri, 17 Nov 2023 21:41:01 -0300 Subject: [PATCH] Update README.md --- README.md | 72 +++++++++++++++---------------------------------------- 1 file changed, 19 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 792506e..eb3e1f2 100644 --- a/README.md +++ b/README.md @@ -3,30 +3,23 @@

- -

- -C4Sharp (`C4S`) is a .net library for building diagram as code, based on [C4 Model](https://c4model.com/). It's works +C4Sharp (`C4S`) is a .net library for building diagrams as code, based on [C4 Model](https://c4model.com/). It works like a superset of [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) through which developers can create, share, and consume [C4 Model diagrams](https://c4model.com/) as code (C#) such as Context, Container, Component and -Deployment diagrams. The library generates the following diagram types: - -![](https://img.shields.io/badge/-png-green) -![](https://img.shields.io/badge/-svg-green) -![](https://img.shields.io/badge/-puml-green) -![](https://img.shields.io/badge/-mermaid-green) - -

+Deployment diagrams. The library generates the following diagram types: PNG, SVG, PUML, MERMAID +>[!NOTE]\ +> The C4 model is an easy-to-learn, developer-friendly approach to software architecture diagramming. Good software architecture diagrams assist with communication inside/outside of software development/product teams, efficient onboarding of new staff, architecture reviews/evaluations, risk identification (e.g. risk-storming), threat modeling (e.g. STRIDE/LINDDUN), etc. +> [SIMON BROWN](https://twitter.com/simonbrown) -# GETTING STARTED +>[!IMPORTANT] +> There are benefits to using these tools over the heavier alternatives, including easy version control and the ability to generate the DSLs from many sources. ools in this space that we like include Diagrams, Structurizr DSL, AsciiDoctor Diagram and stables such as WebSequenceDiagrams, PlantUML and the venerable Graphviz. It's also fairly simple to generate your own SVG these days, so don't rule out quickly writing your own tool either. One of our authors wrote a small Ruby script to quickly create SVGs, for example. +> [Thoughtworks Technology Radar](https://www.thoughtworks.com/en-br/radar/techniques/diagrams-as-code) -> The C4 model is an easy to learn, developer friendly approach to software architecture diagramming. Good software architecture diagrams assist with communication inside/outside of software development/product teams, efficient onboarding of new staff, architecture reviews/evaluations, risk identification (e.g. risk-storming), threat modelling (e.g. STRIDE/LINDDUN), etc. -> [SIMON BROWN](https://twitter.com/simonbrown) +# Getting Started -### Installing -Fist, you will need the [.NET 5.0+](https://docs.microsoft.com/pt-br/dotnet/standard/net-standard) -and [Java](https://www.java.com/en/download/) to run C4Sharp. Also, you should install C4Sharp package in your project. +First, you will need the [.NET 5.0+](https://docs.microsoft.com/pt-br/dotnet/standard/net-standard) +and [Java](https://www.java.com/en/download/) to run C4Sharp. Also, you should install the C4Sharp package in your project. This package is available through [Nuget Packages](https://www.nuget.org/packages/C4Sharp). | Package | Description | Version | Downloads | Maintainability | Status | @@ -34,15 +27,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) | -# DIAGRAM AS CODE -> There are benefits to using these tools over the heavier alternatives, including easy version control and the ability to generate the DSLs from many sources. ools in this space that we like include Diagrams, Structurizr DSL, AsciiDoctor Diagram and stables such as WebSequenceDiagrams, PlantUML and the venerable Graphviz. It's also fairly simple to generate your own SVG these days, so don't rule out quickly writing your own tool either. One of our authors wrote a small Ruby script to quickly create SVGs, for example. -> [Thoughtworks Technology Radar](https://www.thoughtworks.com/en-br/radar/techniques/diagrams-as-code) - -### Coding 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: ```C# -namespace C4Bank.Deposit.Architecure; +namespace C4Bank.Deposit.Architecture; public class ContainerDiagram : DiagramBuildRunner { @@ -80,14 +68,11 @@ public class ContainerDiagram : DiagramBuildRunner }; } ``` -Code 1 - container diagram as code -### Compiling There are two strategies for compiling diagrams in your project: self-compiling and using the `C4SCLI` tool. #### a) self-compiling approach: -Code the following structure into `program.cs`. In this approach, it is preferable that you use a separate project. ```c# internal static class Program { @@ -105,12 +90,12 @@ internal static class Program } } ``` -Code 2 - self-compiling approach see the complete code [here](./samples/Basic/C4Sharp.Sample/Program.cs) #### b) Using the C4SCLI tool: -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: +> [!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: ```shell $ c4scli build [-o ] ``` @@ -119,42 +104,24 @@ see the following sample ```bash $ mkdir assets $ c4scli build /src/c4sharp.sln -o /c4 - ... C4 diagram PNG files C4 diagram generated: file:////c4/internet-banking-system-api-application-c4component.png -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4context.png -C4 diagram generated: file:////c4/container-diagram-for-internet-banking-system-c4container.png -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4deployment.png -C4 diagram generated: file:////c4/system-enterprise-diagram-for-internet-banking-system-c4context.png C4 diagram SVG files C4 diagram generated: file:////c4/internet-banking-system-api-application-c4component.svg -C4 diagram generated: file:////c4/system-enterprise-diagram-for-internet-banking-system-c4context.svg -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4deployment.svg -C4 diagram generated: file:////c4/container-diagram-for-internet-banking-system-c4container.svg -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4context.svg C4 diagram MD files C4 diagram generated: file:////c4/internet-banking-system-api-application-c4component.mermaid.md -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4context.mermaid.md -C4 diagram generated: file:////c4/container-diagram-for-internet-banking-system-c4container.mermaid.md -C4 diagram generated: file:////c4/system-enterprise-diagram-for-internet-banking-system-c4context.mermaid.md C4 diagram PUML files -C4 diagram generated: file:////c4/system-enterprise-diagram-for-internet-banking-system-c4context.puml C4 diagram generated: file:////c4/internet-banking-system-api-application-c4component.puml -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4context.puml -C4 diagram generated: file:////c4/container-diagram-for-internet-banking-system-c4container.puml -C4 diagram generated: file:////c4/system-context-diagram-for-internet-banking-system-c4deployment.puml ``` +>[!WARNING] +> only compatible with projects using c4sharp version 5.0+ -⚠️ *only compatible with projects using c4sharp version 5.0+* - - -### The Result The previous steps will result in the following image: ![img](./docs/images/c4bank-deposit-area-c4container.png) @@ -174,7 +141,6 @@ protected override IElementStyle? SetStyle() ![img](./docs/images/c4bank-deposit-area-c4container-bw.png) -## Compiling Mermaid Markdown 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# @@ -221,11 +187,11 @@ Rel(BankingSystem, Mainframe, "uses") See the complete code [here](./docs/system-enterprise-diagram-for-internet-banking-system-c4context.mermaid.md). -# LEARN +# Learn - See more in our [sample code](./samples): - To learn more about `C4S` access our [wiki](https://github.com/8T4/c4sharp/wiki). -# THANKS +# Thanks ### C4 community @@ -245,7 +211,7 @@ See the complete code [here](./docs/system-enterprise-diagram-for-internet-banki - 🤝 [Rafael Santos](https://www.linkedin.com/in/rafael-santos-0b51465) - 🤝 [Marcus Vinicius Santana Silva](https://github.com/Lowpoc#marcus-vinicius-santana-silva-lowpoc-) -## Guide to contributing to a GitHub project +# Guide to contributing to a GitHub project This is a guide to contributing to this open source project that uses GitHub. It’s mostly based on how many open sorce projects operate. That’s all there is to it. The fundamentals are: