PublicApiGenerator 技术文档

1. 安装指南

PublicApiGenerator 是一个生成公共 API 字符串的工具，它没有依赖，可以轻松安装。以下是安装步骤：

通过 NuGet 包管理器

在您的项目中，使用 NuGet 包管理器安装 PublicApiGenerator。

Install-Package PublicApiGenerator

通过 .NET CLI 工具

您也可以通过 .NET CLI 工具全局安装 PublicApiGenerator。

dotnet tool install -g PublicApiGenerator.Tool

2. 项目的使用说明

PublicApiGenerator 用于生成一个表示公共 API 的字符串。这个字符串可以用于审批，以确保公共 API 的变更。

生成公共 API 字符串

以下是如何生成不同类型公共 API 的示例代码：

// 生成一个程序集的公共 API
var publicApi = typeof(Library).Assembly.GeneratePublicApi();

// 生成多个类型的公共 API
var myTypes = new[] { typeof(MyType), typeof(YetAnotherType) };
var publicApi = typeof(myTypes).GeneratePublicApi();

// 生成一个类型的公共 API
var publicApi = typeof(MyType).GeneratePublicApi();

更多 API 输出控制

如果您需要更多控制 API 输出的选项，可以使用 ApiGeneratorOptions 类。

var options = new ApiGeneratorOptions { ... };
var publicApi = typeof(Library).Assembly.GeneratePublicApi(options);

3. 项目 API 使用文档

PublicApiGenerator 提供了多种方法来验证公共 API 是否发生了变化，以下是一些常用的方法：

手动验证

[Fact]
public void my_assembly_has_no_public_api_changes()
{
    var publicApi = typeof(Library).Assembly.GeneratePublicApi();

    var approvedFilePath = "PublicApi.approved.txt";
    if (!File.Exists(approvedFilePath))
    {
        // 创建一个文件进行写入。
        using (var sw = File.CreateText(approvedFilePath)) { }
    }

    var approvedApi = File.ReadAllText(approvedFilePath);

    Assert.Equal(approvedApi, publicApi);
}

使用 Shouldly

[Fact]
public void my_assembly_has_no_public_api_changes()
{
    var publicApi = typeof(Library).Assembly.GeneratePublicApi();

    // Shouldly
    publicApi.ShouldMatchApproved();
}

使用 ApprovalTests

[Fact]
public void my_assembly_has_no_public_api_changes()
{
    var publicApi = typeof(Library).Assembly.GeneratePublicApi();
    var writer = new ApprovalTextWriter(publicApi, "txt");
    var approvalNamer = new AssemblyPathNamer(assembly.Location);
    Approvals.Verify(writer, approvalNamer, Approvals.GetReporter());
}

使用 Verify

[Fact]
public Task my_assembly_has_no_public_api_changes()
{
    var publicApi = typeof(Library).Assembly.GeneratePublicApi();

    return Verifier.Verify(publicApi);
}

4. 项目安装方式

PublicApiGenerator 可以通过以下方式安装：

通过 NuGet 包

在您的 Visual Studio 项目中，使用 NuGet 包管理器安装 PublicApiGenerator 包。

Install-Package PublicApiGenerator

通过 .NET CLI

使用 .NET CLI 工具全局安装 PublicApiGenerator。

dotnet tool install -g PublicApiGenerator.Tool

如果您需要更新或卸载 PublicApiGenerator，可以使用以下命令：

dotnet tool update -g PublicApiGenerator.Tool

dotnet tool uninstall -g PublicApiGenerator.Tool

以上就是 PublicApiGenerator 的技术文档，希望对您有所帮助。