使用Roslyn的C#语言服务实现UML类图的自动生成

时间：2024-03-08 14:52:45

最近在项目中实现了一套基于Windows Forms的开发框架，个人对于本身的设计还是比较满意的，因此，打算将这部分设计整理成文档，通过一些UML图形比如类图（Class Diagram）来描述整个框架的设计。然而，并没有找到一款合适的UML设计工具，商用版的功能强大，但即便是个人许可，一个License也不下千元；免费社区版的UML工具中，draw.io可以推荐一下，画出的图表看上去都非常专业，然而对于UML图的支持不算特别好，画起来也不太方便；有一款比较好的：Astah Community，虽然使用比较方便，但是面对着复杂的类之间的关系，要一个个手工去画，显得非常麻烦而且容易出错。总而言之，并没有找到一个合适的方法，能够快速准确地产生专业的UML类图，归根结底，还是“穷”+“懒”。

PlantUML

在网上搜索调研各个UML制图工具的时候，发现了PlantUML，个人觉得它的设计理念是非常好的：通过简单的文本来描述UML图，然后通过专业的渲染引擎将文本内容转化成图形。PlantUML的官方网站是：http://plantuml.com/，它是一个开源项目，工具集本身针对不同的许可协议有着不同的编译，因此，你可以根据自己的需要选择使用相对应的版本。PlantUML本身不仅可以支持UML类图的定义，而且可以支持包括时序图、用例图、活动图等9中UML图形，还可以支持包括架构图、甘特图等6种非UML图形。详细内容可以直接参考官网，都是中文版的，简单容易。不过，今天我们只演示UML类图的自动化产生。

举个例子，下面的PlantUML文本：

@startuml test

Dummy2 <|-- Dummy1
Dummy1 *... Dummy3
Dummy1 --- Dummy4
IDummy <|.. Dummy4

interface IDummy {
  + DoSomething(parameter: Object): boolean
}

class Dummy1 {
  + myMethods()
}

class Dummy2 {
  + hiddenMethod()
}

class Dummy3 {
   String name
}

class Dummy4 {
  - field1: string
  - field2: int
  # field3: DateTime
  + DoSomething(parameter: Object): boolean
}

@enduml

会生成下图所示的UML类图：

image

有关PlantUML的语言语法定义，这里就不多说明了，官方网站上有详细的文档，而且还有PDF格式的使用手册可供免费下载。不过，从上面的例子，我们大概可以得知：

  1. PlantUML需要由@startuml和@enduml两条语句来标注起始，@startuml后可以跟上类图的名称
  2. 可以通过不同的符号来标注类、接口之间的关系，事实上，PlantUML的语法定义还是非常随意的，这些定义可以放在文件的任何位置，不过有可能会影响所产生的UML图的布局
  3. 每个接口，每个类中都可以定义字段和方法，并通过不同的符号来表示这些成员的可访问级别

当然，我们的目的不是手写这样的PlantUML文本来绘制UML类图，我们希望能够有个程序，它可以根据给定的源程序代码，自动产生UML类图。

Roslyn的C#语言服务

根据GitHub中Roslyn项目的说明，Roslyn提供了开源的C#和Visual Basic编译器，并且提供了丰富的代码分析API，使得开发人员能够非常方便地开发.NET语言的代码分析工具。总体来说，Roslyn主要提供了以下NuGet包：

  • Microsoft.Net.Compilers：它包含了C#和Visual Basic的编译器
  • Microsoft.CodeAnalysis：它包含了代码分析API以及语言服务（Language Services）

或许大家对于Roslyn并不陌生，然而对于如何运用这套强大的语言平台却倍感疑惑。嗯，Roslyn是.NET语言的编译器基础，基于Apache 2.0开源，很强大，可是我们平时没有需要使用这些工具和库的需求啊，我们知道Visual Studio中的代码分析工具会基于Roslyn，可是除了代码分析，还可以在什么场景中使用呢？今天，我们就使用Roslyn的语言服务来为我们画UML类图。

PlantUML文本的自动生成

使用Roslyn的C#语言服务来生成UML类图，大致流程如下：

  1. 搜索指定目录的所有C#代码文件，这些文件通常都以.cs作为后缀名
  2. 使用Roslyn的C#语言服务，针对每个C#代码文件，逐一分析出其中的类型（类、接口等）以及每个类型下的成员（字段、属性、方法等）
  3. 将分析结果转化为PlantUML文本
  4. 通过某种工具，将PlantUML呈现为UML类图

