Validação de assemblies

De forma semelhante à validação de pacotes, as ferramentas de validação de assemblies permitem que você, como um desenvolvedor de bibliotecas, valide se os assemblies são consistentes e estão bem formados. Use a validação de assemblies em vez da validação de pacotes quando o aplicativo não for empacotável.

A validação de assemblies fornece as seguintes verificações:

• Valida que não há alterações significativas nas versões.
• Valida se o assembly tem o mesmo conjunto de APIs públicas para todas as diferentes implementações específicas para cada runtime.
• Captura todos os espaços de aplicabilidade.

Você pode executar a validação de assemblies como uma tarefa do MSBuild ou usando a ferramenta global Microsoft.DotNet.ApiCompat.Tool.

Habilitar a tarefa do MSBuild

Habilite a validação de assembly em seu projeto .NET definindo a propriedade ApiCompatValidateAssemblies como true e especificando o caminho para o assembly de contrato (linha de base). Você também deve adicionar uma referência de pacote à Microsoft.DotNet.ApiCompat.Task. (Os arquivos targets no pacote em questão não fazem parte do SDK do .NET.)

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

A validação de assemblies é executada no build externo, para projetos com vários destinos (após o destino DispatchToInnerBuilds), ou no build interno, para um projeto de destino único (como parte do destino PrepareForRun). Também é totalmente incremental, o que significa que a comparação só será acionada se as entradas ou saídas tiverem sido alteradas.

Exemplo

1. Crie e compile uma biblioteca de classes C# chamada "ValidateMe" que contenha a seguinte interface simples:

   namespace ValidateMe;
   
   public interface IAnimal
   {
       string Name { get; }
       //string Sound { get; }
   }
   

2. Renomeie o assembly de saída como "ValidateMeV1.dll".

3. Adicione a propriedade Sound à interface descompactando essa linha de código.

4. Adicione as propriedades ApiCompatValidateAssemblies e ApiCompatContractAssembly e a referência do pacote "Microsoft.DotNet.ApiCompat.Task" ao arquivo de projeto. Incremente também a versão do assembly para "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>
   

5. Recompile sua biblioteca de classes.

   O build falha com os seguintes erros:

   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'
   

Suprimir avisos de compatibilidade

Para obter informações sobre como suprimir avisos de compatibilidade, confira Como suprimir.