Übersicht über den .NET-Upgrade-Assistenten

Neue Versionen von .NET werden im Laufe des Jahres veröffentlicht, mit einer Hauptversion einmal pro Jahr. Der .NET-Upgrade-Assistent hilft Ihnen beim Upgrade von Apps aus früheren Versionen von .NET, .NET Core und .NET Framework auf die neueste Version.

Der .NET-Upgrade-Assistent ist ein Visual Studio-Erweiterungs- und Befehlszeilentool, das zum Aktualisieren von Apps auf die neueste Version von .NET entwickelt wurde.

Probleme im Zusammenhang mit dem .NET-Upgrade-Assistenten können in Visual Studio durch Auswählen von Hilfe>Feedback senden>Problem melden dokumentiert werden.

Installieren des Upgrade-Assistenten

Der .NET-Upgrade-Assistent kann als Visual Studio-Erweiterung oder als .NET-Befehlszeilentool installiert werden. Weitere Informationen finden Sie unter Installieren des .NET-Upgrade-Assistenten.

Unterstützte Sprachen

Die folgenden Codesprachen werden unterstützt:

• C#
• Visual Basic

Unterstützte Projekte

Die folgenden Projekttypen werden unterstützt:

• ASP.NET
• Azure-Funktionen
• Windows Presentation Foundation
• Windows Forms
• Klassenbibliotheken
• Konsolen-Apps
• .NET Native UWP
• Xamarin Forms
• .NET MAUI

Upgradepfade

Die folgenden Upgradepfade werden unterstützt:

• .NET Framework zu .NET
• .NET Core zu .NET
• UWP zu WinUI 3
• Vorherige .NET-Version auf die neueste .NET-Version
• Azure Functions v1-v3 bis v4 isoliert
• Xamarin Forms zu .NET MAUI
  • XAML-Dateitransformationen unterstützen nur das Upgrade von Namespaces. Für umfassendere Transformationen verwenden Sie Visual Studio 2022 Version 17.6 oder höher.

Upgrade mit der Visual Studio-Erweiterung

Nachdem Sie die Erweiterung des .NET-Upgrade-Assistenten installiert haben, klicken Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Upgrade aus.

Achtung

Stellen Sie sicher, dass Sie Ihre Projekte vor dem Upgrade sichern, wenn Sie keine Quellcodeverwaltung verwenden.

Es wird eine Registerkarte geöffnet, die je nach Projekttyp verschiedene Upgradearten bereitstellt:

• Direktes Projektupgrade

  Mit dieser Option wird Ihr Projekt aktualisiert, ohne eine Kopie zu erstellen.

• Paralleles Projektupgrade

  Kopiert Ihr Projekt und aktualisiert die Kopie, sodass das ursprüngliche Projekt nicht geändert wird.

• Parallel inkrementell

  Eine gute Wahl für komplizierte Web-Apps. Das Upgrade von ASP.NET auf ASP.NET Core erfordert einiges an Arbeit und manchmal manuelles Refactoring. Dieser Modus platziert ein .NET-Projekt neben Ihrem vorhandenen .NET Framework-Projekt und leitet Endpunkte weiter, die im .NET-Projekt implementiert sind, während alle anderen Aufrufe an die .NET Framework Anwendung gesendet werden.

  In diesem Modus können Sie Ihre ASP.NET- oder Bibliotheks-App schrittweise aktualisieren.

Nachdem Ihre App aktualisiert wurde, wird ein Statusbildschirm angezeigt, auf dem alle Artefakte im Zusammenhang mit Ihrem Projekt angezeigt werden, die dem Upgrade zugeordnet wurden. Jedes Upgradeartefakt kann erweitert werden, um weitere Informationen zum Status zu erhalten. In der folgenden Liste werden die Statussymbole beschrieben:

• Ausgefülltes grünes Häkchen: Das Artefakt wurde aktualisiert und erfolgreich abgeschlossen.
• Nicht ausgefülltes grünes Häkchen: Das Tool hat nichts über das zu aktualisierende Artefakt gefunden.
• Gelbes Warnzeichen: Das Artefakt wurde aktualisiert, aber es gibt wichtige Informationen, die Sie berücksichtigen sollten.
• Rotes X: Das Artefakt sollte aktualisiert werden, aber das Upgrade ist fehlgeschlagen.

Darüber hinaus werden die Aktionen, die der Upgrade-Assistent ausgeführt hat, im Fenster Ausgabe unter der Quelle Upgrade-Assistent protokolliert, wie in der folgenden Abbildung dargestellt:

Nach dem Upgrade Ihres Projekts müssen Sie es sorgfältig testen.

Upgrade mit dem CLI-Tool

Nachdem Sie das CLI-Tool des .NET-Upgrade-Assistenten installiert haben, öffnen Sie ein Terminalfenster, und navigieren Sie zu dem Verzeichnis, das das Projekt enthält, das Sie aktualisieren möchten. Sie können den Befehl upgrade-assistant --help verwenden, um die verfügbaren Optionen anzuzeigen, die die CLI bereitstellt.

Achtung

Stellen Sie sicher, dass Sie Ihre Projekte vor dem Upgrade sichern, wenn Sie keine Quellcodeverwaltung verwenden.

Führen Sie das Tool mit dem Befehl upgrade-assistant upgrade aus. Alle Projekte aus dem aktuellen Ordner und darunter werden aufgeführt. Das CLI-Tool bietet eine interaktive Möglichkeit, das zu aktualisierende Projekt auszuwählen. Verwenden Sie die Pfeiltasten, um ein Element auszuwählen, und drücken Sie die Eingabetaste , um das Element auszuführen. Wählen Sie das Projekt aus, das Sie aktualisieren möchten. Im in diesem Artikel bereitgestellten Beispiel befinden sich vier Projekte unter dem aktuellen Ordner:

 Selected options
───────────────────────────────────────────────────────────
 No options specified, follow steps below to continue

 Steps
─────────────────
 Source project
─────────────────

Which project do you want to upgrade (found 9)?

> MatchingGame (winforms\MatchingGame\MatchingGame.csproj)
  MatchingGame.Logic (winforms\MatchingGame.Logic\MatchingGame.Logic.csproj)
  StarVoteControl (csharp\StarVoteControl\StarVoteControl.csproj)
  WebSiteRatings (csharp\WebSiteRatings\WebSiteRatings.csproj)

  Navigation
    Exit

Abhängig vom Projekt, das Sie aktualisieren, wird Ihnen möglicherweise eine Option angezeigt, um anzugeben, wie das Upgrade fortgesetzt werden soll:

• Direktes Projektupgrade

  Mit dieser Option wird Ihr Projekt aktualisiert, ohne eine Kopie zu erstellen.

• Paralleles Projektupgrade

  Diese Option ist nur für .NET Framework Projekte verfügbar. Kopiert Ihr Projekt und aktualisiert die Kopie, sodass das ursprüngliche Projekt nicht geändert wird.

 Selected options
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Source project     C:\Code\winforms\MatchingGame\MatchingGame.csproj

 Steps
───────────────────────────────
 Source project / Upgrade type
───────────────────────────────

How do you want to upgrade project MatchingGame?

> In-place project upgrade
  Side-by-side project upgrade

  Navigation
    Back
    Exit

Wenn nach diesem Schritt mehr als ein aktualisierbares Zielframework vorhanden ist, wählen Sie ein Ziel aus:

 Selected options
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Source project     C:\Code\Work\dotnet\dotnet-docs\docs\core\porting\snippets\upgrade-assistant-wpf-framework\winforms\MatchingGame\MatchingGame.csproj
 Ugrade type        Inplace

 Steps
──────────────────────────────────────────────────
 Source project / Ugrade type / Target framework
──────────────────────────────────────────────────

What is your preferred target framework?

> .NET 6.0 (Supported until November, 2024)
  .NET 7.0 (Supported until May, 2024)
  .NET 8.0 (Try latest preview features)

  Navigation
    Back
    Exit

Nach dem Upgrade Ihres Projekts müssen Sie es sorgfältig testen.