搜索指定目录下的C#代码文件很简单，使用Directory.EnumerateFiles就可以了，接下来就是要把代码文件中的类型和成员都解析出来，并保存到一个数据模型中，然后，才可以根据这个数据模型来输出PlantUML的文本。这个过程其实也就是计算机语言相互转换的过程，比如你希望将C#语言代码转换成Java代码，那么，两者必然要基于同一个语言数据模型，比如，通用的表达式树可以描述所有编程语言中的表达式。在这里的例子中，我们可以将PlantUML看成是另一种编程语言（它其实本身也就是一种领域特定语言（DSL）），于是，我们目前的首要问题就是定义这个数据模型。

根据需要，我定义了如下的数据模型，用来保存C#代码解析后的信息：

test3


这个数据模型主体部分的设计如下：

  • 一个ClassDiagram类包含了一组BasicTypeRelationship，用来表达基本类型（类和接口）之间的关系；此外，还包含了一组类的声明以及一组接口的声明
  • 类和接口都继承于BasicType基类，同时包含了一组字段（Field）和一组方法（Method）的定义
  • Field和Method都继承于ClassMember
  • Method包含一组参数（Parameter）的定义

目前这个模型的定义还是非常简单的，并没有包含类似泛型、属性等的设计，不过有了这个基础的模型，今后扩展起来就很简单了。接下来就是通过Roslyn，将C#源代码转换成这个模型。

首先，我们需要添加Microsoft.CodeAnalysis.CSharp这个NuGet包，然后，依照访问者设计模式，实现一个CSharpSyntaxWalker，它会在遍历C#语法树的时候，根据访问的当前节点的类型来调用相应的方法，于是，我们的访问器则可以重载这些方法，然后构建上述数据模型。代码如下：

public class PlantUmlClassDiagramGenerator : CSharpSyntaxWalker
{
    public PlantUmlClassDiagramGenerator(string diagramName)
    {
        ClassDiagram = new ClassDiagram(diagramName);
    }

    public override void VisitClassDeclaration(ClassDeclarationSyntax node)
    {
        if (node.BaseList != null)
        {
            foreach (var baseType in node.BaseList.Types)
            {
                ClassDiagram.Relationships.Add(new BasicTypeRelationship
                {
                    Left = baseType.Type.ToString(),
                    Right = node.Identifier.ToString(),
                    Type = RelationshipType.Generalization
                });
            }
        }

        var clazz = new Class { Name = node.Identifier.ToString() };
        if (node.Modifiers.Any(SyntaxKind.AbstractKeyword))
        {
            clazz.IsAbstract = true;
        }

        if (node.Modifiers.Any(SyntaxKind.StaticKeyword))
        {
            clazz.IsStatic = true;
        }

        var propertyDeclarations = node.Members.Where(m => m is PropertyDeclarationSyntax)
            .Select(m => m as PropertyDeclarationSyntax);
        foreach (var propertyDeclaration in propertyDeclarations)
        {
            var field = new Field { Name = propertyDeclaration.Identifier.ToString(), Type = propertyDeclaration.Type.ToString() };
            field.AccessModifier = GetAccessModifier(propertyDeclaration.Modifiers);
            clazz.Fields.Add(field);
        }

        var fieldDeclarations = node.Members.Where(m => m is FieldDeclarationSyntax)
            .Select(m => m as FieldDeclarationSyntax);
        foreach (var fieldDeclaration in fieldDeclarations)
        {
            clazz.Fields.AddRange(CreateFields(fieldDeclaration));
        }

        var methodDeclarations = node.Members.Where(m => m is MethodDeclarationSyntax)
            .Select(m => m as MethodDeclarationSyntax);
        foreach(var methodDeclaration in methodDeclarations)
        {
            clazz.Methods.Add(CreateMethod(methodDeclaration));
        }

        ClassDiagram.Classes.Add(clazz);
    }

    private IEnumerable<Field> CreateFields(FieldDeclarationSyntax fieldDeclaration)
    {
        var type = fieldDeclaration.Declaration.Type.ToString();
        foreach (var variableDeclaration in fieldDeclaration.Declaration.Variables)
        {
            var field = new Field { Name = variableDeclaration.Identifier.ToString(), Type = type };
            field.IsStatic = fieldDeclaration.Modifiers.Any(SyntaxKind.StaticKeyword);
            field.AccessModifier = GetAccessModifier(fieldDeclaration.Modifiers);

            yield return field;
        }
    }

