Migrazione da UWP a Windows App SDK con .NET Upgrade Assistant

  • Articolo

L'Assistente aggiornamento .NET (vedere Panoramica dell'Assistente aggiornamento .NET) è un'estensione di Visual Studio (scelta consigliata) e uno strumento da riga di comando che consente di eseguire la migrazione di un'app UWP (Universal Windows Platform) per C# a un'app di WinUI 3 che usa Windows App SDK.

La roadmap per il supporto UWP in .NET Upgrade Assistant include ulteriori miglioramenti agli strumenti e l'aggiunta del supporto per la migrazione per le nuove funzionalità. Se si riscontrano problemi relativi a .NET Upgrade Assistant, è possibile archiviarli all'interno di Visual Studio selezionando Guida>Invia commenti e suggerimenti>Segnala un problema.

Vedere anche il repository GitHub di Assistente aggiornamento. Le opzioni per l'esecuzione dello strumento nella riga di comando sono documentate in questa posizione.

Installare Assistente aggiornamento .NET

È possibile installare .NET Upgrade Assistant come estensione di Visual Studio o come strumento da riga di comando .NET. Per altre info, vedere Installa .NET Upgrade Assistant.

Riepilogo

Ecco i passaggi e le fasi generali del processo di migrazione eseguito dallo strumento quando si tratta di utilizzare .NET Upgrade Assistant per eseguire la migrazione dell'app UWP.

  • Facoltativamente, copia il progetto ed esegue la migrazione della copia; lasciando invariato il progetto originale.
  • Facoltativamente, esegue la migrazione sul posto del progetto (nelle stesse cartelle e file, senza rinominare le cartelle); e non crea una copia.
  • Aggiorna il progetto dal formato .NET Framework al formato .NET SDK più recente.
  • Pulisce i riferimenti al pacchetto NuGet. Oltre ai pacchetti a cui fa riferimento l'app, il packages.config file contiene riferimenti alle dipendenze di tali pacchetti. Ad esempio, se è stato aggiunto un riferimento al pacchetto A, che dipende dal pacchetto B, nel file verrà fatto riferimento a entrambi i packages.config pacchetti. Nel nuovo sistema di progetto, è necessario solo il riferimento al pacchetto A. Questo passaggio analizza dunque i riferimenti al pacchetto e rimuove quelli che non sono necessari. L'app fa ancora riferimento agli assembly .NET Framework. Alcuni di questi assembly potrebbero essere disponibili come pacchetti NuGet. Questo passaggio analizza quindi tali assembly e fa riferimento al pacchetto NuGet appropriato.
  • Inoltre è destinato a .NET 6 e Windows App SDK.
  • Modifica il moniker del framework di destinazione (TFM) (vedere Framework di destinazione nei progetti in stile SDK) da .NET Framework all'SDK suggerito. Ad esempio: net6.0-windows.
  • Esegue la migrazione del codice sorgente UWP da WinUI 2 a WinUI 3, eseguendo modifiche al codice specifiche dell'origine.
  • Aggiunge/aggiorna qualsiasi modello, configurazione e file di codice. Ad esempio, aggiungendo i profili di pubblicazione necessari, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml e altri.
  • Aggiornare gli spazi dei nomi e aggiungere lo spostamento di MainPage .
  • Tenta di rilevare e correggere le API diverse tra la piattaforma UWP eWindows App SDK; in più, usa gli elementi toDO di Elenco attività per contrassegnare le API non più supportate.

Durante l'esecuzione, lo strumento mira anche a fornire indicazioni sulla migrazione sotto forma di messaggi di avviso all'interno dell'output dello strumento e gli elementi TODO elenco attività sotto forma di commenti all'interno del codice sorgente del progetto (ad esempio, nei casi in cui non è possibile eseguire la migrazione completamente automatizzata del codice sorgente UWP). Un tipico elemento TODO Elenco attività include un collegamento a un argomento in questa documentazione sulla migrazione. In qualità di sviluppatore, si ha sempre il controllo del processo di migrazione.

