PublicApiGenerator 11.3.0

dotnet add package PublicApiGenerator --version 11.3.0                
NuGet\Install-Package PublicApiGenerator -Version 11.3.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="PublicApiGenerator" Version="11.3.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add PublicApiGenerator --version 11.3.0                
#r "nuget: PublicApiGenerator, 11.3.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install PublicApiGenerator as a Cake Addin
#addin nuget:?package=PublicApiGenerator&version=11.3.0

// Install PublicApiGenerator as a Cake Tool
#tool nuget:?package=PublicApiGenerator&version=11.3.0                

PublicApiGenerator

Run tests Publish preview Publish release

License codecov Nuget Nuget GitHub Release Date GitHub commits since latest release (by date) Size

GitHub contributors Activity Activity Activity

PublicApiGenerator has no dependencies and simply creates a string that represents the public API. Any approval library can be used to approve the generated public API. Public API approval is often used as an auxiliary tool (often as automated test as shown in the examples below) for tracking intentional or unforeseen changes in public API. At first, public API as string is stored into a text file in VCS. Then the current generated string is compared with one preserved earlier. If they are different, the test ends with an error, indicating the need to make a decision. As a rule, the text file in VCS is updated with a new generated value, while accordingly changing project version - major or minor. Also note that it is normal that sometimes changes in public API do not require changes in minor or major version at all.

PublicApiGenerator supports C# 8 Nullable Reference Types from version 10.

How do I use it

Install-package PublicApiGenerator

Public API of an assembly

var publicApi = typeof(Library).Assembly.GeneratePublicApi();

Public API of multiple types

var myTypes = new[] { typeof(MyType), typeof(YetAnotherType) };
var publicApi = typeof(myTypes).GeneratePublicApi();

Public API of a type

var publicApi = typeof(MyType).GeneratePublicApi();

More control over the API output

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

Manual

[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 itself uses this approach to test API changes.

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; }
    }
}

Verify

Verify

Install-package Verify.Xunit

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

    return Verifier.Verify(publicApi);

    // Or, if the public api is different based on the target frameworks:
    // return Verifier.Verify(publicApi).UniqueForTargetFrameworkAndVersion();
}

Or

Install-package Verify.NUnit

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

    return Verifier.Verify(publicApi);
}

Or

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 Global Tool

Install

dotnet tool install -g PublicApiGenerator.Tool

Update

dotnet tool update -g PublicApiGenerator.Tool

Remove

dotnet tool uninstall -g PublicApiGenerator.Tool

Examples

Generate public API for fluent assertions 5.6.0 for runtime framework netcoreapp2.1 and net461

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

Generate public API for fluent assertions 5.* for runtime framework net47

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

Note that when a single target framework is specified then the API is generated to standard output. To write to a file, you can either use shell redirection:

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

or specify an output directory to force the generation of an API file:

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

Generate public API for fluent assertions 5.6.0 (exact version match) for runtime framework net47

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

Generate public API for NServiceBus 7.1.4 for runtime framework netcoreapp2.2 and net452. Note NServiceBus package doesn't contain NServiceBus.dll and therefore it is required to specify the assembly that contains the public API.

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

Generate a public API for NServiceBus release available on myget

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

Command line arguments

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

The target framework in which the package will be restored. The target framework is also used as runtime to generate the public API. It is required to specify a valid runtime framework. For example

  • "netcoreapp2.2;net452" to build a public API for netcoreapp2.2 and net452
  • "netcoreapp2.1;net461" to build a public API for netcoreapp2.1 and net461
  • net47 to build a public API for net47

It is not possible to use netstandard2.0 because it is not a valid runtime framework.

If only a single target framework is given then the API is generated to the standard output unless the --output-directory option is also specified.

--package-name PackageName

A valid nuget package name. For example

  • FluentAssertions
  • NServiceBus

When the --package-name switch is used the --package-version switch is mandatory.

--package-version Version

A nuget package version or floating versions as specified by https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files and https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges-and-wildcards. For example

  • 8.1.1
  • 8.0
  • 8.0-*
--package-source Source

Allows specifying one or multiple package sources to look for packages.

--assembly Assembly.dll