    private Method CreateMethod(MethodDeclarationSyntax methodDeclaration)
    {
        var method = new Method { Name = methodDeclaration.Identifier.ToString() };
        method.IsAbstract = methodDeclaration.Modifiers.Any(SyntaxKind.AbstractKeyword);
        method.IsStatic = methodDeclaration.Modifiers.Any(SyntaxKind.StaticKeyword);
        method.AccessModifier = GetAccessModifier(methodDeclaration.Modifiers);
        foreach (var parameterDeclaration in methodDeclaration.ParameterList.Parameters)
        {
            method.Parameters.Add(new Parameter { Name = parameterDeclaration.Identifier.ToString(), Type = parameterDeclaration.Type.ToString() });
        }
        method.Type = methodDeclaration.ReturnType.ToString();

        return method;
    }

    private AccessModifier GetAccessModifier(SyntaxTokenList modifiers)
    {
        if (modifiers.Any(SyntaxKind.PublicKeyword))
        {
            return AccessModifier.Public;
        }
        else if (modifiers.Any(SyntaxKind.ProtectedKeyword))
        {
            return AccessModifier.Protected;
        }
        else if (modifiers.Any(SyntaxKind.InternalKeyword))
        {
            return AccessModifier.Internal;
        }
        else
        {
            return AccessModifier.Private;
        }
    }

    public override void VisitInterfaceDeclaration(InterfaceDeclarationSyntax node)
    {
        ClassDiagram.Interfaces.Add(new Interface { Name = node.Identifier.ToString() });
    }

    public ClassDiagram ClassDiagram { get; }
}

以下是调用代码：

static void Main(string[] args)
{
    const string SourcePath = @"C:\Users\daxne\source\repos\ConsoleApp10\ConsoleApp10\Sample";
    var csharpFiles = Directory.EnumerateFiles(SourcePath, "*.cs", SearchOption.AllDirectories);
    var walker = new PlantUmlClassDiagramGenerator("sample");
    foreach(var csharpFile in csharpFiles)
    {
        if (csharpFile.EndsWith(".designer.cs", StringComparison.InvariantCultureIgnoreCase))
        {
            continue;
        }

        var sourceCode = File.ReadAllText(csharpFile);
        var syntaxTree = CSharpSyntaxTree.ParseText(sourceCode);
        walker.Visit(syntaxTree.GetRoot());
    }

    Console.WriteLine($"Classes: {walker.ClassDiagram.Classes.Count}");
    Console.WriteLine($"Interfaces: {walker.ClassDiagram.Interfaces.Count}");

    File.WriteAllText(@"C:\Users\daxne\Desktop\text.puml", walker.ClassDiagram.ToString());
}

最后输出的PlantUML文本如下：

@startuml sample
Person <|-- Student
Person <|-- Employee
Employee <|-- RegularEmployee
Employee <|-- Contractor
abstract class Person {
  + FirstName : string
  + LastName : string
  + MiddleInitial : string
}

class Student {
  + Identification : string
  +Register(registerDate: DateTime) : void
}

abstract class Employee {
  + EmployeeId : string
  + DocumentSigned : DateTime
}

class RegularEmployee {
  +Resign() : void
}

class Contractor {
  + ContractEndDate : DateTime
  +TerminateContract() : void
}

@enduml

PlantUML文本的图形化渲染

现在已经生成了PlantUML的文本，接下来就要将它渲染成UML类图。我推荐使用Visual Studio Code的PlantUML插件，不仅能够提供代码高亮功能，而且还可以实时预览渲染结果，非常方便。

image

在安装和使用PlantUML插件之前，请确保已经安装了以下组件：

  • Java 8
  • Graphviz

该插件还支持将渲染的UML图导出成各种格式的图片，在此就不多说明了。

总结

本文对PlantUML进行了简单的介绍，并介绍了如何通过.NET的Roslyn语言服务和代码分析API，实现类图的动态生成。PlantUML将UML图文本化，不仅有利于UML图的版本追踪和控制，而且在很多第三方的工具（比如Confluence）中都能够很方便地集成。而自动化生成UML图形的意义在于，从代码产生设计图变得更加方便，而且能够始终与代码设计保持一致。而另一方面，.NET Roslyn编译器服务本身也给开发者带来了更多C#、Visual Basic代码处理的机遇，我们可以使用这样的服务来帮助我们做更多的事情，简化我们的日常工作。

相关文章