Skip to content

Commit

Permalink
Merge pull request #42 from 8T4/yanjustino-patch-1
Browse files Browse the repository at this point in the history 
Update README.md
  • Loading branch information
@yanjustino
yanjustino committed Nov 18, 2023
2 parents 8c90746 + 4b15c05 commit 7229d5a
Showing 1 changed file with 19 additions and 53 deletions.
72 changes: 19 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,46 +3,34 @@
</p>



<p align="center">

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)

</p>
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 |
|---------|--------------------------------------|------------------------------------------------------------------------------------------------| ----- |----- |----- |
|`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&amp;utm_medium=referral&amp;utm_content=8T4/c4sharp&amp;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&amp;utm_medium=referral&amp;utm_content=8T4/c4sharp&amp;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
{
Expand Down Expand Up @@ -80,14 +68,11 @@ public class ContainerDiagram : DiagramBuildRunner
};
}
```
<small><strong>Code 1</strong> - container diagram as code</small>

### 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
{
Expand All @@ -105,12 +90,12 @@ internal static class Program
}
}
```
<small><strong>Code 2</strong> - self-compiling approach</small>
<small>see the complete code [here](./samples/Basic/C4Sharp.Sample/Program.cs)</small>

#### 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 <solution path> [-o <output path>]
```
Expand All @@ -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)
Expand All @@ -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#
Expand Down Expand Up @@ -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

Expand All @@ -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:
Expand Down

0 comments on commit 7229d5a

Please sign in to comment.