Suggerimento

Per visualizzare tutti i TODO generati dallo strumento, esaminare Elenco attività in Visual Studio.

Nota

Al termine dell'esecuzione dello strumento, è possibile eseguire alcuni passaggi di completamento, se necessario. È possibile spostare il codice da App.xaml.old.cs a App.xaml.cs; inoltre è possibile eseguire il ripristino AssemblyInfo.cs dal backup creato dallo strumento.

Elementi supportati dallo strumento

Questa versione di .NET Upgrade Assistant è attualmente in anteprima e riceve aggiornamenti frequenti. Attualmente lo strumento supporta solo il linguaggio di programmazione C#; non C++. E nella maggior parte dei casi con questa versione, il progetto richiederà ulteriori sforzi da parte dell'utente per completare la migrazione.

Lo strumento mira a eseguire la migrazione del progetto e del codice in modo che venga compilato. Tuttavia, alcune funzionalità richiedono l'analisi e la correzione (tramite gli elementi TODO elenco attività). Per altre informazioni su quel che c'è da considerare prima della migrazione, vedere Elementi supportati durante la migrazione da UWP a WinUI 3.

A causa delle limitazioni seguenti della versione corrente di .NET Upgrade Assistant, è possibile scegliere di attendere una versione futura prima della migrazione dell'app:

Laddove possibile, lo strumento tenta di generare un avviso; e provoca intenzionalmente la compilazione del codice fino a quando non viene modificata.

  • Le visualizzazioni personalizzate non sono supportate. Ad esempio, non si riceverà un avviso o una correzione per una finestra di dialogo personalizzata che estende MessageDialog e richiederà un'API in modo errato.
  • I componenti Windows Runtime non sono supportati.
  • È possibile che la migrazione delle app a più finestre non venga eseguita correttamente.
  • Un progetto che segue una struttura di file non standard (ad esempio App.xaml e App.xaml.cs non presente nella cartella radice) potrebbe non essere migrato correttamente.

Il repository GitHub di Assistente aggiornamento documenta suggerimenti e problemi noti per la risoluzione dei problemi. Se si verificano problemi durante l'uso dello strumento, segnalarli nello stesso repository di GitHub, contrassegnandoli con un tag di area di UWP. Lo apprezziamo!

Nota

Per indicazioni sul processo di migrazione e sulle differenze tra le funzionalità e le API UWP e Windows App SDK, vedere Migrazione dalla piattaforma UWP a Windows App SDK.

Suggerimento

È possibile visualizzare la versione dello strumento disponibile eseguendo il comando upgrade-assistant --version.

Eseguire il test drive dello strumento con l'esempio PhotoLab UWP

Si prenda l'Assistente aggiornamento .NET per un test drive.

Come materiale di origine, verrà eseguita la migrazione dell'applicazione UWP Campione PhotoLab. PhotoLab è un'app campione per la visualizzazione e la modifica dei file di immagine. Illustra il layout XAML, l'associazione dati e le funzionalità di personalizzazione dell'interfaccia utente.

Nota

È possibile visualizzare un case study dell'esempio PhotoLab di cui viene eseguita la migrazione completa manualmente in Migrazione Windows App SDK dell'app campione PhotoLab UWP.

  1. Iniziare clonando o scaricando il codice sorgente dell'esempio PhotoLab dal collegamento precedente.

Suggerimento

Tenere presente che, dopo aver usato lo strumento per automatizzare la migrazione dell'app, sarà necessario un ulteriore sforzo manuale per completare la migrazione.

  1. Aprire la soluzione in Microsoft Visual Studio.

  2. Dopo aver installato l'estensione .NET Upgrade Assistant (vedere Installazione di .NET Upgrade Assistant in precedenza in questo argomento), fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Aggiorna.

  3. Scegliere l'opzione Aggiorna progetto a una versione .NET più recente.

  4. Scegliere l'opzione Aggiornamento progetto sul posto .

  5. Scegliere un framework di destinazione:

  6. Fare clic su Selezione aggiornamento.

  7. Viene eseguito .NET Upgrade Assistant e utilizzata la finestra Output di Visual Studio per stampare le informazioni e lo stato man mano che passa.

