Skip to content

Command Line Interface (CLI)

Jump to bottom
Slava Vedernikov edited this page Nov 9, 2024 · 39 revisions

Home   CLI   Samples   Q&A   How‐to guides   Quick‐starts   Tutorials

Overview

The out of the box CLI can be built from C4InterFlow.Cli project. It can be used to generate diagrams from YAML and JSON Architecture as code. See E-Commerce Platform - Yaml sample and Trader X - Json sample.

If your aim is to generate Architecture as Code in C# or YAML from a .NET C# solution or project, then it is recommended to created a C# Console Application per Application Architecture project e.g. DotNetEShop.Cli was created specifically for E-Shop sample .NET application .

The Console Application should reference C4InterFlow.Automation package.

The Program.cs file should contain the following code to take advantage of all CLI Commands already implemented in C4InterFlow.Cli namespace.

using System.CommandLine.Builder;
using System.CommandLine.Parsing;
using C4InterFlow.Cli.Root;
using C4InterFlow.Cli.Commands;
using C4InterFlow.Cli.Extensions;

var rootCommandBuilder = RootCommandBuilder
    .CreateDefaultBuilder(args)
    .Configure(context =>
    {
        context.Add<DrawDiagramsCommand>();
        context.Add<QueryUseFlowsCommand>();
        context.Add<QueryByInputCommand>();
        context.Add<ExecuteAaCStrategyCommand>();
    });

await new CommandLineBuilder(rootCommandBuilder.Build())
    .UseDefaults().UseLogging().Build().InvokeAsync(args);

All custom AaC Read/Write Strategies can also be implemented in this Console Application e.g. CSharpToCSharpBasketApiAaCGenerator, CSharpToYamlBasketApiAaCGenerator etc.

Commands

All command support -?, -h, --help option that shows help and usage information.

Generating Architecture as Code (AaC)

Use execute-aac-strategy command to generate AaC in either C#, YAML or JSON. AaC can be generated either from C# source code or from CSV Architecture Catalogue making the following four scenarios possible:

  1. Generating C# AaC from C# source code
  2. Generating C# AaC from CSV Architecture Catalogue
  3. Generating YAML AaC from C# source code
  4. Generating YAML AaC from CSV Architecture Catalogue
  5. Generating JSON AaC from CSV Architecture Catalogue

NOTE: More scenarios may be supported out-of-the-box in the future. C4InterFlow is using Strategy pattern and Generic interfaces, which allow for custom implementations of any unsupported scenarios.

Usage

DotNetEShop.Cli execute-aac-strategy [options]

Options

AaC Root Namespace

-aac-rn, --aac-root-namespace: Architecture As Code root Namespace. (Required).

AaC Output Path

-aac-outp, --aac-output-path: The path to the Architecture As Code output (Required).

AaC Writer Strategy

-aac-ws, --aac-writer-strategy: The full Type name of the Architecture As Code Writer Strategy to execute (Required).

AaC Strategy Parameters

-ps, --params: The key/value pairs of additional command parameters.

NOTE: AaC Strategy parameters are spesific for each Strategy e.g. any AaC generators that ultimately extend C4InterFlow.Automation.CSharpToAnyAaCStrategy would require software-system-source-path and software-system-name parameters.

Usage Examples

Example 1

DotNetEShop.Cli execute-aac-strategy --aac-root-namespace DotNetEShop --aac-output-path DotNetEShop\DotNetEShop.csproj --aac-writer-strategy "DotNetEShop.Cli.CSharpToCSharpBasketApiAaCGenerator, DotNetEShop.Cli" --params software-system-source-path="C:\Repos\eShop-main\src\Basket.API\Basket.API.csproj" --params software-system-name="BasketApi"

Example 2

DotNetEShop.Cli execute-aac-strategy --aac-root-namespace DotNetEShop --aac-output-path DotNetEShop\DotNetEShop\Yaml --aac-writer-strategy "DotNetEShop.Cli.CSharpToYamlCatalogApiAaCGenerator, DotNetEShop.Cli" --params software-system-source-path="C:\Repos\eShop-main\src\Catalog.API\Catalog.API.csproj" --params software-system-name="CatalogApi"

Drawing diagrams

Use draw-diagrams command to draw diagrams of different Types, Scopes and Level of Details using AaC in either C#, YAML or JSON.

Usage

C4InterFlow.Cli draw-diagrams [options]

Options

AaC Input Paths

-aac-inp, --aac-input-paths: The path to the Architecture As Code input (Required).

AaC Reader Strategy

-aac-rs, --aac-reader-strategy: The full Type name of the Architecture As Code Reader Strategy to use (Required).

Interfaces

-i, --interfaces: The aliases of the interfaces to be used as input for a Command. Multiple values are allowed.

Interfaces input file

