公共API生成器 11.1.0

PublicApiGenerator

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

如何使用

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 生成器全局工具

安装

dotnet tool install -g PublicApiGenerator.Tool

更新

dotnet tool update -g PublicApiGenerator.Tool

移除

dotnet tool uninstall -g PublicApiGenerator.Tool

示例

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

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

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

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

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

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的公共API（精确版本匹配）

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

为运行时框架 netcoreapp2.2 和 net452 生成版本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

为我的get上可用的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

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

wait-time-in-seconds

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