È possibile monitorare la barra di stato fino a completare l'operazione di aggiornamento.

La migrazione del codice per l'app campione PhotoLab include quanto segue:

  • Modifiche alle API di selezione file e finestra di dialogo contenuto.
  • Aggiornamento XAML per il pacchetto Animations.
  • Visualizzazione dei messaggi di avviso e aggiunta degli elementi TODO elenco attività in DetailPage.xaml, DetailPage.xaml.cs e MainPage.xaml.cs per il pulsante Indietro personalizzato.
  • Implementazione della funzionalità del pulsante Indietro e aggiunta di un elemento TODO elenco attività per personalizzare il pulsante XAML.
  • Viene fornito un collegamento alla documentazione che è possibile usare per altre informazioni sull'implementazione del pulsante Indietro.

I numeri di versione nel risultato .csproj saranno leggermente diversi, ma essenzialmente sarà simile al seguente (con alcuni dei gruppi di proprietà di configurazione di compilazione rimossi per brevità):

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

Come si può notare, il progetto fa ora riferimento a Windows App SDK, WinUI 3 e .NET 6. Una volta che è stata eseguita la migrazione di PhotoLab , è possibile sfruttare tutte le nuove funzionalità offerte dalle app WinUI 3 e aumentare l'app con la piattaforma.

Inoltre, .NET Upgrade Assistant aggiunge analizzatori al progetto che consentono di continuare con il processo di aggiornamento. Ad esempio, il pacchetto NuGet Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers .

Completamento della migrazione manuale

A questo punto è possibile aprire la soluzione o il progetto PhotoLab migrato e visualizzare le modifiche apportate nel codice sorgente. Il progetto richiede un po' di lavoro per completare l'associazione prima delle build, delle versioni di WinUI 3, delle esecuzioni e del comportamento come la versione UWP.

Per i TODO da eseguire in modo da completare manualmente la migrazione, vedere Elenco attività in Visual Studio (Visualizza>Elenco attività).

È possibile che la versione UWP (.NET Framework) dell'app contenga riferimenti a librerie che il progetto non usa effettivamente. Sarà necessario analizzare ogni riferimento e determinare se è richiesto o meno. È anche possibile che lo strumento abbia aggiunto o aggiornato un riferimento a un pacchetto NuGet alla versione errata.

L'Assistente aggiornamento non modifica Package.appxmanifest, che richiederà alcune modifiche affinché l'app venga avviata:

  1. Aggiungere questo spazio dei nomi nell'elemento radice <Pacchetto> :
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. Modificare l'elemento <Applicazione> da EntryPoint="appnamehere.App" a EntryPoint="$targetentrypoint$"

  2. Sostituire qualsiasi elemento specificato Capability con il comando seguente:

<rescap:Capability Name="runFullTrust" />

Nel file .csproj potrebbe essere necessario modificare il file di progetto per impostare <OutputType>WinExe</OutputType> e <UseMaui>False</UseMaui>.

Per usare molti dei controlli XAML, assicurarsi che il app.xaml file includa , <XamlControlsResources>, come in questo esempio:

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

Suggerimenti per la risoluzione dei problemi

Quando si usa .NET Upgrade Assistant, possono verificarsi diversi problemi noti. In alcuni casi, questi problemi riguardano lo strumento try-convert usato internamente da .NET Assistente aggiornamento.

Per altri suggerimenti e problemi noti per la risoluzione dei problemi, vedere il repository di GitHub Assistente aggiornamento.

Vedi anche