Sdílet prostřednictvím

Nástroje pro kompatibilitu rozhraní API

  • Článek

Kompatibilita mezi platformami se stala hlavním požadavkem pro autory knihoven .NET. Bez nástrojů pro ověření sestavení a balíčků však můžou obsahovat neúmyslné zásadní změny. Jako autor knihovny je potřeba zajistit, aby vícecílová sestavení byla kompatibilní. Například pro balíček, který více cílů pro .NET 6 a .NET Standard 2.0, musíte zajistit, aby kód zkompilovaný proti binárnímu souboru .NET Standard 2.0 mohl běžet v binárním souboru .NET 6.

Můžete si myslet, že změna je bezpečná a kompatibilní, pokud zdroj, který tuto změnu využívá, se i nadále kompiluje bez změn. Změny ale můžou způsobit problémy za běhu, pokud uživatel nebyl rekompilován. Například přidání volitelného parametru do metody nebo změna hodnoty konstanty může způsobit tyto druhy problémů s kompatibilitou.

Sada .NET SDK nabízí různé způsoby porovnání verzí vytvořených pro různé cílové architektury. Můžete také ověřit novější verzi na základní verzi, abyste zajistili, že se nezanesou žádné zásadní změny. Povolte úlohy NÁSTROJE MSBuild k ověření sestavení v době kompilace nebo balíčků při balení. Nebo použijte globální nástroj Microsoft.DotNet.ApiCompat.Tool k ověření mimo nástroj MSBuild.

Další informace o ověření balíčku naleznete v tématu Ověření balíčku. Ověření sestavení by se mělo použít v případě, že vaše aplikace není zabalitelná. Další informace o ověřování sestavení naleznete v tématu Ověření sestavení.

Poznámka:

Chcete-li spustit ověření sestavení jako úlohu MSBuild, musíte přidat odkaz na balíček Microsoft.DotNet.ApiCompat.Task. Podobně můžete také přidat odkaz na tento balíček, pokud chcete otestovat novější funkce, které ještě nejsou dostupné v sadě .NET SDK. Můžete například odkazovat na verzi 9.0.100-Preview balíčku Microsoft.DotNet.ApiCompat.Task při použití sady .NET 8 SDK.

Striktní režim

Ve výchozím nastavení ověřování provádí kontroly kompatibility. Můžete se ale také přihlásit k přísnému režimu. V přísném režimu provádí ověření kontroly rovnosti . Rovnost znamená, že nebyly provedeny žádné dodatky rozhraní API ani změny sestavení, ani kompatibilní.

Případy použití pro striktní režim zahrnují následující:

  • Údržba, ve které jsou doplňky rozhraní API obvykle zakázané.
  • Sledování změn rozhraní API Funkce kompatibility rozhraní API zaznamenává všechny rozdíly v kompatibilitě v souboru potlačení, pokud nastavíte ApiCompatGenerateSuppressionFile na truehodnotu .

Pokud chcete pro nástroj příkazového řádku povolit striktní režim, zadejte --strict-mode možnost nebo jednu z --enable-strict* možností. Chcete-li povolit striktní režim pro úlohy MSBuild, přidejte do souboru projektu jednu nebo více z následujících vlastností NÁSTROJE MSBuild: