Generating API files in the build
editThe Meziantou.Framework.PublicApiGenerator.MSBuild package writes the API files of a project after each build, and can check them instead of writing them.
Set up the project
Reference the package and set PublicApiGeneratorOutputPath, the only required property:
<ItemGroup>
<PackageReference Include="Meziantou.Framework.PublicApiGenerator.MSBuild" Version="x.y.z" PrivateAssets="all" />
</ItemGroup>
<PropertyGroup>
<PublicApiGeneratorOutputPath>PublicApi/PublicApi.g.cs</PublicApiGeneratorOutputPath>
</PropertyGroup>
<ItemGroup>
<Compile Remove="PublicApi/**" />
</ItemGroup>- The path is relative to the project directory. With the default
SingleFilelayout, it is the path of the file; with the other layouts, it is a directory. - Exclude the API files from the compilation with
Compile Remove, or write them outside of the project directory: otherwise the next build compiles the stubs with your code and fails with duplicate declarations. - A build that generates or checks the API files fails when
PublicApiGeneratorOutputPathis not set.
The files are written after the Build target, from the assembly the build produced. Design-time builds, such as the ones of your IDE, do not generate them.
Options
Set these properties in the project file, in a Directory.Build.props file to configure several projects at once, or on the command line with -p:<Name>=<Value>:
| Property | Default | Description |
|---|---|---|
PublicApiGeneratorOutputPath | (required) | The file (SingleFile layout) or the directory (other layouts) to write, relative to the project directory. |
PublicApiGeneratorFileLayout | SingleFile | SingleFile, OneFilePerNamespace or OneFilePerType. See File layouts. |
PublicApiGeneratorIncludeAutoGeneratedComment | true | Starts each file with a // <auto-generated/> comment. Set it to false to omit it. |
PublicApiGeneratorIncludeAssemblyReferences | false | Lists the referenced assemblies that are not part of the framework in the header, so that adding or removing a dependency changes the API files. See Referenced assemblies. |
PublicApiGeneratorIncludedAssemblyReferences | (empty) | Semicolon-separated patterns of the framework assemblies to list too, for instance System.Net.*. |
PublicApiGeneratorExcludedAssemblyReferences | (empty) | Semicolon-separated patterns of the assemblies not to list. They win over the included patterns. |
PublicApiGeneratorIncludeAllAttributes | false | Writes [EditorBrowsable], the attributes of other namespaces than System and the assembly attributes. See Attributes. |
PublicApiGeneratorGenerateOnBuild | true | Writes the API files after each build. |
PublicApiGeneratorVerifyNoChangeOnBuild | false | Checks the API files instead of writing them. See Check the API files in CI. |
PublicApiGeneratorDeleteUnexpectedFiles | false | Deletes the files of the output directory that the build does not write. See Files of removed types. |
When both PublicApiGeneratorGenerateOnBuild and PublicApiGeneratorVerifyNoChangeOnBuild are false, the package does nothing. To split the API into one file per namespace:
<PropertyGroup>
<PublicApiGeneratorOutputPath>PublicApi</PublicApiGeneratorOutputPath>
<PublicApiGeneratorFileLayout>OneFilePerNamespace</PublicApiGeneratorFileLayout>
</PropertyGroup>Multithreaded builds
The task supports the multithreaded mode of MSBuild 18.6 and later (dotnet build -mt): MSBuild runs it in the build process instead of a separate task host. Earlier versions of MSBuild are still supported. Relative paths are resolved against the project directory, not the current directory of the process.
Multi-targeted projects
For a project that sets TargetFrameworks, the files are written once, after all the target frameworks are built: the assemblies of all the target frameworks are merged into one set of files, with #if blocks for the declarations that differ. Nothing else to configure. See Multi-targeted libraries.
Check the API files in CI
Set PublicApiGeneratorVerifyNoChangeOnBuild to true to compare the API files with the build output instead of writing them:
dotnet build -p:PublicApiGeneratorVerifyNoChangeOnBuild=trueThis mode takes precedence over PublicApiGeneratorGenerateOnBuild: no file is written. The build fails with one error per difference:
File '…' is out of date.: the public API changed and the file was not regenerated.Expected file '…' does not exist.: a file is missing, for instance for a new namespace withOneFilePerNamespace.Unexpected file '…' exists in the output directory.: with a directory layout, a file that the generator would not write, such as the file of a removed type.
Line endings are ignored by the comparison, so a checkout that converts them does not fail the check. To fix an error, build without the property, and commit the changes of the API files.
Run the check in the same configuration as the one you generate the files with: when it is not the same, the API can be different, for instance when some code is only compiled in Debug.
Files of removed types
With the OneFilePerNamespace and OneFilePerType layouts, the build writes the files of the current API but does not delete a file by default. When you remove or rename a type or a namespace, its old file stays in the directory, and the check reports it as an unexpected file.
Set PublicApiGeneratorDeleteUnexpectedFiles to true to delete them: the build then deletes every file of the directory, subdirectories included, that it does not write, and the directories that are empty after that. Only use it when the directory only contains the API files:
<PropertyGroup>
<PublicApiGeneratorOutputPath>PublicApi</PublicApiGeneratorOutputPath>
<PublicApiGeneratorFileLayout>OneFilePerType</PublicApiGeneratorFileLayout>
<PublicApiGeneratorDeleteUnexpectedFiles>true</PublicApiGeneratorDeleteUnexpectedFiles>
</PropertyGroup>The property does not apply to the SingleFile layout, which writes one file at the path you set.