Share via

API-kompatibilitetsverktyg

  • Artikel

Plattformsoberoende kompatibilitet har blivit ett vanligt krav för .NET-biblioteksförfattare. Men utan verktyg för att verifiera sammansättningar och paket kan de innehålla oavsiktliga icke-bakåtkompatibla ändringar. Som biblioteksförfattare måste du se till att flerriktade sammansättningar är kompatibla. För ett paket som har flera mål för .NET 6 och .NET Standard 2.0 måste du till exempel se till att kod som kompilerats mot binärfilen .NET Standard 2.0 kan köras mot binärfilen .NET 6.

Du kanske tror att en ändring är säker och kompatibel om källförbrukning av den ändringen fortsätter att kompileras utan ändringar. Ändringarna kan dock fortfarande orsaka problem vid körning om konsumenten inte kompilerades om. Om du till exempel lägger till en valfri parameter i en metod eller ändrar värdet för en konstant kan det orsaka den här typen av kompatibilitetsproblem.

.NET SDK innehåller olika sätt att jämföra versioner som skapats för olika målramverk. Du kan också verifiera en nyare version mot en baslinjeversion för att säkerställa att inga icke-bakåtkompatibla ändringar har införts. Aktivera MSBuild-uppgifter för att verifiera dina sammansättningar vid kompileringstillfället eller dina paket när du packar. Du kan också använda verktyget Microsoft.DotNet.ApiCompat.Tool för att verifiera utanför MSBuild.

Mer information om paketverifiering finns i Paketverifiering. Sammansättningsverifiering bör användas när appen inte är packbar. Mer information om sammansättningsverifiering finns i Sammansättningsverifiering.

Kommentar

Om du vill köra sammansättningsverifiering som en MSBuild-uppgift måste du lägga till en paketreferens till Microsoft.DotNet.ApiCompat.Task. På samma sätt kan du också lägga till en referens till det här paketet när du vill testa nyare funktioner som ännu inte är tillgängliga i .NET SDK. Du kan till exempel referera till 9.0.100-förhandsversionen av paketet Microsoft.DotNet.ApiCompat.Task när du använder .NET 8 SDK.

Strikt läge

Som standard utför verifieringen kompatibilitetskontroller. Men du kan också välja strikt läge. I strikt läge utför verifieringen likhetskontroller. Likhet innebär att inga API-tillägg eller sammansättningsändringar, inte ens kompatibla, har gjorts.

Användningsfallen för strikt läge omfattar följande:

  • Service, där API-tillägg vanligtvis är förbjudna.
  • För att spåra API-ändringar. API-kompatibilitetsfunktionen registrerar alla kompatibilitetsskillnader i undertryckningsfilen om du anger ApiCompatGenerateSuppressionFile till true.

Om du vill aktivera strikt läge för kommandoradsverktyget anger du alternativet --strict-mode eller något av --enable-strict* alternativen. Om du vill aktivera strikt läge för MSBuild-aktiviteter lägger du till en eller flera av följande MSBuild-egenskaper i projektfilen: