Verwenden des Legacy-Assistenten für .NET-Upgrades

Artikel
06/08/2023

In diesem Artikel erfahren Sie, wie Sie die alte Version des Befehlszeilenschnittstellentools (CLI) des .NET-Upgrade-Assistenten installieren und ausführen. Ab Version 0.5.2 wurde die Codebasis für das CLI-Tool des .NET-Upgrade-Assistenten auf die Visual Studio-Erweiterung umgestellt. Dies bedeutet, dass es nun zwei verschiedene CLI-Tools gibt: die Version vor 0.5.2 (die Legacyversion) und die Version ab 0.5.2 (die aktuelle Version).

Die Legacyversion verfügt über einige Funktionen, die in der neuen Version noch nicht verfügbar sind, z. B. die Analyse von Upgrades auf Befehls- oder Projektmappenebene, aber es fehlen auch einige Verbesserungen, die in der neuen Version (ab 0.5.2) verfügbar sind. Daher können Sie es weiterhin verwenden, bis die Funktionen und der Umfang der aktuellen Version erweitert werden.

Tipp

Die Legacyversion des Tools kann Projektmappendateien aktualisieren.

Installieren der Legacyversion

Die Legacyversion des Tools wird auf die gleiche Weise wie die aktuelle Version installiert, mit der Ausnahme, dass Sie als Version 0.4.421302 angeben:

dotnet tool install upgrade-assistant -g --version 0.4.421302

Wichtig

Die Installation dieses Tools schlägt möglicherweise fehl, wenn Sie zusätzliche NuGet-Feedquellen konfiguriert haben. Verwenden Sie den --ignore-failed-sources-Parameter, um diese Fehler als Warnungen statt als Fehler zu behandeln:

dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302

Analysieren Ihrer App

Die Legacyversion des Tools bietet einen Analysemodus, der einen vereinfachten Testlauf des Upgrades Ihrer App ausführt. Er kann Erkenntnisse über möglicherweise erforderliche Änderungen liefern, bevor das Upgrade gestartet wird. Öffnen Sie ein Terminal, und navigieren Sie zu dem Ordner, in dem sich das Zielprojekt oder die Projektmappe befindet. Führen Sie den Befehl upgrade-assistant analyze aus, und übergeben Sie den Namen des zu aktualisierenden Projekts oder der Projektmappe.

Im Folgenden sehen Sie eine Beispielausgabe nach dem Ausführen des Analysemodus mit der .NET Framework-WPF-App:

> upgrade-assistant analyze .\WebSiteRatings.sln

