Sammansättningsverifiering

På samma sätt som med paketverifiering kan du som biblioteksutvecklare verifiera att dina sammansättningar är konsekventa och välformulerade. Använd sammansättningsverifiering i stället för paketverifiering när appen inte är packbar.

Sammansättningsverifiering ger följande kontroller:

• Verifierar att det inte finns några icke-bakåtkompatibla ändringar i olika versioner.
• Verifierar att sammansättningen har samma uppsättning offentliga API:er för alla olika körningsspecifika implementeringar.
• Fångar eventuella tillämplighetshål.

Du kan köra sammansättningsverifiering antingen som en MSBuild-uppgift eller med hjälp av det globala verktyget Microsoft.DotNet.ApiCompat.Tool.

Aktivera MSBuild-uppgift

Du aktiverar sammansättningsvalidering i .NET-projektet genom att ange ApiCompatValidateAssemblies egenskapen till true och ange sökvägen till sammansättningen kontrakt (baslinje). Du måste också lägga till en paketreferens till Microsoft.DotNet.ApiCompat.Task. (Filerna targets i paketet ingår inte i .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>

Sammansättningsvalidering körs antingen i den yttre versionen för projekt med flera mål (efter DispatchToInnerBuilds målet) eller i den inre versionen för ett projekt med enkel inriktning (som en del av PrepareForRun målet). Det är också helt inkrementellt, vilket innebär att jämförelsen endast utlöses om indata eller utdata har ändrats.

Exempel

1. Skapa och skapa ett C#-klassbibliotek med namnet "ValidateMe" som innehåller följande enkla gränssnitt:

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

2. Byt namn på utdatasammansättningen till "ValidateMeV1.dll".

3. Lägg till egenskapen Sound i gränssnittet genom att avkommentarera den kodraden.

4. ApiCompatValidateAssemblies Lägg till egenskaperna och ApiCompatContractAssembly och paketreferensen "Microsoft.DotNet.ApiCompat.Task" i projektfilen. Öka också versionen av sammansättningen till "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. Återskapa klassbiblioteket.

   Bygget misslyckas med följande fel:

   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'
   

Ignorera kompatibilitetsvarningar

Information om hur du undertrycker kompatibilitetsvarningar finns i Så här utelämnar du.