Walidacja zestawu

  • Artykuł

Podobnie jak w przypadku sprawdzania poprawności pakietu, narzędzie sprawdzania poprawności zestawu umożliwia deweloperowi biblioteki sprawdzenie, czy zestawy są spójne i dobrze sformułowane. Jeśli aplikacja nie jest pakowalna, użyj walidacji zestawu zamiast sprawdzania poprawności pakietu.

Walidacja zestawu zapewnia następujące testy:

  • Sprawdza, czy nie ma żadnych zmian powodujących niezgodność w różnych wersjach.
  • Sprawdza, czy zestaw ma ten sam zestaw publicznych interfejsów API dla wszystkich różnych implementacji specyficznych dla środowiska uruchomieniowego.
  • Przechwytuje wszelkie otwory stosowania.

Walidację zestawu można uruchomić jako zadanie MSBuild lub za pomocą narzędzia globalnego Microsoft.DotNet.ApiCompat.Tool.

Włączanie zadania MSBuild

Walidację zestawu można włączyć w projekcie platformy .NET, ustawiając ApiCompatValidateAssemblies właściwość na true i określając ścieżkę do zestawu kontraktu (punktu odniesienia). Należy również dodać odwołanie do pakietu Microsoft.DotNet.ApiCompat.Task. targets(Pliki w tym pakiecie nie są częścią zestawu SDK platformy .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>

Walidacja zestawu jest uruchamiana w kompilacji zewnętrznej dla projektów wielowersyjnych (po DispatchToInnerBuilds obiekcie docelowym) lub w wewnętrznej kompilacji dla pojedynczego projektu docelowego (w ramach PrepareForRun celu). Jest to również w pełni przyrostowe, co oznacza, że porównanie jest wyzwalane tylko wtedy, gdy dane wejściowe lub wyjściowe uległy zmianie.

Przykład

  1. Utwórz i skompiluj bibliotekę klas języka C# o nazwie "ValidateMe", która zawiera następujący prosty interfejs:

    namespace ValidateMe;

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

  2. Zmień nazwę zestawu wyjściowego na "ValidateMeV1.dll".

  3. Sound Dodaj właściwość do interfejsu, usuwając komentarz z tego wiersza kodu.

  4. ApiCompatValidateAssemblies Dodaj właściwości i ApiCompatContractAssembly oraz odwołanie do pakietu "Microsoft.DotNet.ApiCompat.Task" do pliku projektu. Zwiększa również wersję zestawu do "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. Ponownie skompiluj bibliotekę klas.

    Kompilacja kończy się niepowodzeniem z następującymi błędami:

    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'

Pomijanie ostrzeżeń dotyczących zgodności

Aby uzyskać informacje na temat pomijania ostrzeżeń dotyczących zgodności, zobacz Jak pominąć.