Analysieren von Abhängigkeiten zum Portieren von Code aus .NET Framework zu .NET

  • Artikel

Um die nicht unterstützten Drittanbieterabhängigkeiten in Ihrem Projekt zu identifizieren, müssen Sie zunächst Ihre Abhängigkeiten verstehen. Externe Abhängigkeiten sind die NuGet-Pakete oder .dll-Dateien, auf die Sie in Ihrem Projekt verweisen, die Sie aber nicht selbst erstellen.

Das Portieren Ihres Codes zu .NET Standard 2.0 oder niedriger gewährleistet, dass er sowohl mit .NET Framework als auch mit .NET verwendet werden kann. Wenn Sie die Bibliothek jedoch nicht mit .NET Framework verwenden müssen, sollten Sie in Erwägung ziehen, die neueste Version von .NET als Ziel zu verwenden.

Migrieren von NuGet-Paketen zu PackageReference

.NET kann die Datei packages.config nicht für NuGet-Verweise verwenden. Sowohl .NET als auch .NET Framework können PackageReference verwenden, um Paketabhängigkeiten anzugeben. Wenn Sie packages.config verwenden, um die Pakete in Ihrem Projekt anzugeben, konvertieren Sie die Datei in das PackageReference-Format.

Informationen zum Migrieren finden Sie im Artikel Migrieren von „packages.config“ zu PackageReference.

Aktualisieren von NuGet-Paketen

Nachdem Sie Ihr Projekt zum PackageReference-Format migriert haben, überprüfen Sie, ob Ihre Pakete mit .NET kompatibel sind.

Aktualisieren Sie zunächst Ihre Pakete auf die neueste Version, die verfügbar ist. Dies kann über die Benutzeroberfläche des NuGet-Paket-Managers in Visual Studio erfolgen. Es ist wahrscheinlich, dass neuere Versionen ihrer Paketabhängigkeiten bereits mit .NET Core kompatibel sind.

Analysieren der Paketabhängigkeiten

Wenn Sie noch nicht überprüft haben, ob die konvertierten und aktualisierten Paketabhängigkeiten in .NET Core funktionieren, gibt es zwei Möglichkeiten, dies zu bestätigen:

Mithilfe von nuget.org

Sie können die TFMs (Target Framework Monikers, Zielframeworkmoniker), die die einzelnen Pakete unterstützen, unter nuget.org im Abschnitt Dependencies (Abhängigkeiten) der Paketseite anzeigen.

Es ist einfacher, die Website zum Überprüfen der Kompatibilität zu verwenden. Allerdings stehen dort nicht für alle Abhängigkeiten Informationen zur Verfügung.

Mithilfe des NuGet-Paket-Explorers

Ein NuGet-Paket besteht wiederum aus mehreren Ordnern, die plattformspezifische Assemblys enthalten. Überprüfen Sie, ob es im Paket einen Ordner gibt, der eine kompatible Assembly enthält.

Am einfachsten überprüfen Sie die NuGet-Paketordner mit dem Tool NuGet Package Explorer. Führen Sie nach der Installation folgende Schritte durch, um die Ordnernamen anzuzeigen:

  1. Öffnen Sie den NuGet-Paket-Explorer.
  2. Klicken Sie auf Open package from online feed (Paket über Onlinefeed öffnen).
  3. Suchen Sie nach dem Namen des Pakets.
  4. Wählen Sie den Paketnamen aus den Suchergebnissen aus, und klicken Sie auf Öffnen.
  5. Erweitern Sie den Ordner Lib (Bibliotheken) auf der rechten Seite, und suchen Sie in den Ordnernamen.

Suchen Sie nach einem Ordner mit Namen mit einem der folgenden Muster: netstandardX.Y, netX.Y oder netcoreappX.Y.

Diese Werte sind die Zielframeworkmoniker (TFMs), die den Versionen von .NET Standard, .NET und .NET Core zugeordnet sind, die alle mit .NET kompatibel sind.

Wichtig

Wenn Sie die von einem Paket unterstützten TFMs untersuchen, beachten Sie, dass ein anderer TFM als netstandard* auf eine bestimmte Implementierung von .NET abzielt, z. B. auf .NET 5, .NET Core oder .NET Framework. Ab .NET 5 ersetzt der net*-TFM (ohne Betriebssystembezeichnung) effektiv netstandard* als portierbares Ziel. Beispielsweise zielt net5.0 auf die .NET 5-API-Oberfläche und ist plattformübergreifend, aber net5.0-windows zielt auf die .NET 5-API-Oberfläche, wie sie unter dem Windows-Betriebssystem implementiert ist.

Der .NET Framework-Kompatibilitätsmodus

Nachdem Sie die NuGet-Pakete analysiert haben, zeigt sich möglicherweise, dass sie nur .NET Framework als Ziel verwenden.

