Share via

Migrieren von UWP zum Windows App SDK mit dem .NET-Upgrade-Assistenten

  • Artikel

Der .NET-Upgrade-Assistent (siehe Übersicht über den .NET-Upgrade-Assistenten) ist eine Visual Studio-Erweiterung (empfohlen) und ein Befehlszeilenprogramm, das Sie bei der Migration einer C#-App für die universelle Windows-Plattform (UWP)-App zu einer Windows UI Library (WinUI) 3-App unterstützt, die das Windows App SDK verwendet.

Unsere Roadmap für die UWP-Unterstützung im .NET-Upgrade-Assistent umfasst weitere Verbesserungen der Tools und die Unterstützung der Migration für neue Funktionen. Wenn Sie Probleme im Zusammenhang mit dem .NET-Upgrade-Assistenten feststellen, können Sie diese in Visual Studio unter Hilfe>Feedback senden>Problem melden melden.

Sehen Sie sich auch das GitHub-Repository zum Upgrade-Assistenten an. Dort sind Optionen für die Ausführung des Tools auf der Befehlszeile dokumentiert.

Installieren des .NET-Upgrade-Assistenten

Sie können den .NET-Upgrade-Assistenten als Visual Studio-Erweiterung oder als .NET-Befehlszeilenprogramm installieren. Weitere Informationen finden Sie unter Installieren des .NET-Upgrade-Assistenten.

Zusammenfassung

Wenn Sie den .NET-Upgrade-Assistenten verwenden, um Ihre UWP-App zu migrieren, finden Sie hier die allgemeinen Schritte und Phasen im Migrationsprozess, den das Tool ausführt.

  • Kopiert Ihr Projekt optional und migriert die Kopie. Das ursprüngliche Projekt bleibt unverändert.
  • Migriert Ihr Projekt optional direkt (in dieselben Ordner und Dateien, ohne Ordner umzubenennen) und macht keine Kopie.
  • Das Projekt wird vom .NET Framework-Projektformat auf das .NET SDK-Projektformat aktualisiert.
  • Bereinigt NuGet-Paketverweise. Zusätzlich zu den Paketen, auf die ihre App verweist, enthält die Datei packages.config Verweise auf die Abhängigkeiten dieser Pakete. Wenn Sie beispielsweise einen Verweis auf das Paket A hinzugefügt haben, das vom Paket B abhängt, wird in der Datei packages.config auf beide Pakete verwiesen. Im neuen Projektsystem ist nur der Verweis auf das Paket A erforderlich. In diesem Schritt werden also die Paketverweise analysiert und diejenigen entfernt, die nicht erforderlich sind. Ihre App verweist weiterhin auf .NET Framework-Assemblys. Einige dieser Assemblys sind möglicherweise als NuGet-Pakete verfügbar. In diesem Schritt werden also diese Assemblys analysiert und auf der Verweis auf das entsprechende NuGet-Paket hergestellt.
  • Zielt auf .NET 6 und das Windows App SDK.
  • Ändert den Zielframeworkmoniker (TFM) (siehe Zielframeworks in Projekten im SDK-Format) von .NET Framework zum vorgeschlagenen SDK. Beispiel: net6.0-windows.
  • Migriert Ihren UWP-Quellcode von WinUI 2 zu WinUI 3 und führt quellcodespezifische Codeänderungen durch.
  • Fügt Vorlagen-, Konfigurations- und Codedateien hinzu/aktualisiert sie. Fügen Sie z. B. erforderliche Veröffentlichungsprofile, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml und andere hinzu.
  • Aktualisieren Sie Namespaces und fügen Sie die MainPage-Navigation hinzu.
  • Versucht, APIs zu erkennen und zu korrigieren, die sich zwischen UWP und dem Windows App SDK unterscheiden, und verwendet Aufgabenliste-TODOs, um APIs zu markieren, die nicht mehr unterstützt werden.

Während der Ausführung bietet das Tool außerdem Migrationshinweise in Form von Warnmeldungen in der Ausgabe des Tools und Aufgabenliste-TODOs in Form von Kommentaren im Quellcode Ihres Projekts (zum Beispiel für Fälle, in denen eine vollständig automatisierte Migration Ihres UWP-Quellcodes nicht möglich ist). Ein typischer Aufgabenliste-TODO enthält einen Link zu einem Thema in dieser Migrationsdokumentation. Als Entwickler*in haben Sie immer die Kontrolle über den Migrationsprozess.

Tipp

