README.md

Lively 🌳

Living Documentation

Example yumlmd ouput for this repository:

How does it work?

Lively uses reflection to create a tree of class dependencies for given types in an assembly.

By default it uses the Startup file to load and resolve which type is registered to an interface.

There are a few different output formats that can be configured, the default is yumlmd.

How can I use it?

It is available as a GitHub Action and a Nuget package.

GitHub Action

Available here.

The GitHub action is defined in ./action.yml and uses the Dockerfile in the root of the project.

Example outputs can be found here

Example worflow

name: Use GitHub Action

on: push

jobs:

  generate_examples:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-dotnet@v1

    - name: Build project
      run: dotnet build -c Release

    - name: Generate yuml
      id: generate_yuml
      uses: maisiesadler/lively@v1.0.3-gh-action-test.0
      env:
        ASSEMBLY_LOCATION: './src/Lively/bin/Release/net5.0/Lively.dll'
        ROOT_TYPES: 'Lively.DependencyTree'
        INTERFACE_RESOLVER: None
        OUTPUT_FORMAT: yuml

    - name: Write outputs to file
      shell: bash
      run: |
        echo '${{ steps.generate_yuml.outputs.result }}' > example-outputs/yuml.yum

    - uses: EndBug/add-and-commit@v7
      name: Commit Changes
      with:
        default_author: github_actions
        message: 'Generate diagrams'

Nuget

• Lively
• Lively.Diagrams

Create a custom application using the Nuget package.

var assemblyLocation = "...";
var className = "YourAssembly.RootClassName";
var assembly = Assembly.LoadFrom(assemblyLocation);
var config = new DependencyTreeConfig(assembly, applicationConfig.AssemblyConfiguration)
{
    // Add your own interface resolver
    CreateInterfaceResolver = new CustomInterfaceResolver(),
    SkipTypes = new HashSet<string> { "Microsoft.Extensions.Options.IOptions" },
    StartupName = "CustomStartupName",
};

var tree = new DependencyTree(config);
var node = tree.GetDependencies(className);

// Use diagrams package or create own output
var diagram = MermaidMd.Create(new [] { node });
System.Console.WriteLine(diagram);

Configuration

Name	Environment Variable	CLI setting		Required
Assembly Location	ASSEMBLY_LOCATION	-a --assembly	The assembly file location or directory containing assemblies to load	Yes
Assembly Pattern Match	ASSEMBLY_PATTERN_MATCH	--pattern-match	Regex pattern of assemblies to load in directory	No
Root types	ROOT_TYPES	-t --root-types	The root type to use for the dependency tree, multiple values can be used as a csv input	Yes
Skip types	SKIP_TYPES	-s --skip-types	Types to not include in diagram, multiple values can be used as a csv input	No
Assembly Config Location	ASSEMBLY_CONFIG_LOCATION	--assembly-config	The location of the configuration file required to build IConfiguration for Startup	No
Interface Resolver Type	INTERFACE_RESOLVER	-i --interface-resolver	Method for resolving interfaces, Allowed Values: None, Startup. Default: Startup.	No
Startup Name	STARTUP_NAME	--startup-name	Startup Type Name or FullName. Default: Startup.	No
Output Format	OUTPUT_FORMAT	--output-format	Format to print out the result. Allowed values: debug, yumlmd, yuml, mermaid, mermaidmd, plantuml. Default: yumlmd.	No
Application Config Location	APPLICATION_CONFIG_LOCATION	-c --config	The location of application config file	No

Application config

There is support for passing in a config file for multiple Skip or Generate (root) types.

Example

Interface Resolver Type

If Interface Resolver is Startup (default) then the application will look for a class named Startup.

If the Startup file has an IConfiguration constructor then set the Assembly Config Location to the path of an example config file that has enough data in it to build the configuration.

If there is no startup then set Interface Resolver to None.

The Startup file name can be overriden to either the type Name or FullName. E.g. TestStartup or Lively.MultipleApplications.Startup.

Diagrams

yumlmd is the default output format for the GitHub Action

UML

yUML

There are 2 output formats using yUML, yuml and yumlmd.

• yuml - creates a yUML diagram that can be parsed by this vscode extension which produces a SVG
• yumlmd - creates a URL that is dynamically created into an image by yuml.me which can then be displayed in a html document

PlantUML

PlantUML

• plantuml

Mermaid

Mermaid is a javascript based diagramming and charting tool. There are a few vscode extensions that can be used to view the diagrams locally and a chrome extension that can be added to view the diagrams in GitHub.

• mermaid - mermaid diagram
• mermaidmd - mermaid diagram with mermaid syntax that can be rendered by vscode/chrome extension in a markdown file

Example applications

Pokedex - dotnet5 web api

Example workflow

• Needed to publish a single file application dotnet publish -r linux-x64 -p:PublishSingleFile=true -p:UseAppHost=true --self-contained
• Need to add RuntimeIdentifiers here.

Example output

Endpoints - doesn't use Startup

Example workflow

Example output