Validação de montagem

Semelhante à validação de pacotes, as ferramentas de validação de assembly permitem que você, como desenvolvedor de biblioteca, valide se seus assemblies são consistentes e bem formados. Use a validação de assembly em vez da validação de pacote quando seu aplicativo não puder ser empacotado.

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

• Valida que não há alterações significativas entre as versões.
• Valida se o assembly tem o mesmo conjunto de APIs públicas para todas as diferentes implementações específicas de tempo de execução.
• Deteta quaisquer furos de aplicabilidade.

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

Habilitar tarefa do MSBuild

Você habilita a validação de assembly em seu projeto .NET definindo a ApiCompatValidateAssemblies propriedade e true especificando o caminho para o assembly de contrato (linha de base). Você também deve adicionar uma referência de pacote a Microsoft.DotNet.ApiCompat.Task. (Os targets arquivos nesse pacote 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 montagem é executada na compilação externa para projetos de segmentação múltipla (após o DispatchToInnerBuilds destino) ou na compilação interna para um projeto de direcionamento único (como parte do PrepareForRun destino). Também é totalmente incremental, o que significa que a comparação só é acionada se as entradas ou saídas tiverem mudado.

Exemplo

1. Crie e construa uma biblioteca de classes C# chamada "ValidateMe" que contém a seguinte interface simples:

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

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

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

4. Adicione as ApiCompatValidateAssemblies propriedades e ApiCompatContractAssembly e a referência do pacote "Microsoft.DotNet.ApiCompat.Task" ao seu arquivo de projeto. Além disso, incremente a versão do seu 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. Reconstrua sua biblioteca de classes.

   A compilação 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, consulte Como suprimir.