Compartilhar via


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.