Alle vom Tool generierten TODOs finden Sie in Visual Studio in der Aufgabenliste.

Hinweis

Nachdem das Tool ausgeführt wurde, gibt es einige Folgeschritte, die Sie bei Bedarf ausführen können. Sie können Ihren Code von App.xaml.old.cs nach App.xaml.cs verschieben und AssemblyInfo.cs aus der Sicherung, die das Tool erstellt, wiederherstellen.

Was das Tool unterstützt

Diese Version des .NET-Upgrade-Assistenten befindet sich derzeit in der Vorschauphase und erhält häufige Updates. Das Tool unterstützt derzeit nur die Programmiersprache C#, nicht C++. Und in den meisten Fällen müssen Sie bei dieser Version in ihrem Projekt zusätzliche Maßnahmen ergreifen, um die Migration abzuschließen.

Das Tool soll Ihr Projekt und Ihren Code so migrieren, dass er kompilierbar ist. Aber einige Funktionen erfordern, dass Sie sie untersuchen und korrigieren (über Aufgabenliste-TODOs). Weitere Informationen darüber, was Sie vor der Migration beachten sollten, finden Sie unter Was wird bei der Migration von UWP zu WinUI 3 unterstützt?.

Aufgrund der folgenden Einschränkungen der aktuellen Version des .NET-Upgrade-Assistenten könnten Sie auch auf eine neuere Version warten, bevor Sie Ihre App migrieren:

  • Das Migrieren von ApplicationView-APIs wird nicht unterstützt.
  • Das Migrieren von AppWindow-verwandten APIs wird nicht unterstützt.

Wo es möglich ist, versucht das Tool, eine Warnung zu erzeugen, und es bewirkt absichtlich, dass Ihr Code nicht kompiliert wird, bis Sie ihn ändern.

  • Benutzerdefinierte Ansichten werden nicht unterstützt. Sie erhalten zum Beispiel keine Warnung oder Korrektur für ein benutzerdefiniertes Dialogfeld, das MessageDialog erweitert und eine API falsch aufruft.
  • Windows-Runtime-Komponenten werden nicht unterstützt.
  • Anwendungen mit mehreren Fenstern werden möglicherweise nicht korrekt migriert.
  • Ein Projekt, das einer nicht standardmäßigen Dateistruktur folgt (z.B., wenn sich App.xaml und App.xaml.cs nicht im Stammordner befinden), wird möglicherweise nicht korrekt migriert.

Das GitHub-Repository des Upgrade-Assistenten dokumentiert Tipps zur Problembehandlung und bekannte Probleme. Wenn Sie bei der Verwendung des Tools auf Probleme stoßen, melden Sie diese bitte in demselben GitHub-Repository und versehen Sie sie mit dem Bereichstag UWP. Dafür bedanken wir uns!

Hinweis

Eine Anleitung zum Migrationsprozess und zu den Unterschieden zwischen den Funktionen und APIs von UWP und Windows App SDK finden Sie unter Migrieren von UWP zum Windows App SDK.

Tipp

Sie können sehen, welche Version des Tools Sie haben, indem Sie den Befehl upgrade-assistant --version eingeben.

Testen des Tools mit dem UWP PhotoLab-Beispiel

Probieren wir den .NET-Upgrade-Assistenten aus.

Als Ausgangsmaterial werden wir die UWP PhotoLab-Beispielanwendung migrieren. PhotoLab ist eine Beispiel-App zum Anzeigen und Bearbeiten von Bilddateien. Es demonstriert XAML-Layout, Datenbindung und Funktionen zur Anpassung der Benutzeroberfläche.

Hinweis

Eine Fallstudie zur vollständigen manuellen Migration des PhotoLab-Beispiels finden Sie unter Eine Windows App SDK-Migration der UWP PhotoLab-Beispielanwendung.

  1. Beginnen Sie mit dem Klonen oder dem Herunterladen des PhotoLab-Beispiel-Quellcodes über den obigen Link.

Tipp

Beachten Sie, dass nach der Verwendung des Tools zur Automatisierung der Migration der App zusätzlicher manueller Aufwand erforderlich ist, um die Migration abzuschließen.

  1. Öffnen Sie die PhotoLab-Lösung in Visual Studio.

  2. Nachdem Sie die Erweiterung .NET-Upgrade-Assistent installiert haben (weitere Informationen weiter oben in diesem Thema unter Installieren des .NET-Upgrade-Assistenten), klicken Sie mit der rechten Maustaste im Projektmappen-Explorer auf das Projekt und klicken Sie auf Upgrade.

  3. Wählen Sie die Option Projekt auf eine neuere .NET-Version aktualisieren aus.

  4. Wählen Sie die Option Direktes Projektupgrade aus.

  5. Wählen Sie ein Zielframework.

  6. Klicken Sie auf Upgradeauswahl.

  7. Der .NET-Upgrade-Assistent wird ausgeführt und verwendet das Visual Studio-Ausgabefenster zum Drucken von Informationen und des Status während der Ausführung.

