PublicApiGenerator.Tool 11.1.0

PublicApiGenerator

PublicApiGenerator 无任何依赖，仅创建表示公共 API 的字符串。可以使用任何批准库来批准生成的公共 API。PublicApiGenerator 从版本 10 开始支持 C# 8 可为 null 的引用类型。

如何使用它

Install-package PublicApiGenerator

程序集的公共 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 输出的控制

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

手册

[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))
    {
        // Create a file to write to.
        using (var sw = File.CreateText(approvedFilePath)) { }
    }

    var approvedApi = File.ReadAllText(approvedFilePath);

    Assert.Equal(approvedApi, publicApi);
}

Shouldly

Shouldly

Install-package Shouldly

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

    //Shouldly
    publicApi.ShouldMatchApproved();
}

ApiGenerator 本身 使用 此方法来测试 API 变更。

ApprovalTests

ApprovalTests

Install-package 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());
}

private class AssemblyPathNamer : UnitTestFrameworkNamer
{
    private readonly string name;

    public AssemblyPathNamer(string assemblyPath)
    {
        name = Path.GetFileNameWithoutExtension(assemblyPath);
    }

    public override string Name
    {
        get { return name; }
    }
}

验证

验证

Install-package Verify.Xunit

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

        return Verifier.Verify(publicApi);
    }
}

或

Install-package Verify.NUnit

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

    return Verifier.Verify(publicApi);
}

或

Install-package Verify.MSTest

[TestClass]
public class VerifyObjectSamples :
    VerifyBase
{
    [TestMethod]
    public Task my_assembly_has_no_public_api_changes()
    {
        var publicApi = typeof(Library).Assembly.GeneratePublicApi();

        return Verifier.Verify(publicApi);
    }
}

PublicApi Generator 全球工具

安装

dotnet tool install -g PublicApiGenerator.Tool

更新

dotnet tool update -g PublicApiGenerator.Tool

删除

dotnet tool uninstall -g PublicApiGenerator.Tool

示例

为运行时框架 netcoreapp2.1 和 net461 生成 5.6.0 版本 fluent assertions 的公共 API

generate-public-api --target-frameworks "netcoreapp2.1;net461" --package FluentAssertions --package-version 5.6.0

为运行时框架 net47 生成 5.* 版本 fluent assertions 的公共 API

generate-public-api --target-frameworks net47 --package FluentAssertions --package-version 5.*

注意，当指定单个目标框架时，API 将生成到标准输出。要写入文件，可以，或者使用外壳重定向

generate-public-api --target-frameworks net47 --package FluentAssertions --package-version 5.* > api.txt

或指定一个输出目录以强制生成 API 文件

generate-public-api --target-frameworks net47 --package FluentAssertions --package-version 5.* --output-directory .

为运行时框架 net47 生成 5.6.0 版本 fluent assertions 的公共 API（精确版本匹配）

generate-public-api --target-frameworks net47 --package FluentAssertions --package-version [5.6.0]

为运行时框架 netcoreapp2.2 和 net452 生成适用于 NServiceBus 7.1.4 的公开 API。注意，NServiceBus 包不包含 NServiceBus.dll，因此需要指定包含公开 API 的程序集。

generate-public-api --target-frameworks "netcoreapp2.2;net452" --package NServiceBus --package-version 7.1.4 --assembly NServiceBus.Core.dll

为 MyGet 上的可用的 NServiceBus 版本生成公开 API。

generate-public-api --target-frameworks "netcoreapp2.2;net452" --package NServiceBus --package-version 7.1.4 --assembly NServiceBus.Core.dll --package-source https://www.myget.org/F/particular/api/v3/index.json

命令行参数

--target-frameworks framework|"framework;framework"

将从中恢复包的目标框架。目标框架还用作生成公开 API 的运行时。需要指定一个有效的运行时框架。例如

• "netcoreapp2.2;net452" 用于构建针对 netcoreapp2.2 和 net452 的公开 API
• "netcoreapp2.1;net461" 用于构建针对 netcoreapp2.1 和 net461 的公开 API
• net47 用于构建针对 net47 的公开 API

不能使用 netstandard2.0，因为它不是一个有效的运行时框架。

如果只给出一个目标框架，则除非还指定了 --output-directory 选项，否则 API 将生成到标准输出。

--package-name PackageName

一个有效的 NuGet 包名。例如

• FluentAssertions
• NServiceBus

当使用 --package-name 开关时，必须使用 --package-version 开关。

--package-version Version

NuGet 包版本或根据 https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files 和 https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges-and-wildcards 指定的浮点版本。例如

• 8.1.1
• 8.0
• 8.0-*

--package-source Source

允许指定一个或多个包源以查找包。

--assembly Assembly.dll

要在其中生成公开 API 的程序集名称（包括扩展名），如果它与包名不同。例如

• PublicApiGenerator.dll
• NServiceBus.Core.dll

--project-path

包含需要构建的公开 API 的 csproj 文件的路径。默认情况下，将生成发布版构建。当使用项目路径开关时，需要指定 --assembly 开关以指向包含公开 API 的输出程序集。例如

• ..\PublicApiGenerator\PublicApiGenerator.csproj

--working-directory Path

用于生成工作原文件的临时工作目录。

--output-directory Path

将公开 API 文本文件移动到的输出目录。以 *.received.txt 结尾

--generator-version Version

默认情况下，将在全局工具的全局范围内使用最新的稳定发布版本 PubliApiGenerator 来生成公开 API。可以通过在此开关中指定要使用的版本来覆盖 PublicApiGenerator 版本。例如

• 8.1.0

--verbose

关于幕后发生的事情的详细信息

leave-artifacts

出于故障排除的目的，可能需要检查临时工作原文件。指定此开关后，在运行结束后不会删除临时 csproj 文件和所有临时文件夹。请注意，这可能会显着减少可用的磁盘空间，因为包括编译时原文件在内的所有原文件都不会被删除。

wait-time-in-seconds

等待 API 生成过程结束的秒数（默认 60 秒）。如果使用了多个目标框架，则等待时间应用于每个目标框架。如果在指定的时间内进程没有结束，将抛出 TimeoutException。