.NET Portability Analyzer

  • Artikel
  • 5 Minuten Lesedauer

Hinweis

Wir befinden uns im Prozess der veralteten API-Portierung, um binäre Analyse direkt in .NET Upgrade Assistent zu integrieren. In den kommenden Monaten werden wir den Back-End-Dienst des API-Port herunterfahren, der das Tool offline verwenden muss. Weitere Informationen finden Sie unter GitHub: .NET API Port Repository.*

Sollen Ihre Bibliotheken mehrere Plattformen unterstützen? Möchten Sie wissen, wie viel Arbeit erforderlich ist, damit Ihre .NET Framework-Anwendung unter .NET Core ausgeführt werden kann? .NET Portability Analyzer ist ein Tool, das Assemblys analysiert und einen detaillierten Bericht zu fehlenden .NET-APIs bereitstellt, damit die Anwendungen oder Bibliotheken auf die von Ihnen angegebenen .NET-Zielplattformen portiert werden können. Die Portabilitätsanalyse wird als Visual Studio-Erweiterung angeboten, die eine Assembly pro Projekt analysiert und als ApiPort-Konsolen-App, die Assemblys durch angegebene Dateien oder Verzeichnis analysiert.

Nachdem Sie Ihr Projekt konvertiert haben, um auf die neue Plattform wie .NET Core zu abzielen, können Sie die Roslyn-basierte Plattformkompatibilitätsanalyse verwenden, um APIs zu identifizieren, die Ausnahmen und andere Kompatibilitätsprobleme auslösen.PlatformNotSupportedException

Allgemeine Ziele

  • .NET Core: Besitzt einen modularen Aufbau, unterstützt die parallele Ausführung und ist auf plattformübergreifende Szenarios ausgerichtet. Die parallele Installation ermöglicht Ihnen die Übernahme neuer Versionen von .NET Core, ohne andere Apps zu beeinträchtigen. Wenn Sie Ihre App zur Unterstützung mehrerer Plattformen nach .NET Core portieren möchten, wird dieses Ziel empfohlen.
  • .NET Standard: Enthält die .NET Standard-APIs, die für alle .NET-Implementierungen verfügbar sind. Wenn Sie möchten, dass Ihre Bibliothek auf allen Plattformen ausgeführt werden kann, die .NET unterstützen, wird dieses Ziel empfohlen.
  • ASP.NET Core: Ein modernes Webframework, das auf .NET Core basiert. Wenn Sie Ihre Webanwendung zur Unterstützung von mehreren Plattformen nach .NET Core portieren möchten, wird dieses Ziel empfohlen.
  • .NET Core-Plattform + Plattformerweiterungen: Enthält die .NET Core-APIs sowie den Windows Compatibility Pack, der zahlreiche in .NET Framework verfügbare Technologien bereitstellt. Dieses Ziel wird zum Portieren der Anwendung von .NET Framework nach .NET Core unter Windows empfohlen.
  • .NET Standard-Plattform + Plattformerweiterungen: Enthält die .NET Standard-APIs sowie den Windows Compatibility Pack, der zahlreiche in .NET Framework verfügbare Technologien bereitstellt. Dieses Ziel wird zum Portieren der Bibliothek von .NET Framework nach .NET Core unter Windows empfohlen.

Verwenden von .NET Portability Analyzer

Laden Sie .NET Portability Analyzer in Visual Studio zunächst von Visual Studio Marketplace herunter, um mit der Verwendung dieser Erweiterung zu beginnen. Es funktioniert in Visual Studio 2017- und Visual Studio 2019-Versionen.

Wichtig

Die .NET-Portabilitätsanalyse wird in Visual Studio 2022 nicht unterstützt.

Sie können ihn in Visual Studio über Analyze>Portability Analyzer Settings (Analysieren/Portability Analyzer-Einstellungen) konfigurieren und Ihre Zielplattformen, also die .NET-Plattformen/Versionen auswählen, für die Sie Portabilitätslücken im Vergleich zu der Plattform/Version analysieren möchten, mit der Ihre aktuelle Assembly erstellt wurde.

Screenshot von Portability Analyzer.

Sie können auch die ApiPort-Konsolenanwendung verwenden. Laden Sie sie aus dem ApiPort-Repository herunter. Sie können die Befehlsoption listTargets verwenden, um die Liste mit verfügbaren Zielen anzuzeigen. Anschließend wählen Sie Zielplattformen aus, indem Sie die Befehlsoption -t oder --target angeben.

Projektmappenweite Ansicht

Ein nützlicher Schritt bei der Analyse einer Projektmappe mit vielen Projekten wäre das Visualisieren der Abhängigkeiten, um zu verstehen, welche Teilmenge von Assemblys wovon abhängig ist. Die allgemeine Empfehlung ist, für die Ergebnisse der Analyse einen Bottom-up-Ansatz zu verwenden, beginnend mit den Blattknoten eines Abhängigkeitsdiagramms.

Zum Abrufen können Sie den folgenden Befehl ausführen:

