Migrera från UWP till Windows App SDK med .NET Upgrade Assistant

.NET Upgrade Assistant (se Översikt över .NET Upgrade Assistant) är ett Visual Studio-tillägg (rekommenderas) och ett kommandoradsverktyg som kan hjälpa till med att migrera en C# UWP-app (Universal Windows Platform) till en WinUI 3-app som använder Windows App SDK.

Vår översikt för UWP-stöd i .NET Upgrade Assistant innehåller ytterligare verktygsförbättringar och tillägg av migreringsstöd för nya funktioner. Om du hittar problem som rör .NET-uppgraderingsassistenten kan du skicka dem i Visual Studio genom att välja Hjälp>Skicka feedback>Rapportera ett problem.

Se även Upgrade Assistant GitHub-lagringsplatsen. Alternativ för att köra verktyget på kommandoraden dokumenteras där.

Installera .NET Upgrade Assistant

Du kan installera .NET Upgrade Assistant som ett Visual Studio-tillägg eller som ett .NET-kommandoradsverktyg. Mer information finns i Installera .NET Upgrade Assistant.

Sammanfattning

När du använder .NET Upgrade Assistant för att migrera din UWP-app, här är de övergripande stegen och stegen i migreringsprocessen som verktyget utför.

• Du har möjlighet att kopiera ditt projekt och migrera kopian. Det ursprungliga projektet lämnas oförändrat.
• Du kan också migrera projektet på plats (i samma mappar och filer, utan att byta namn på mappar). och gör ingen kopia.
• Uppgraderar projektet från .NET Framework-projektformatet till det senaste .NET SDK-projektformatet.
• Rensar NuGet-paketreferenser. Förutom de paket som refereras till av din app innehåller packages.config-filen referenser till beroendena för dessa paket. Om du till exempel har lagt till en referens till paketet A, som är beroende av paketet B, refereras båda paketen i filen packages.config. I det nya projektsystemet krävs bara referensen till paket A. I det här steget analyseras paketreferenserna och de som inte krävs tas bort. Appen refererar fortfarande till .NET Framework-sammansättningar. Vissa av dessa sammansättningar kan vara tillgängliga som NuGet-paket. Det här steget analyserar därför dessa sammansättningar och refererar till lämpligt NuGet-paket.
• Riktar sig mot .NET 6 och Windows App SDK.
• Ändrar målramverkets moniker (TFM) (se Målramverk i SDK-liknande projekt) från .NET Framework till det föreslagna SDK:t. Till exempel net6.0-windows.
• Migrerar UWP-källkoden från WinUI 2 till WinUI 3 och utför källspecifika kodändringar.
• Lägger till/uppdaterar alla mall-, konfigurations- och kodfiler. Du kan exempelvis lägga till nödvändiga publiceringsprofiler som App.xaml.cs, MainWindow.xaml.cs, MainWindow.xamloch andra.
• Uppdaterar namnområden och lägger till MainPage navigering.
• Försöker identifiera och åtgärda API:er som skiljer sig mellan UWP och Windows App SDK och använder aktivitetslista TODO:er för att markera API:er som inte längre stöds.

När det körs syftar verktyget också till att ge migreringsvägledning i form av varningsmeddelanden i verktygets utdata, och uppgiftslista TODO:er i form av kommentarer i projektets källkod (till exempel för fall där helt automatiserad migrering av UWP-källkoden inte är möjlig). En typisk uppgiftslista TODO innehåller en länk till ett ämne i den här migreringsdokumentationen. Som utvecklare har du alltid kontroll över migreringsprocessen.

Vad verktyget stöder

Den här versionen av .NET Upgrade Assistant är för närvarande i förhandsversion och får frekventa uppdateringar. Verktyget stöder för närvarande endast programmeringsspråket C#. inte C++. Och i de flesta fall med den här versionen kräver projektet ytterligare arbete från dig för att slutföra migreringen.

Verktyget syftar till att migrera projektet och koden så att det kompileras. Men vissa funktioner kräver att du undersöker och åtgärdar dem (via uppgiftslista TODO:er). Mer information om vad du bör tänka på innan du migrerar finns i Vad som stöds när du migrerar från UWP till WinUI 3.

På grund av följande begränsningar i den aktuella versionen av .NET Upgrade Assistant kan du välja att vänta på en framtida version innan du migrerar din app:

• Migrering från ApplicationView API:er stöds inte.
• Migrering från AppWindow-relaterade API:er stöds inte.

När det är möjligt försöker verktyget generera en varning. och det gör avsiktligt att koden inte kompileras förrän du ändrar den.

• Anpassade vyer stöds inte. Du får till exempel ingen varning eller korrigering för en anpassad dialogruta som utökar MessageDialogoch anropar ett API felaktigt.
• Windows Runtime-komponenter stöds inte.

