Condividi tramite

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.

  • Last updated on