Mit .NET Standard 2.0 wurde der .NET Framework-Kompatibilitätsmodus eingeführt. Mit diesem Kompatibilitätsmodus können .NET Standard- und .NET Core-Projekte auf .NET Framework-Bibliotheken verweisen. Das Verweisen auf .NET Framework-Bibliotheken funktioniert nicht bei allen Projekten. So funktioniert es z.B. nicht, wenn die Bibliothek Windows Presentation Foundation-APIs (WPF) verwendet. Dadurch werden jedoch viele Portierungsszenarios ermöglicht.

Wenn Sie in Ihrem Projekt auf NuGet-Pakete mit .NET Framework als Ziel verweisen, wie z. B. Huitian.PowerCollections, wird eine Paketfallbackwarnung (NU1701) ähnlich wie im folgenden Beispiel ausgegeben:

NU1701: Package ‘Huitian.PowerCollections 1.0.0’ was restored using ‘.NETFramework,Version=v4.6.1’ instead of the project target framework ‘.NETStandard,Version=v2.0’. This package may not be fully compatible with your project.

Diese Warnung wird angezeigt, wenn Sie das Paket hinzufügen und jedes Mal, wenn Sie etwas erstellen, um sicherzustellen, dass Sie das Paket mit Ihrem Projekt testen. Wenn Ihr Projekt wie gewünscht funktioniert, können Sie die Warnung unterdrücken, indem Sie die Paketeigenschaften in Visual Studio bearbeiten oder die Projektdatei in Ihrem bevorzugten Code-Editor manuell bearbeiten.

Um die Warnung durch Bearbeiten der Projektdatei zu unterdrücken, suchen Sie den PackageReference-Eintrag für das Paket, für das Sie die Warnung unterdrücken möchten, und fügen Sie das NoWarn-Attribut hinzu. Das NoWarn-Attribut akzeptiert eine durch Trennzeichen getrennte Liste aller Warnungs-IDs. Im folgenden Beispiel wird gezeigt, wie Sie die NU1701-Warnung für das Huitian.PowerCollections-Paket unterdrücken, indem Sie Ihre Projektdatei manuell bearbeiten:

<ItemGroup>
  <PackageReference Include="Huitian.PowerCollections" Version="1.0.0" NoWarn="NU1701" />
</ItemGroup>

Weitere Informationen zum Unterdrücken von Compilerwarnungen in Visual Studio finden Sie unter Unterdrücken von Compilerwarnungen im Abschnitt zum Unterdrücken von Warnungen für NuGet-Pakete.

Wenn NuGet-Pakete unter .NET nicht ausgeführt werden

Es gibt einige Dinge, die Sie tun können, wenn ein NuGet-Paket, auf das Sie angewiesen sind, unter .NET Core nicht ausgeführt wird:

  • Wenn es sich um ein Open Source-Projekt handelt, das beispielsweise von GitHub gehostet wird, können Sie sich direkt an die Entwickler wenden.
  • Sie können den Autor direkt über nuget.org kontaktieren. Suchen Sie nach dem Paket, und klicken Sie links auf der Paketseite auf Contact Owners (Besitzer kontaktieren).
  • Sie können nach einem anderen Paket suchen, das unter .NET Core ausgeführt wird und denselben Zweck erfüllt wie das Paket, das Sie bisher verwendet haben.
  • Sie können den vom Paket ausgeführten Code selbst schreiben.
  • Sie können die Abhängigkeit für das Paket eliminieren, indem Sie die Funktionalität Ihrer Anwendung ändern, zumindest bis eine kompatible Version des Pakets verfügbar ist.

Denken Sie daran, dass Open-Source-Projektverwalter und NuGet-Paketherausgeber häufig Freiwillige sind. Sie beteiligen sich, weil Ihnen eine bestimmte Domäne wichtig ist. Sie arbeiten daran unentgeltlich und haben häufig einen anderen Job, für den sie unter der Woche arbeiten. Denken Sie daran, wenn Sie diese Personen kontaktieren, um sie um Unterstützung bezüglich .NET Core zu bitten.

Wenn es Ihnen mit den genannten Optionen nicht gelingt, Ihr Problem zu beheben, müssen Sie sich mit dem Portieren in .NET Core noch etwas gedulden.

Das .NET-Team würde gerne wissen, welche Bibliotheken von .NET Core unterstützt werden sollten. Sie können uns gerne mit einer E-Mail an dotnet@microsoft.com mitteilen, welche Bibliotheken Sie gerne verwenden würden.

Analysieren von Nicht-NuGet-Abhängigkeiten

Möglicherweise verfügen Sie über eine Abhängigkeit, bei der es sich nicht um ein NuGet-Paket, sondern beispielsweise um eine DLL im Dateisystem handelt. Sie können die Portabilität dieser Abhängigkeit ermitteln, indem Sie die Funktion für die binäre Analyse des .NET-Upgrade-Assistenten verwenden.

Nächste Schritte