-iif, --interfaces-input-file The file where the aliases of the Interfaces, which are intended to be used as input for a Command, can be loaded from.

Business processes

-bp, --business-processes: The aliases of Business Process for which to draw the Diagram(s). Multiple values are allowed.

Scopes

-s, --scopes: Scopes of Diagram(s) to draw. Multiple values are allowed. Default: * (all Scopes).

Possible values:
business-process
component
component-interface
container
container-interface
software-system
software-system-interface
namespace
all-software-systems

Types

-t, --types: Types of Diagram(s) to draw. Multiple values are allowed. Default: * (all Types).

Possible values:
c4
c4-static
c4-sequence
sequence

Levels of Details

-l, --levels-of-details: Levels of Details of the Diagram(s). Multiple values are allowed. Default: * (all Levels of Details).

Possible values:
component
container
context

Show Interface Input/Output

-siinout, --show-interface-input-output: Show Interface Input and Output. Default: False.

NOTE: This option is used for component Level of Details only.

Output Directory

-od, --output-dir: The output directory for the current command. Default: Current working directory (Required).

Name Prefix

-np, --name-prefix: The name prefix for a Diagram.

Formats

-f, --formats: Diagram format(s) to draw. Multiple values are allowed.

NOTE: Diagram(s) in puml format are always generated by default .

Possible values:
png
svg
md

Usage Examples

Example 1

C4InterFlow.Cli draw-diagrams --aac-input-paths DotNetEShop.dll --aac-reader-strategy "C4InterFlow.Automation.Readers.CSharpAaCReaderStrategy,C4InterFlow.Automation" --interfaces DotNetEShop.SoftwareSystems.*.Containers.*.Components.*.Interfaces.*

This command will generate diagrams of all Types, all Scopes and all Levels of Details for all Interfaces of all Components of all Containers of all Software Systems in DotNetEShop Namespace. It will use C# AaC (aac-reader-strategy) that is compiled as DotNetEShop.dll (aac-input-paths)

Example 2

C4InterFlow.Cli draw-diagrams --aac-input-paths "DotNetEShop\Yaml" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --interfaces DotNetEShop.SoftwareSystems.BasketApi.Containers.*.Components.*.Interfaces.* DotNetEShop.SoftwareSystems.CatalogApi.Containers.*.Components.*.Interfaces.* --types sequence --formats svg

This command will generate Plant UML - Sequence diagrams of Component interface Scope and all Levels of Details for all Interfaces of all Components of all Containers of BasketApi and CatalogApi Software Systems in DotNetEShop Namespace. It will use YAML AaC (aac-reader-strategy) that is saved in .yaml files located in DotNetEShop\Yaml directory (aac-input-paths)

Generating Documentation

Use generate-documentation command to generate documentation using Liquid templates based on AaC data in either C#, YAML or JSON.

Usage

C4InterFlow.Cli generate-documentation [options]

Options

AaC Input Paths

-aac-inp, --aac-input-paths: The path to the Architecture As Code input (Required).

AaC Reader Strategy

-aac-rs, --aac-reader-strategy: The full Type name of the Architecture As Code Reader Strategy to use (Required).

Structures

-st, --structures: The aliases of the structures to be used as input for a Command. Multiple values are allowed (Required).

Templates Directory

-td, --templates-dir: The directory where documentation templates for structures can be found (Required).

The command expects the following directory/file structure inside the Templates Directory:

Software Systems
  <FILE_NAME>.liquid
  Containers
    <FILE_NAME>.liquid
    Components
      <FILE_NAME>.liquid

It will use the relevant template for each structure type e.g. Software Systems\<FILE_NAME>.liquid for all Software Systems, Software Systems\Containers\<FILE_NAME>.liquid for all Containers etc.

The documentation files will be saved with template's <FILE_NAME> e.g. when Software Systems\README.liquid template is used with --file-extension "md" option (see below), then README.md file will be created.

Output Directory

-od, --output-dir: The output directory for the current command. Default: Current working directory (Required).

File Extension

-fe, --file-extension: The file extension of the artifact used/generated by the command (Required).

Usage Examples

Example 1

C4InterFlow.Cli generate-documentation --structures BigBankPlc.SoftwareSystems.* BigBankPlc.SoftwareSystems.*.Containers.* --templates-dir ".\Templates" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --aac-input-paths ".\Architecture" --output-dir ".\Diagrams\BigBankPlc" --file-extension "md"

This command will generate .md documentation for all Software Systems and Containers in BigBankPlc Namespace. It will use Yaml AaC (aac-reader-strategy) and Liquid templates located in .\Templates directory.

Publishing Diagrams and Documentation

Use publish-site command to publish all Diagrams and Documentation as a website.

Usage

C4InterFlow.Cli publish-site [options]

Options

Site Source Directory

-ssd, --site-source-dir: The directory where site source can be found (Required).

Output Directory

-od, --output-dir: The output directory for the current command (Required).

Site Content Sub-Directories

-scsds, --site-content-sub-dirs: The sub-directories where site content can be found. Multiple values are allowed (Required).

Site No-Sitemap Sub-Directories

-snssds, --site-no-sitemap-sub-dirs: The sub-directories that should be excluded from a sitemap. Multiple values are allowed.(Required).

Diagram Formats

-f, --formats: Diagram format(s) to publish. Multiple values are allowed.

Batch File

-bf, --batch-file: The path to .bat (batch) file to be executed by the command. Default: build.bat

Site Build Directory

-sbd, --site-build-dir: The directory where built site can be found. Default: build

Environment Variables

-ev, --environment-variables: The expressions to be used to set environment variables before external batch file is executed e.g. SOME_VARIABLE=some-value.

Usage Examples

Example 1

publish-site --site-source-dir "C:\C4InterFlow\Publishers\StaticSite" --output-dir "C:\architecture-as-code-samples-visualiser\e-commerce-platform" --environment-variables "HOMEPAGE=architecture-as-code-samples-visualiser/e-commerce-platform" --site-content-sub-dirs "ECommercePlatform" ".c4s" --site-no-sitemap-sub-dirs ".c4s"

This command will build a static website using a template source code located in C:\C4InterFlow\Publishers\StaticSite directory and publish it to C:\architecture-as-code-samples-visualiser\e-commerce-platform directory.

Querying Architecture as Code (AaC)

Use query-use-flows command to finds all interface(s) that Use given interface(s) in their Flows.

Usage

C4InterFlow.Cli query-use-flows [options]

Options

Interfaces

-i, --interfaces: The aliases of the interfaces to be used as input for a Command. Multiple values are allowed.

Recursive

-r, --recursive: Indicates if the Query should be executed recursively. Default: False.

  • Non-recursive Query will return only the immediate (first) instance of a given Interface being Used in a Flow by another Interface.
  • Recursive Query will follow the whole Use Flow tree upwards, and will return only the top-most Interface from it.

Query Output File

-qof, --query-output-file: The name of the file where the Query results should be saved.

NOTE: If a value for this option is not provided, CLI will output Query results to Console.

Append

-a, --append: Append Query results to an output file. Default: False.

AaC Input Paths

-aac-inp, --aac-input-paths: The path to the Architecture As Code input (Required).

AaC Reader Strategy

-aac-rs, --aac-reader-strategy: The full Type name of the Architecture As Code Reader Strategy to use (Required).

Include Self

-incls, --include-self: Is Interface queried by included in the query result. Default: False.

Usage Examples

Give the Interface DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.UpdateBasket with the following AaC definition

DotNetEShop:
  SoftwareSystems:
    BasketApi:
      Containers:
        Grpc:
          Components:
            BasketService:
              Interfaces:
                UpdateBasket:
                  Label: Update Basket
                  Description: ''
                  Path: ''
                  IsPrivate: false
                  Protocol: ''
                  Flows:
                  - Type: If
                    Expression: string.IsNullOrEmpty(userId)
                    Flows:
                    - Type: Use
                      Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.ThrowNotAuthenticated
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.MapToCustomerBasket
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync
                  - Type: If
                    Expression: response is null
                    Flows:
                    - Type: Use
                      Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.ThrowBasketDoesNotExist
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.MapToCustomerBasketResponse

And the Interface DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync with the following AaC definition

DotNetEShop:
  SoftwareSystems:
    BasketApi:
      Containers:
        Data:
          Components:
            RedisBasketRepository:
              Interfaces:
                UpdateBasketAsync:
                  Label: Update Basket Async
                  Description: ''
                  Path: ''
                  IsPrivate: false
                  Protocol: ''
                  Flows:
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.GetBasketKey
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync
                  - Type: Use
                    Expression: DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.GetBasketAsync

Example 1

When the following command is executed

C4InterFlow.Cli query-use-flows --aac-input-paths "DotNetEShop\Yaml" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --interfaces DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync

Then the following result will be returned

DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync

Example 2

When the following command is executed

C4InterFlow.Cli query-use-flows --aac-input-paths "DotNetEShop\Yaml" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --interfaces DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync --include-self

Then the following result will be returned

DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync
DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync

Example 3

When the following command is executed

C4InterFlow.Cli query-use-flows --aac-input-paths "DotNetEShop\Yaml" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --interfaces DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync --include-self --recursive

Then the following result will be returned

DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync
DotNetEShop.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.UpdateBasket
DotNetEShop.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync

Home   CLI   Samples   Q&A   How‐to guides   Quick‐starts   Tutorials

Note: This document is subject to change. Users are encouraged to check back regularly for updates.

Clone this wiki locally