Share via

API-compatibiliteitshulpprogramma's

  • Artikel

Platformoverschrijdende compatibiliteit is een basisvereiste geworden voor auteurs van .NET-bibliotheken. Zonder hulpprogramma's om assembly's en pakketten te valideren, kunnen deze echter onbedoelde wijzigingen bevatten die fouten veroorzaken. Als auteur van een bibliotheek moet u ervoor zorgen dat meerdere assembly's compatibel zijn. Voor een pakket met meerdere doelen voor .NET 6 en .NET Standard 2.0 moet u er bijvoorbeeld voor zorgen dat code die is gecompileerd op basis van het binaire .NET Standard 2.0, kan worden uitgevoerd op basis van het binaire .NET 6-bestand.

U denkt misschien dat een wijziging veilig en compatibel is als de bron die deze wijziging gebruikt, zonder wijzigingen blijft compileren. De wijzigingen kunnen echter nog steeds problemen veroorzaken tijdens de uitvoering als de consument niet opnieuw is gecompileerd. Als u bijvoorbeeld een optionele parameter toevoegt aan een methode of de waarde van een constante wijzigt, kan dit soort compatibiliteitsproblemen veroorzaken.

De .NET SDK biedt verschillende manieren waarop u versies kunt vergelijken die zijn gebouwd voor verschillende doelframeworks. U kunt ook een nieuwere versie valideren op basis van een basislijnversie om ervoor te zorgen dat er geen belangrijke wijzigingen zijn geïntroduceerd. Schakel MSBuild-taken in om uw assembly's te valideren tijdens het compileren of uw pakketten wanneer u inpakt. Of gebruik het globale hulpprogramma Microsoft.DotNet.ApiCompat.Tool om buiten MSBuild te valideren.

Zie Pakketvalidatie voor meer informatie over pakketvalidatie. Assemblyvalidatie moet worden gebruikt wanneer uw app niet kan worden verpakt. Zie Assembly-validatie voor meer informatie over assemblyvalidatie.

Notitie

Als u assemblyvalidatie wilt uitvoeren als een MSBuild-taak, moet u een pakketreferentie toevoegen aan Microsoft.DotNet.ApiCompat.Task. Op dezelfde manier kunt u ook een verwijzing naar dit pakket toevoegen als u nieuwere functies wilt testen die nog niet beschikbaar zijn in de .NET SDK. U kunt bijvoorbeeld verwijzen naar de versie 9.0.100 preview van het Microsoft.DotNet.ApiCompat.Task-pakket terwijl u de .NET 8 SDK gebruikt.

Strikte modus

De validatie voert standaard compatibiliteitscontroles uit. U kunt echter ook kiezen voor strikte modus. In de strikte modus voert de validatie gelijkheidscontroles uit. Gelijkheid betekent dat er geen API-toevoegingen of assemblywijzigingen, zelfs compatibele, zijn aangebracht.

De gebruiksvoorbeelden voor de strikte modus omvatten het volgende:

  • Onderhoud, waarbij API-toevoegingen meestal verboden zijn.
  • Voor het bijhouden van API-wijzigingen. De API-compatibiliteitsfunctionaliteit registreert alle compatibiliteitsverschillen in het onderdrukkingsbestand als u ApiCompatGenerateSuppressionFile instelt op true.

Als u de strikte modus voor het opdrachtregelprogramma wilt inschakelen, geeft u de --strict-mode optie of een van de --enable-strict* opties op. Als u de strikte modus voor de MSBuild-taken wilt inschakelen, voegt u een of meer van de volgende MSBuild-eigenschappen toe aan uw projectbestand: