Narzędzia zgodności interfejsu API

  • Artykuł

Zgodność międzyplatformowa stała się głównym wymaganiem dla autorów bibliotek platformy .NET. Jednak bez narzędzi do weryfikowania zestawów i pakietów mogą one zawierać niezamierzone zmiany powodujące niezgodność. Jako autor biblioteki należy upewnić się, że zestawy wielokierunkowe są zgodne. Na przykład w przypadku pakietu, który ma wiele obiektów docelowych dla platform .NET 6 i .NET Standard 2.0, należy upewnić się, że kod skompilowany względem pliku binarnego platformy .NET Standard 2.0 może działać względem danych binarnych platformy .NET 6.

Można pomyśleć, że zmiana jest bezpieczna i zgodna, jeśli użycie źródła, które zmiany będzie nadal kompilowane bez zmian. Jednak zmiany mogą nadal powodować problemy w czasie wykonywania, jeśli konsument nie został ponownie skompilowany. Na przykład dodanie opcjonalnego parametru do metody lub zmiana wartości stałej może spowodować tego rodzaju problemy ze zgodnością.

Zestaw .NET SDK udostępnia różne sposoby porównywania wersji utworzonych dla różnych platform docelowych. Możesz również zweryfikować nowszą wersję względem wersji punktu odniesienia, aby upewnić się, że nie wprowadzono żadnych zmian powodujących niezgodność. Włącz zadania programu MSBuild, aby weryfikować zestawy w czasie kompilacji lub pakiety podczas pakowania. Możesz też użyć narzędzia globalnego Microsoft.DotNet.ApiCompat.Tool, aby sprawdzić poprawność poza programem MSBuild.

Aby uzyskać więcej informacji na temat walidacji pakietów, zobacz Walidacja pakietu. Walidacja zestawu powinna być używana, gdy aplikacja nie jest pakowalna. Aby uzyskać więcej informacji na temat walidacji zestawu, zobacz Walidacja zestawu.

Uwaga

Aby uruchomić walidację zestawu jako zadanie MSBuild, należy dodać odwołanie do pakietu Microsoft.DotNet.ApiCompat.Task. Podobnie możesz również dodać odwołanie do tego pakietu, jeśli chcesz przetestować nowsze funkcje, które nie są jeszcze dostępne w zestawie SDK platformy .NET. Można na przykład odwołać się do wersji 9.0.100-preview pakietu Microsoft.DotNet.ApiCompat.Task podczas korzystania z zestawu SDK platformy .NET 8.

Tryb ścisły

Domyślnie walidacja przeprowadza kontrole zgodności . Można jednak również zdecydować się na tryb ścisły. W trybie ścisłym walidacja przeprowadza kontrole równości . Równość oznacza, że nie wprowadzono żadnych dodatków interfejsu API ani zmian zestawów, nawet zgodnych.

Przypadki użycia trybu ścisłego obejmują następujące elementy:

  • Obsługa, w której dodatki interfejsu API są zwykle zabronione.
  • Śledzenie zmian interfejsu API. Funkcja zgodności interfejsu API rejestruje wszystkie różnice zgodności w pliku pomijania, jeśli ustawisz wartość ApiCompatGenerateSuppressionFile na true.

Aby włączyć tryb ścisły dla narzędzia wiersza polecenia, określ --strict-mode opcję lub jedną z --enable-strict* opcji. Aby włączyć tryb ścisły dla zadań programu MSBuild, dodaj do pliku projektu co najmniej jedną z następujących właściwości programu MSBuild: