dotmorten / dotnetomdgenerator

A Roslyn-based cross-platform tool that generates an object model diagram from a set of C# source files or assemblies

.NET Object Model Diagram Generator

A cross-platform Roslyn-based tool that generates an object model diagram of a set of C# source files and/or .NET assemblies

Sponsoring

If you like this library and use it a lot, consider sponsoring me. Anything helps and encourages me to keep going.

See here for details: https://github.com/sponsors/dotMorten

Install

Run the following command from commandline (requires .NET Core 2.1 installed):

dotnet tool install --global dotMorten.OmdGenerator

Usage:

generateomd /source=[source folder] /compareSource=[oldSourceFolder] /preprocessors=[defines] /format=[html|image] /showPrivate /showInternal

Required parameters:
  source            Specifies the folder of source files to include for the object model.
                    Separate with ; for multiple folders
or
  assemblies        Specifies a set of assemblies to include for the object model.
                    Separate with ; for multiple assemblies, or use wildcards
				
Optional parameters:
  compareSource     Specifies a folder of old source to compare and generate a diff model
                    This can be useful for finding API changes or compare branches
  compareAssemblies Specifies a set of old assemblies to compare and generate a adiff model.
                    Separate with; for multiple assemblies, or use wildcards
  format            Format to generate: 
                       'html' a single html output (html is default)
                       'md' for markdown you can copy-paste to for instance GitHub.
		       Specify multiple with a semicolon seperator, and use an output filename without extension
  preprocessors     Define a set of preprocessors values. Use ; to separate multiple
  exclude           Defines one or more strings that can't be part of the path Ie '*/Samples/*;*/UnitTests/*'
                    (use forward slash for folder separators)
  regexfilter       Defines a regular expression for filtering on full file names in the source
  showPrivate       Show private members (default is false)
  showInternal      Show internal members (default is false)
  output            Filename to write the output to (extension is optional, but exclude the extension if you specify multiple formats)

NuGet

As an alternative you can also reference a NuGet package to your class library, and set up a post-build script to generate an Object Model Diagram HTML file:

Install-Package dotMorten.OmdGenerator 

Add the following to your project:

  <Target Name="GenerateObjectModel" AfterTargets="Compile">
    <Exec Command="dotnet &quot;$(DotNetOMDGeneratorToolPath)&quot; /source=&quot;@(Compile)&quot; /preprocessors=&quot;$(DefineConstants)&quot; /output=&quot;$(OutputPath)$(TargetName)&quot;" WorkingDirectory="$(ProjectDir)" />
  </Target>
 

An example of a generated output for all of .NET Core can be found here.

It can also be used to compare two folders (for instance two separate branches) and only show changes to the API. Here's an example of .NET CoreFX v2.0 vs Master.

Examples

Generate OMD for .NET Core FX source code, and ignore ref and test folders:

generateomd /source=c:\github\dotnet\corefx\src /exclude="*/ref/*;*/tests/*;*/perftests/*"

Compare .NET CoreFX Master with v2.0.0 repo branches directly from their Github zipped downloads:

generateomd /source=https://github.com/dotnet/corefx/archive/master.zip /compareSource=https://github.com/dotnet/corefx/archive/release/2.0.0.zip /exclude="*/ref/*;*/tests/*;*/perftests/*"

What's new in Xamarin.Forms? Compare assemblies from the nuget cache:

generateomd /assemblies=%USERPROFILE%\.nuget\packages\xamarin.forms\3.3.0.912540\lib\netstandard2.0\*.dll /compareAsssemblies=%USERPROFILE%\.nuget\packages\xamarin.forms\3.2.0.871581\lib\netstandard2.0\*.dll

dotnetomdgenerator's Issues

Suggestion: Sort the properties and methods by name and the constructors by # of parameters

May be a nice enhancement to sort the constructors by number of parameters and the properties and methods by name.

foreach (var method in type.GetConstructors(oldType).OrderBy(m => m.Item1.Parameters.Count()))
foreach (var method in type.GetProperties(oldType).OrderBy(m => m.Item1.Name))
etc.

Add support for generating diff-OMDs between two branches or folders

Compare two sets of source folders (or branches) and only generate the parts of the OMD that adds or removes objects and members.

Add support for .csproj and .sln project/solutions

Challenge: This change requires a nuget package that isn't working cross-platform.

Add search/filtering to HTML OMD

It would be useful to be able to quickly filter the HTML diagram by name, namespace, usage etc.

Suggestion: Add support for nested classes

Currently these are not displayed.

Add grouping support to HTML OMD

It would be useful to be able to quickly group/reorder objects by namespaces.

Test out generating SVGs instead for HTML diagrams

Suggestion by @jongalloway. Example snippet here: https://codepen.io/jongalloway/pen/bvgvWN

Add dotnet tool support the Generator

Add dotnet tool support,
so anybody can use it directly after installation from nuget from the shell.

https://docs.microsoft.com/de-de/dotnet/core/tools/dotnet-tool-install

Hier is a list with of other dotnet tools
https://github.com/natemcmaster/dotnet-tools

Add Mermaid output for markdown support

Generate mermaid output, for easier integration into GitHub:
See github/roadmap#372

Mermaid spec:
https://mermaid-js.github.io/mermaid/#/classDiagram

Live editor sample:
https://mermaid.live/edit/#pako:eNptkU1PwzAMhv9KlBOI9Q9UuyC2SRx22m2KhNzEdFbzAfnQBKP_nbSlYXT4ZD-OX72xL1w6hbzmUkMIG4LWgxGW5Xi0ZECz9VdVsU2S3S3dUTjd0iM2Hv7gmj2QjQxaXOJD9GRb1qJV6K-bw0jYg8np3f2iYSDiDEfbo73LBFgRbRC6J6edL41wJjMP5vI9gezmur_WGz5W9KrBe6BPfLY7xFiwBLuF-O_8uIJfQ41zmlF4OZNWBfpkF7Nz8BU36A2QyncZVQSPJzQoeJ1Tha-QdBRc2D4_TW8q72OrKDrP6-gTrjik6A4fVs719ObnuhPsvwES3pny

Suggestion: Use the new Tuple syntax with names

e.g.

    public static IEnumerable<(IMethodSymbol symbol, bool wasRemoved)> GetConstructors(this INamedTypeSymbol type, INamedTypeSymbol oldType)
    {
        if (oldType == null || type == null)
            return GetConstructors(type ?? oldType).Select(p => (p, type == null));
        var newMembers = GetConstructors(type);
        var oldMembers = GetConstructors(oldType);
        return newMembers.Except(oldMembers, Generator.MethodComparer.Comparer).Select(p => (p, false))
            .Union(oldMembers.Except(newMembers, Generator.MethodComparer.Comparer).Select(p => (p, true)))
            .OrderBy(t => t.symbol.Name);
    }

And none of that nasty Item1, Item2 stuff.

`private protected` members are not handled correctly

Treated as public, when it's internal only. Icon is also missing.

public static fields aren't shown

By design?

e.g.
public static List RegisteredFunctions = new List()...

Add support for comparing DLLs and WinMD files.

Since Roslyn can treat compiled binaries the same way, it should be a simple matter to add these.

Add support for delegate

Delegates are not currently rendered

Add support for XML comments

Would be nice if XML comments could flow through to the HTML, maybe as tooltips on each of the elements.

Is there a way to extend the code so that it also works with C# script?

Hi,

I'm using C# scripts in my application that are compiled by Roslyn. Because it are scripts the outer part of the script does not contain a class. So when I now try your tool it will always end up empty.

A C# script looks like this... it's entry point is Main()

using System;
using System.Collections.Generic;

// Wordt gebruikt door de GetPolisNumbersFromAttachments methode
private string _attachmentsText = null;

private struct DefinedFields
{
	public bool Found;
	public string Folder;
	public string DocumentInhoud;
	public string Zoekgegeven;
}

private string Property1
{
    get 
	{
		return "Hello";
	}
}


private string Method1(string prop1)
{
	return "Hello from method 1"
}

public void Main()
{
}

I'm trying to generate an OMD for this. But because there is no class around this it is always empty.

I already tried to do it this way

class Script { " + script + " }

But then I still don't have any methods