ApiPort.exe analyze -r DGML -f [directory or file]

In Visual Studio sieht das Ergebnis in etwa wie folgt aus:

Screenshot der DGML-Analyse

Analysieren der Portabilität

Um das gesamte Projekt in Visual Studio zu analysieren, klicken Sie mit der rechten Maustaste im Projektmappen-Explorer auf Ihr Projekt, und wählen Sie Assemblyportabilität analysieren aus. Wechseln Sie andernfalls zum Menü Analysieren, und wählen Sie Assemblyportabilität analysieren. Wählen Sie dort die ausführbare Datei oder DLL-Datei des Projekts aus.

Screenshot von Portability Analyzer aus dem Projektmappen-Explorer.

Sie können auch die ApiPort-Konsolenanwendung verwenden.

Geben Sie den folgenden Befehl an, um das aktuelle Verzeichnis zu analysieren:

ApiPort.exe analyze -f .

Um eine bestimmte Liste von DLL-Dateien zu analysieren, geben Sie den folgenden Befehl ein:

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

Verwenden Sie zum Ziel einer bestimmten Version den -t Parameter:

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

Führen Sie ApiPort.exe -? weitere Hilfe aus.

Es wird empfohlen, alle zugehörigen EXE- und DLL-Dateien, die Sie besitzen und die Sie portieren möchten, einzubeziehen, und die Dateien auszuschließen, von denen Ihre Anwendung abhängt, die Sie jedoch nicht besitzen möchten und die Sie nicht portieren können. Dadurch erhalten Sie einen entsprechend sachdienlichen Portabilitätsbericht.

Anzeigen und Interpretieren des Portabilitätsergebnisses

Im Bericht werden nur die APIs angegeben, die von einer Zielplattform nicht unterstützt werden. Nach dem Ausführen der Analyse in Visual Studio wird der Link für die Datei des .NET-Portabilitätsberichts angezeigt. Wenn Sie die ApiPort-Konsolenanwendung verwendet haben, wird der .NET Portabilitätsbericht als Datei im angegebenen Format gespeichert. Die Standardeinstellung ist eine Excel-Datei ( .xlsx) im aktuellen Verzeichnis.

Zusammenfassung zur Portabilität

Screenshot der Zusammenfassung zur Portabilität.

Im Berichtsabschnitt mit der Portabilitätszusammenfassung wird für jede in der Ausführung enthaltene Assembly der Portabilitätsprozentsatz angezeigt. Im vorherigen Beispiel sind 71,24 Prozent der in der App svcutil verwendeten .NET Framework-APIs in .NET Core und Plattformerweiterungen verfügbar. Wenn Sie das Tool .NET Portability Analyzer für mehrere Assemblys ausführen, gibt es im Bericht „Zusammenfassung zur Portabilität“ für jede Assembly eine Zeile.

Details

Screenshot der Portabilitätsdetails.

Im Abschnitt Details des Berichts werden die APIs aufgeführt, die in einer der Zielplattformen fehlen.

  • Zieltyp: Der Typ enthält APIs, die in einer Zielplattform fehlen.
  • Zielmember: Die Methode fehlt in einer Zielplattform.
  • Assemblyname: Die .NET Framework-Assembly, in der sich die fehlende API befindet.
  • Jede ausgewählte Zielplattform wird als eine Spalte dargestellt, z. B. „.NET Core“: Der Wert „Nicht unterstützt“ bedeutet, dass die API auf dieser Zielplattform nicht unterstützt wird.
  • Empfohlene Änderungen: Empfohlene API oder Technologie, zu der gewechselt werden sollte. Dieses Feld ist für viele APIs derzeit leer oder nicht mehr aktuell. Aufgrund der Vielzahl von APIs ist es eine große Herausforderung, auf dem Laufenden zu bleiben. Wir suchen nach alternativen Lösungen, um Kunden nützliche Informationen anbieten zu können.

Fehlende Assemblys

Screenshot der fehlenden Assemblys.

Ihr Bericht enthält möglicherweise einen Abschnitt mit der Überschrift „Fehlende Assemblys“. Dieser Abschnitt enthält eine Liste der Assemblys, die von Ihren analysierten Assemblys referenziert werden, aber nicht analysiert wurden. Wenn es sich um eine Assembly in Ihrem Besitz handelt, beziehen Sie sie in die Ausführung von API Portability Analyzer ein, sodass Sie dafür die im Portabilitätsbericht angegebene API-Ebene erhalten. Wenn es sich um eine Bibliothek eines Drittanbieters handelt, überprüfen Sie, ob es eine neuere Version gibt, die Ihre Zielplattform unterstützt, und erwägen Sie eine Umstellung auf die neuere Version. Letztlich soll diese Liste alle Assemblys von Drittanbietern enthalten, von denen Ihre Anwendung abhängig ist, und diese müssen nachweislich eine Version aufweisen, die Ihre Zielplattform unterstützt.

Weitere Informationen zur .NET-Portabilitätsanalyse finden Sie in der GitHub-Dokumentation.