Skip to content

Command Line Interface (CLI)

Jump to bottom
Slava Vedernikov edited this page Aug 7, 2024 · 39 revisions

Overview

At the moment it is recommended to created a C# Console Application per Application Architecture project e.g. dotnet.eShop.Architecture.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 C4InterFlow.Cli.Root;
using C4InterFlow.Cli.Commands;

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

await root.Run();

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

dotnet.eShop.Architecture.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

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

Example 2

dotnet.eShop.Architecture.Cli execute-aac-strategy --aac-root-namespace dotnet.eShop.Architecture --aac-output-path dotnet.eShop.Architecture\dotnet.eShop.Architecture\Yaml --aac-writer-strategy "dotnet.eShop.Architecture.Cli.CSharpToYamlCatalogApiAaCGenerator, dotnet.eShop.Architecture.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).

Output Sub-Directory

-osd, --output-sub-dir | The sub-directory where the Diagram(s) should be saved.

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 dotnet.eShop.Architecture.dll --aac-reader-strategy "C4InterFlow.Automation.Readers.CSharpAaCReaderStrategy,C4InterFlow.Automation" --interfaces dotnet.eShop.Architecture.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 dotnet.eShop.Architecture Namespace. It will use C# AaC (aac-reader-strategy) that is compiled as dotnet.eShop.Architecture.dll (aac-input-paths)

Example 2

C4InterFlow.Cli draw-diagrams --aac-input-paths "dotnet.eShop.Architecture\Yaml" --aac-reader-strategy "C4InterFlow.Automation.Readers.YamlAaCReaderStrategy,C4InterFlow.Automation" --interfaces dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.*.Components.*.Interfaces.* dotnet.eShop.Architecture.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 dotnet.eShop.Architecture Namespace. It will use YAML AaC (aac-reader-strategy) that is saved in .yaml files located in dotnet.eShop.Architecture\Yaml directory (aac-input-paths)

Generate 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.

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 dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.UpdateBasket with the following AaC definition

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

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

dotnet:
  eShop:
    Architecture:
      SoftwareSystems:
        BasketApi:
          Containers:
            Data:
              Components:
                RedisBasketRepository:
                  Interfaces:
                    UpdateBasketAsync:
                      Label: Update Basket Async
                      IsPrivate: false
                      Flows:
                      - Type: Use
                        Expression: dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync
                      - Type: Use
                        Expression: dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.GetBasketKey
                      - Type: Use
                        Expression: dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.GetBasketAsync

Example 1

When the following command is executed

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

Then the following result will be returned

dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync

Example 2

When the following command is executed

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

Then the following result will be returned

dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisDatabase.Interfaces.StringSetAsync
dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync

Example 3

When the following command is executed

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

Then the following result will be returned

dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Grpc.Components.BasketService.Interfaces.UpdateBasket
dotnet.eShop.Architecture.SoftwareSystems.BasketApi.Containers.Data.Components.RedisBasketRepository.Interfaces.UpdateBasketAsync
Clone this wiki locally