• Appar med flera fönster kanske inte migreras korrekt.
• Ett projekt som följer en icke-standardfilstruktur (till exempel App.xaml och App.xaml.cs inte finns i rotmappen) kanske inte migreras korrekt.

GitHub-lagringsplatsen för Upgrade Assistant dokumenterar felsökningstips och kända problem. Om du hittar några problem när du använder verktyget kan du rapportera dem på samma GitHub-lagringsplats och tagga dem med en områdestagg på UWP. Vi uppskattar det!

Provkör verktyget med UWP PhotoLab-exemplet

Nu ska vi ta .NET Upgrade Assistant för en provkörning.

Vi kommer att migrera UWP PhotoLab exempelprogram som källmaterial. PhotoLab är en exempelapp för att visa och redigera bildfiler. Den visar funktioner för XAML-layout, databindning och UI-anpassning.

1. Börja med att klona eller ladda ned PhotoLab-exempelkällkoden från länken ovan.

1. Öppna PhotoLab-lösningen i Visual Studio.

2. När du har installerat tillägget .NET Upgrade Assistant (se Installera .NET Upgrade Assistant tidigare i det här avsnittet) högerklickar du på projektet i Solution Exploreroch klickar på Uppgradera.

3. Välj alternativet Uppgradera projektet till en nyare .NET-version .

4. Välj alternativet projektuppgradering på plats.

5. Välj ett målsatt ramverk.

6. Klicka på Uppgradera markering.

7. När .NET Upgrade Assistant körs använder den fönstret Visual Studio Output för att skriva ut information och status.

Du kan övervaka förloppsindikatorn tills uppgraderingen har slutförts.

Kodmigrering för PhotoLab exempelapp innehåller:

• Ändringar i api:er för innehållsdialogruta och filsparväljare.
• XAML-uppdatering för paketet Animeringar.
• Visar varningsmeddelanden och lägger till aktivitetslista att göra-listor i DetailPage.xaml, DetailPage.xaml.csoch MainPage.xaml.cs för anpassad bakåtknapp.
• Implementera bakåtknappsfunktionen och lägga till en aktivitetslista TODO för att anpassa XAML-knappen.
• En länk till dokumentationen tillhandahålls som du kan använda för att lära dig mer om implementering av bakåtknappar.

Versionsnumren i din resulterande .csproj kommer att vara något annorlunda, men i huvudsak ser det ut så här (med några av egenskapsgrupperna för byggkonfigurationen borttagna för korthet):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.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>win-x86;win-x64;win-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>

Som du ser refererar projektet nu till Windows App SDK, WinUI 3 och .NET 6. Nu när PhotoLab- har migrerats kan du dra nytta av alla nya funktioner som WinUI 3-appar har att erbjuda och utöka din app med plattformen.

Dessutom lägger .NET Upgrade Assistant till analysverktyg i projektet som hjälper dig att fortsätta med uppgraderingsprocessen. Till exempel Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers NuGet-paketet.

Manuell migrering som uppföljning

Nu kan du öppna den migrerade PhotoLab- lösning eller projekt och se de ändringar som har gjorts i källkoden. Projektet behöver lite mer arbete för att slutföra att koppla ihop saker innan WinUI 3-versionen byggs, körs och beter sig som UWP-versionen.

Se uppgiftslista i Visual Studio (View>Task List) för TODO:er som du bör vidta för att slutföra migreringen manuellt.

Det är möjligt att UWP-versionen (.NET Framework) av din app innehåller biblioteksreferenser som projektet faktiskt inte använder. Du måste analysera varje referens och avgöra om den krävs eller inte. Verktyget kan också ha lagt till eller uppgraderat en NuGet-paketreferens till fel version.

Uppgraderingsassistenten redigerar inte Package.appxmanifest, vilket kommer att behöva vissa ändringar för att appen ska kunna starta.

1. Lägg till det här namnområdet i rotpaketelementet<>:

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

2. <Redigera programelementet> från EntryPoint="appnamehere.App" tillEntryPoint="$targetentrypoint$"

3. Ersätt alla angivna Capability med detta:

<rescap:Capability Name="runFullTrust" />

I din .csproj-fil kan du behöva redigera projektfilen för att ange <OutputType>WinExe</OutputType> och <UseMaui>False</UseMaui>.

Om du vill använda många av XAML-kontrollerna, se till att app.xaml-filen innehåller <XamlControlsResources>, till exempel:

<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>

Felsökningstips

Det finns flera kända problem som kan uppstå när du använder .NET Upgrade Assistant. I vissa fall är dessa problem med try-convert-verktyget som .NET Upgrade Assistant använder internt.

Mer felsökningstips och kända problem finns dock i Upgrade Assistant GitHub-lagringsplatsen.

Se även

• Windows App SDK och Windows-versioner som stöds