API-Kompatibilitätstools

  • Artikel

Die plattformübergreifende Kompatibilität ist für .NET-Bibliotheksautoren zu einer gängigen Anforderung geworden. Ohne Tools zum Überprüfen von Assemblys und Paketen können sie jedoch unbeabsichtigte Unterbrechungen enthalten. Als Bibliotheksautor*in müssen Sie sicherstellen, dass Multi-Targeting-Assemblys kompatibel sind. Beispielsweise muss ein Paket mit mehreren Zielen für .NET 6 und .NET Standard 2.0 sicherstellen, dass der für die Binärdatei von .NET Standard 2.0 kompilierte Code für die Binärdatei von .NET 6 ausgeführt werden kann.

Möglicherweise wirkt es so, als wäre eine Änderung sicher und kompatibel, wenn die Quelle, für die die Änderung vorgesehen ist, weiterhin ohne Änderungen kompiliert wird. Die Änderungen können jedoch zur Laufzeit weiterhin Probleme verursachen, wenn der Consumer nicht neu kompiliert wurde. Beispielsweise kann das Hinzufügen eines optionalen Parameters zu einer Methode oder das Ändern des Werts einer Konstante zu solchen Kompatibilitätsproblemen führen.

Das .NET SDK bietet verschiedene Möglichkeiten zum Vergleichen von Versionen, die für verschiedene Zielframeworks erstellt wurden. Sie können auch eine neuere Version anhand einer Basisversion überprüfen, um sicherzustellen, dass keine grundlegenden Änderungen eingeführt wurden. Aktivieren Sie MSBuild-Aufgaben, um Ihre Assemblys zur Kompilierungszeit oder ihre Pakete beim Packen zu überprüfen. Oder verwenden Sie das globale Tool „Microsoft.DotNet.ApiCompat.Tool“, um außerhalb von MSBuild zu überprüfen.

Weitere Informationen zur Paketüberprüfung finden Sie unter Paketüberprüfung. Die Assemblyüberprüfung sollte verwendet werden, wenn Ihre App nicht gepackt werden kann. Weitere Informationen zur Assemblyüberprüfung finden Sie unter Assemblyüberprüfung.

Hinweis

Um die Assemblyüberprüfung als MSBuild-Aufgabe auszuführen, müssen Sie einen Paketverweis auf Microsoft.DotNet.ApiCompat.Task hinzufügen. Ebenso können Sie auch einen Verweis auf dieses Paket hinzufügen, wenn Sie neuere Funktionen testen möchten, die noch nicht im .NET SDK verfügbar sind. Sie können beispielsweise auf die 9.0.100-Vorschauversion des Microsoft.DotNet.ApiCompat.Task-Pakets verweisen, wenn Sie das .NET 8 SDK verwenden.

Strict-Modus

Standardmäßig führt die Überprüfung Kompatibilitätsprüfungen durch. Sie können sich jedoch auch für den Strict-Modus entscheiden. Im Strict-Modus werden Gleichheitsüberprüfungen durchgeführt. Gleichheit bedeutet, dass keine API-Ergänzungen oder Assemblyänderungen, auch nicht, wenn sie kompatibel sind, vorgenommen wurden.

Die Anwendungsfälle für den Strict-Modus umfassen:

  • Wartung, in der API-Ergänzungen in der Regel verboten sind.
  • Zum Nachverfolgen von API-Änderungen. Die API-Kompatibilitätsfunktionalität zeichnet alle Kompatibilitätsunterschiede in der Unterdrückungsdatei auf, wenn Sie ApiCompatGenerateSuppressionFile auf true festlegen.

Um den Strict-Modus für das Befehlszeilentool zu aktivieren, geben Sie die --strict-mode-Option oder eine der --enable-strict*-Optionen an. Um den Strict-Modus für die MSBuild-Aufgaben zu aktivieren, fügen Sie Ihrer Projektdatei mindestens eine der folgenden MSBuild-Eigenschaften hinzu: