Convalida dell'assembly

Analogamente alla convalida dei pacchetti, gli strumenti di convalida degli assembly consentono, come sviluppatore di librerie, di verificare che gli assembly siano coerenti e ben formati. Usa la convalida dell'assembly anziché la convalida dei pacchetti quando l'app non è comprimibile.

La convalida dell'assembly fornisce i controlli seguenti:

• Verifica che non siano presenti modifiche di rilievo tra le versioni.
• Verifica che l'assembly abbia lo stesso set di API pubbliche per tutte le diverse implementazioni specifiche del runtime.
• Cattura eventuali fori di applicabilità.

È possibile eseguire la convalida dell'assembly come attività MSBuild o usando lo strumento globale Microsoft.DotNet.ApiCompat.Tool.

Abilitare l'attività MSBuild

Per abilitare la convalida dell'assembly nel progetto .NET, impostare la ApiCompatValidateAssemblies proprietà su true e specificare il percorso dell'assembly del contratto (baseline). È inoltre necessario aggiungere un riferimento al pacchetto a Microsoft.DotNet.ApiCompat.Task. I targets file in tale pacchetto non fanno parte di .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>

La convalida dell'assembly viene eseguita nella compilazione esterna per i progetti con più destinazioni (dopo la DispatchToInnerBuilds destinazione) o nella compilazione interna per un progetto di destinazione singola (come parte della PrepareForRun destinazione). È anche completamente incrementale, ovvero il confronto viene attivato solo se gli input o gli output sono stati modificati.

Esempio

1. Creare e compilare una libreria di classi C# denominata "ValidateMe" che contiene l'interfaccia semplice seguente:

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

2. Rinominare l'assembly di output in "ValidateMeV1.dll".

3. Aggiungere la Sound proprietà all'interfaccia annullando il commento di tale riga di codice.

4. Aggiungere le ApiCompatValidateAssemblies proprietà e ApiCompatContractAssembly e il riferimento al pacchetto "Microsoft.DotNet.ApiCompat.Task" al file di progetto. Incrementare anche la versione dell'assembly a "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. Ricompilare la libreria di classi.

   La compilazione ha esito negativo con gli errori seguenti:

   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'
   

Eliminare gli avvisi di compatibilità

Per informazioni sull'eliminazione degli avvisi di compatibilità, vedere Come eliminare.