Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Similar to package validation, assembly validation tooling allows you, as a library developer, to validate that your assemblies are consistent and well formed. Use assembly validation instead of package validation when your app isn't packable.
Assembly validation provides the following checks:
You can run assembly validation either as an MSBuild task or using the Microsoft.DotNet.ApiCompat.Tool global tool.
You enable assembly validation in your .NET project by setting the ApiCompatValidateAssemblies
property to true
and specifying the path to the contract (baseline) assembly. You must also add a package reference to Microsoft.DotNet.ApiCompat.Task. (The targets
files in that package aren't part of the .NET SDK.)
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net8.0</TargetFrameworks>
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
<ApiCompatContractAssembly>[Path to contract assembly]</ApiCompatContractAssembly>
<IsPackable>false</IsPackable>
</PropertyGroup>
<ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
<PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
</ItemGroup>
</Project>
Assembly validation runs either in the outer build for multi-targeting projects (after the DispatchToInnerBuilds
target) or in the inner build for a single-targeting project (as part of the PrepareForRun
target). It's also fully incremental, meaning the comparison is only triggered if the inputs or outputs have changed.
Create and build a C# class library named "ValidateMe" that contains the following simple interface:
namespace ValidateMe;
public interface IAnimal
{
string Name { get; }
//string Sound { get; }
}
Rename the output assembly to "ValidateMeV1.dll".
Add the Sound
property to the interface by uncommenting that line of code.
Add the ApiCompatValidateAssemblies
and ApiCompatContractAssembly
properties and the "Microsoft.DotNet.ApiCompat.Task" package reference to your project file. Also increment the version of your assembly to "2.0.0".
<PropertyGroup>
<OutputType>Library</OutputType>
<TargetFrameworks>net8.0</TargetFrameworks>
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
<ApiCompatContractAssembly>$(OutDir)bin\Release\net8.0\ValidateMeV1.dll</ApiCompatContractAssembly>
<IsPackable>false</IsPackable>
<Version>2.0.0</Version>
</PropertyGroup>
<ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
<PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
</ItemGroup>
Rebuild your class library.
The build fails with the following errors:
C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API compatibility errors between 'bin\Release\net8.0\ValidateMeV1.dll' (left) and 'C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll' (right):
1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error CP0006: Cannot add interface member 'string ValidateMe.IAnimal.Sound' to C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll because it does not exist on bin\Release\net8.0\ValidateMeV1.dll
1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API breaking changes found. If those are intentional, the APICompat suppression file can be updated by rebuilding with '/p:ApiCompatGenerateSuppressionFile=true'
For information about suppressing compatibility warnings, see How to suppress.
.NET feedback
.NET is an open source project. Select a link to provide feedback:
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Learn to validate Teams apps extensible across Microsoft 365 - Training
In this module, our focus is on ensuring that the extensible Teams apps meet the validation requirements.
Documentation
Package Validation Diagnostics IDs - .NET
A reference for assembly and package validation diagnostic IDs, and how to suppress them.
Microsoft.DotNet.ApiCompat.Tool global tool - .NET
Learn about the Microsoft.DotNet.ApiCompat.Tool global tool, which performs API compatibility checks on assemblies and packages.
.NET Package Validation - .NET
Learn how .NET compatibility features can be used to develop consistent and well-formed multi-targeting packages.