The assembly name including the extension to generate a public API from in case in differs from the package name. For example

  • PublicApiGenerator.dll
  • NServiceBus.Core.dll
--project-path

A path to a csproj file that contains the public API that needs to be built. By default a release build will be generated. When the project-path switch is used it is required to specify the --assembly switch to point to the output assembly that contains the public API. For example

  • ..\PublicApiGenerator\PublicApiGenerator.csproj
--working-directory Path

The temporary working directory to be used to generate the work artifacts.

--output-directory Path

The output directory where public API text-files should be moved. The end with *.received.txt

--generator-version Version

By default latest stable release version of PubliApiGenerator will be used in the global tool to generate the public API with in the major range of the global tool. It is possible to override the PublicApiGenerator version by specifying the version to be used in this switch. For example

  • 8.1.0
--verbose

Detailed information about what's going on behind the scenes

leave-artifacts

For troubleshooting purposes it might be necessary to look into the temporary work artifacts. By specifying this switch the temporary csproj files and all the temp folders are not deleted after a run. Be aware this might significantly decrease the available disk space because all artifacts including the compile time artifacts are not deleted.

wait-time-in-seconds

The number of seconds to wait for the API generation process to end (default 60 seconds). If multiple target frameworks are used the wait time is applied per target framework. If the process did not end in the allotted time a TimeoutException is thrown.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on PublicApiGenerator:

Package Downloads
ApiApprover

Simply add this package to add a test which generates a string of your public API, then sends it to Approval Tests to approve any public API changes. Don't accidently miss a breaking API change and break semantic versioning again.

GitHub repositories (59)

Showing the top 5 popular GitHub repositories that depend on PublicApiGenerator:

Repository Stars
Humanizr/Humanizer
Humanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities
reactiveui/refit
The automatic type-safe REST library for .NET Core, Xamarin and .NET. Heavily inspired by Square's Retrofit library, Refit turns your REST API into a live interface.
reactiveui/ReactiveUI
An advanced, composable, functional reactive model-view-viewmodel framework for all .NET platforms that is inspired by functional reactive programming. ReactiveUI allows you to abstract mutable state away from your user interfaces, express the idea around a feature in one readable place and improve the testability of your application.
serilog/serilog
Simple .NET logging with fully-structured events
dotnet/reactive
The Reactive Extensions for .NET
Version Downloads Last updated
11.3.0 3,441 12/17/2024
11.2.0 7,611 12/11/2024
11.1.0 422,522 12/3/2023
11.0.0 223,318 3/6/2023
10.5.0 480 3/6/2023
10.4.1 289 3/6/2023
10.4.0 295 3/6/2023
10.3.0 259,076 1/31/2022
10.2.0 625,804 6/26/2020
10.1.2 7,441 6/18/2020
10.1.1 756 6/17/2020
10.1.0 4,420 5/18/2020
10.0.2 96,053 1/27/2020
10.0.1 130,763 12/4/2019
10.0.0 1,309 12/1/2019
9.3.0 209,939 8/2/2019
9.2.0 1,668 8/2/2019
9.1.0 13,139 6/30/2019
9.0.0 2,495 6/13/2019
9.0.0-beta3 1,385 3/31/2019
9.0.0-beta2 1,375 3/29/2019
9.0.0-beta1 1,206 3/29/2019
8.1.0 48,721 1/7/2019
8.0.1 7,284 9/23/2018
8.0.0 2,423 7/24/2018
7.1.0 1,609 7/18/2018
7.0.1 4,872 5/7/2018
7.0.0 1,512 3/10/2018
6.6.0 1,351 3/9/2018
6.5.2 1,114 3/8/2018
6.5.1 1,206 3/7/2018
6.5.0 3,740 11/17/2017
6.4.0 2,827 10/10/2017
6.1.0-beta2 3,074 5/22/2017
6.1.0-beta1 2,784 5/15/2017
6.0.0 12,045 12/14/2016
5.0.0 4,143 11/21/2016
4.2.0 3,657 11/2/2016
4.1.0 3,252 10/6/2016
4.0.1 16,430 2/2/2016
4.0.0 1,715 2/2/2016