Assemblyüberprüfung

Ähnlich wie bei der Paketüberprüfung können Sie mithilfe von Assemblyüberprüfungstools als Bibliotheksentwickler*in überprüfen, ob Ihre Assemblys konsistent und wohlgeformt sind. Verwenden Sie die Assemblyüberprüfung anstelle der Paketüberprüfung, wenn Ihre App nicht gepackt werden kann.

Die Assemblyüberprüfung stellt die folgenden Überprüfungen bereit:

• Überprüfung, ob keine versionsübergreifenden Breaking Changes vorhanden sind
• Überprüfung, ob das Paket über dieselben öffentlichen APIs für die verschieden runtimespezifischen Implementierungen verfügt.
• Findet alle Lücken in der Anwendbarkeit.

Sie können die Assemblyüberprüfung entweder als MSBuild-Aufgabe oder mit dem globalen Tool Microsoft.DotNet.ApiCompat.Tool ausführen.

MSBuild-Aufgabe aktivieren

Sie aktivieren die Assemblyüberprüfung in Ihrem .NET-Projekt, indem Sie die ApiCompatValidateAssemblies-Eigenschaft auf true festlegen und den Pfad zur Vertragsassembly (Baselineassembly) angeben. Sie müssen auch einen Paketverweis auf Microsoft.DotNet.ApiCompat.Task hinzufügen. (Die targets-Dateien in diesem Paket sind nicht Teil des .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>

Die Assemblyüberprüfung wird entweder im äußeren Build für Projekte mit mehreren Zielen (nach dem DispatchToInnerBuilds-Ziel) oder im inneren Build für ein Projekt mit einem Ziel (als Teil des PrepareForRun-Ziels) ausgeführt. Es ist auch vollständig inkrementell, was bedeutet, dass der Vergleich nur ausgelöst wird, wenn sich die Eingaben oder Ausgaben geändert haben.

Beispiel

1. Erstellen Sie eine C#-Klassenbibliothek mit dem Namen „ValidateMe“, die die folgende einfache Schnittstelle enthält:

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

2. Benennen Sie die Ausgabeassembly in „ValidateMeV1.dll“ um.

3. Fügen Sie der Schnittstelle die Sound-Eigenschaft hinzu, indem Sie die Auskommentierung dieser Codezeile aufheben.

4. Fügen Sie Ihrer Projektdatei die Eigenschaften ApiCompatValidateAssemblies und ApiCompatContractAssembly sowie den Verweis auf das Paket „Microsoft.DotNet.ApiCompat.Task“ hinzu. Erhöhen Sie außerdem die Version Ihrer Assembly auf „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. Erstellen Sie Ihre Klassenbibliothek erneut.

   Beim Build treten die folgenden Fehler auf:

   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'
   

Kompatibilitätswarnungen unterdrücken

Informationen zum Unterdrücken von Kompatibilitätswarnungen finden Sie unter Unterdrücken.