Sie können die Statusanzeige beobachten, bis der Upgradevorgang abgeschlossen ist.

Die Codemigration für die PhotoLab-Beispiel-App umfasst Folgendes:

  • Änderungen an Inhaltsdialogen und Dateispeicherauswahl-APIs
  • XAML-Update für das Animationspaket
  • Anzeigen von Warnmeldungen und Hinzufügen von Aufgabenliste-TODOs in DetailPage.xaml, DetailPage.xaml.cs und MainPage.xaml.cs für die benutzerdefinierte Zurück-Schaltfläche.
  • Implementieren der Funktionalität der Zurück-Schaltfläche und Hinzufügen eines Aufgabenliste-TODOs zum Anpassen der XAML-Schaltfläche.
  • Es wird ein Link zu einer Dokumentation bereitgestellt, in der Sie mehr über die Implementierung der Zurück-Schaltfläche erfahren können.

Die Versionsnummern in Ihrem resultierenden .csproj werden leicht unterschiedlich sein, aber im Wesentlichen wird sie so aussehen (wobei einige der Eigenschaftsgruppen der Build-Konfiguration der Kürze halber entfernt wurden):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

Wie Sie sehen können, bezieht sich das Projekt jetzt auf das Windows App SDK, WinUI 3 und .NET 6. Nach der Migration von PhotoLab können Sie nun alle neuen Funktionen nutzen, die WinUI 3-Apps zu bieten haben, und Ihre App mit der Plattform erweitern.

Der .NET-Upgrade-Assistent fügt dem Projekt außerdem Analysen hinzu, die bei der Fortsetzung des Upgradevorgangs helfen. Zum Beispiel das NuGet-Paket Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers.

Nachfolgende manuelle Migration

Jetzt können Sie die migrierte PhotoLab-Lösung oder das migrierte Projekt öffnen und die im Quellcode vorgenommenen Änderungen sehen. An dem Projekt muß noch gefeilt werden, bevor die WinUI 3-Version kompiliert wird, läuft und sich wie die UWP-Version verhält.

In der Aufgabenliste in Visual Studio (Ansicht>Aufgabenliste) finden Sie TODOs, die Sie durchführen sollten, um die Migration manuell abzuschließen.

Es ist möglich, dass die UWP (.NET Framework)-Version Ihrer Anwendung Bibliotheksverweise enthielt, die Ihr Projekt nicht wirklich verwendet. Sie müssen jeden Verweis analysieren und bestimmen, ob er gebraucht wird oder nicht. Das Tool könnte auch einen NuGet-Paketverweis auf die falsche Version hinzugefügt oder aktualisiert haben.

Der Upgrade-Assistent bearbeitet nicht das Package.appxmanifest, das einige Änderungen benötigt, um die App zu starten:

  1. Fügen Sie diesen Namespace zum <Paket>-Element des Stamms hinzu:
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. Bearbeiten Sie das <Application>-Element von EntryPoint="appnamehere.App" zu EntryPoint="$targetentrypoint$".

  2. Ersetzen Sie alle angegebenen Capability durch Folgendes:

<rescap:Capability Name="runFullTrust" />

In Ihrer .csproj-Datei müssen Sie möglicherweise die Projektdatei bearbeiten, um <OutputType>WinExe</OutputType> und <UseMaui>False</UseMaui> festzulegen.

Um viele der XAML-Steuerelemente zu verwenden, stellen Sie sicher, dass Ihre app.xaml-Datei die in diesem Beispiel enthaltenen <XamlControlsResources> enthält:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

Tipps zur Problembehandlung

Es gibt mehrere bekannte Probleme, die bei der Verwendung des .NET-Upgrade-Assistenten auftreten können. In einigen Fällen treten Probleme mit dem Tool „try-convert“ auf, das vom .NET-Upgrade-Assistenten intern verwendet wird.

Weitere Tipps zur Problembehandlung und zu bekannten Problemen finden Sie im GitHub-Repository des Upgrade-Assistenten.