[15:39:00 INF] Loaded 9 extensions
[15:39:02 INF] Using MSBuild from C:\Program Files\dotnet\sdk\7.0.201\
[15:39:02 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
[15:39:05 INF] Writing output to C:\code\migration\AnalysisReport.sarif
[15:39:06 INF] Recommending Windows TFM net7.0-windows for project WebSiteRatings.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:06 INF] Marking assembly reference System.Configuration for removal based on package mapping configuration System.Configuration
[15:39:06 INF] Adding package System.Configuration.ConfigurationManager based on package mapping configuration System.Configuration
[15:39:08 INF] Package EntityFramework, Version=6.2.0 does not support the target(s) net7.0-windows but a newer version (6.4.4) does.
[15:39:09 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:10 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Recommending Windows TFM net7.0-windows for project StarVoteControl.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:13 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:13 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Running analyzers on WebSiteRatings
[15:39:14 INF] Identified 0 diagnostics in project WebSiteRatings
[15:39:14 INF] Running analyzers on StarVoteControl
[15:39:15 INF] Identified 0 diagnostics in project StarVoteControl
[15:39:15 INF] Analysis Complete, the report is available at C:\code\migration\AnalysisReport.sarif

Die Ausgabe enthält zahlreiche interne Diagnoseinformationen, aber einige Informationen sind hilfreich. Beachten Sie, dass der Analysemodus angibt, dass während eines Upgrades der Moniker des Zielframeworks (TFM) des Projekts auf net7.0-windows anstelle von net7.0 festgelegt wurde. Diese Empfehlung basiert darauf, dass die Projekte, auf die die Projektmappe verweist, WPF-Projekte sind, eine reine Windows-Technologie. Eine Konsolenanwendung würde wahrscheinlich direkt auf TFM net7.0 aktualisiert werden, es sei denn, sie verwendet eine Windows-spezifische Bibliothek oder einen bestimmten Code.

Ausführen des Upgrade-Assistenten

Öffnen Sie ein Terminal, und navigieren Sie zu dem Ordner, in dem sich das Zielprojekt oder die Projektmappe befindet. Führen Sie den Befehl upgrade-assistant upgrade aus, und übergeben Sie den Namen des zu aktualisierenden Projekts oder der Projektmappe.

Während der Ausführung des Tools wird eine Liste der Schritte angezeigt, die zum Upgraden des Projekts ausgeführt werden. Nachdem die einzelnen Schritte abgeschlossen wurden, stellt das Tool eine Reihe von nummerierten Befehlen bereit, mit denen Benutzer*innen den nächsten Schritt anwenden oder überspringen können. Er bietet möglicherweise weitere Optionen, z. B.:

Abrufen weiterer Informationen zum Schritt
Ändern von Projekten
Anpassen der Protokollierungseinstellungen
Abbrechen des Upgrades und Beenden

Wenn Sie die EINGABETASTE drücken, ohne eine Zahl auszuwählen, wird das erste Element in der Liste ausgewählt.

Während die einzelnen Schritte initialisiert werden, zeigt das Tool möglicherweise Informationen dazu an, was bei der Durchführung des Schritts passieren kann.

Upgraden einer Projektmappe

Wenn Sie ein Upgrade einer Projektmappe durchführen, die mehrere Projekte enthält, müssen Sie auswählen, welches Projekt in der Projektmappe der Einstiegspunkt ist. Basierend auf dem Einstiegspunktprojekt wird ein Abhängigkeitsdiagramm erstellt, um zu bestimmen, welche Projekte in welcher Reihenfolge aktualisiert werden sollen. Wenn die Projektmappe Projekte enthält, die nicht Teil des Abhängigkeitsdiagramms sind, werden diese ignoriert, und Sie müssen diese Projekte separat aktualisieren. Abhängigkeiten werden zuerst aktualisiert, dann das Einstiegspunktprojekt.

Der nächste Schritt besteht darin, das zu aktualisierende Projekt auszuwählen. Die Ausgabe sollte in etwa wie der folgende Codeschnipsel aussehen:

Upgrade Steps

1. [Next step] Select an entrypoint
2. Select project to upgrade

Choose a command:
   1. Apply next step (Select an entrypoint)
   2. Skip next step (Select an entrypoint)
   3. See more step details
   4. Configure logging
   5. Exit

Tipp

Achten Sie auf die Ausgabe der einzelnen Schritte, da sie möglicherweise Informationen zu etwas enthalten, das das Tool nicht aktualisieren kann. Je nach Komplexität Ihrer App müssen Sie möglicherweise weitere Upgradearbeiten nach dem Ausführen des Tools erledigen.

Upgraden des Projekts

Nachdem ein Projekt ausgewählt wurde, wird eine Liste der Upgradeschritte aufgeführt. Der erste Schritt ist ausgewählt, das Projekt zu sichern. Die Liste der Schritte ähnelt dem folgenden Codeschnipsel:

[15:50:50 INF] Initializing upgrade step Back up project

Upgrade Steps

Entrypoint: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj
Current Project: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj

1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
4. Update TFM
5. Update NuGet Packages
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
6. Add template files
7. Update WCF service to CoreWCF (Preview)
8. Upgrade app config files
    a. Convert Application Settings
    b. Convert Connection Strings
    c. Disable unsupported configuration sections
9. Update source code
    a. Apply fix for UA0002: Types should be upgraded
    b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
10. Move to next project

Choose a command:
   1. Apply next step (Back up project)
   2. Skip next step (Back up project)
   3. See more step details
   4. Select different project
   5. Configure logging
   6. Exit

Bei jedem Schritt wird zuerst beschrieben, was er tun wird, und dann werden Sie aufgefordert, ihn auszuführen. Jeder Schritt, den Sie nicht für die Anwendung auswählen, wird übersprungen, wenn das Tool ihn erreicht. Wenn das Tool beispielsweise 7. WCF-Dienst auf CoreWCF (Vorschau) aktualisieren verarbeitet, aber Ihre App keinen WCF-Dienst definiert, wird er übersprungen und Schritt 8 verarbeitet. Wird Schritt 8 wiederum nicht angewendet, wird er ebenfalls übersprungen. Möglicherweise werden viele Schritte übersprungen, während das Tool versucht, den nächsten anzuwendenden Schritt zu finden.

Abschließende Schritte

Nachdem Sie Ihre Projekt upgegradet haben, müssen Sie sie kompilieren und testen. Wahrscheinlich gibt es noch mehr zu tun, um das Upgrade abzuschließen. Es ist möglich, dass die .NET Framework-Version Ihrer App Bibliotheksverweise enthält, die Ihr Projekt gar nicht verwendet und die einfach nur übernommen wurden. Analysieren Sie jeden Verweis, und bestimmen Sie, ob er erforderlich ist. Das Tool hat möglicherweise auch eine falsche Version hinzugefügt oder einen NuGet-Paketverweis auf eine falsche Version upgegradet.

Suchen Sie abschließend nach Möglichkeiten, Ihre App zu modernisieren. Beispiele finden Sie unter Modernisieren nach dem Upgrade von .NET Framework auf .NET.

Freigeben über