Migrar um aplicativo UWP para o WinUI 3

A UWP não está mais em desenvolvimento ativo. O WinUI 3 e o SDK do Aplicativo Windows são seus sucessores e as ferramentas de IA podem automatizar a maior parte da migração. O principal desafio é que os modelos de IA foram treinados em anos de exemplos UWP, portanto, sem orientação, eles reproduzem os padrões dos quais você está tentando se afastar. Esta página fornece ao seu agente o contexto necessário para acertar.

Instalar o plug-in do agente WinUI

A habilidade winui-uwp-migration faz automaticamente as substituições comuns:

gh copilot plugin install winui@awesome-copilot

Consulte o plug-in do agente WinUI para obter detalhes completos.

Tabela de substituição de API

Namespaces

UWP WinUI 3
Windows.UI.Xaml.* Microsoft.UI.Xaml.*
Windows.UI.Xaml.Controls.* Microsoft.UI.Xaml.Controls.*
Windows.UI.Xaml.Media.* Microsoft.UI.Xaml.Media.*
Windows.UI.Composition Microsoft.UI.Composition

Threading

UWP WinUI 3
CoreDispatcher DispatcherQueue
Dispatcher.RunAsync(...) DispatcherQueue.TryEnqueue(...)
CoreApplication.MainView.CoreWindow.Dispatcher this.DispatcherQueue (de um Window ou Page)

Windowing

UWP WinUI 3
ApplicationView AppWindow
ApplicationView.GetForCurrentView() AppWindow.GetFromWindowId(...)
ApplicationViewTitleBar AppWindowTitleBar
CoreWindow Microsoft.UI.Xaml.Window
SystemNavigationManager Botão Voltar por meio de AppWindowTitleBar

Caixas de diálogo e seletores

UWP WinUI 3
MessageDialog ContentDialog (set XamlRoot)
FileOpenPicker FileOpenPicker + InitializeWithWindow
FileSavePicker FileSavePicker + InitializeWithWindow
FolderPicker FolderPicker + InitializeWithWindow

Importante

Os seletores exigem InitializeWithWindow antes de chamar PickSingleFileAsync (ou semelhante):

var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

ContentDialog requer XamlRoot (não InitializeWithWindow):

var dialog = new ContentDialog { XamlRoot = this.Content.XamlRoot, ... };
await dialog.ShowAsync();

Notificações

UWP WinUI 3
Windows.UI.Notifications.ToastNotificationManager Microsoft.Windows.AppNotifications.AppNotificationManager
Windows.UI.Notifications.BadgeUpdateManager Microsoft.Windows.BadgeNotifications.BadgeNotificationManager
Windows.UI.Notifications.TileUpdateManager Os blocos são preteridos – use notificações ou widgets
UWP WinUI 3
Frame.Navigate(typeof(MyPage)) Frame.Navigate(typeof(MyPage)) — inalterado
SystemNavigationManager.BackRequested Manipular via NavigationView ou AppWindow
Windows.UI.Core.Preview.SystemNavigationManagerPreview evento AppWindow.Closing

Ciclo de vida do aplicativo

UWP WinUI 3
Application.Current.Suspending Microsoft.Windows.AppLifecycle (requer alterações arquitetônicas — consulte a observação)
Application.Current.Resuming AppInstance.GetCurrent().Activated (consulte a nota)
BackgroundTaskBuilder Tarefas em Segundo Plano do SDK do Aplicativo Windows

Note

A migração do ciclo de vida do aplicativo WinUI 3 não é uma simples troca de nomes de API. O SDK do Aplicativo Windows usa um modelo de ativação e suspensão diferente. Trate o código do ciclo de vida como exigindo uma reescrita dedicada em vez de uma substituição automatizada. Consulte a documentação do ciclo de vida SDK do Aplicativo Windows para obter o modelo completo.

Configurações e armazenamento

UWP WinUI 3
ApplicationData.Current.LocalSettings Inalterado
ApplicationData.Current.LocalFolder Inalterado
Windows.Storage.KnownFolders Inalterado

APIs que não mudam

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color e a maioria das APIs do WinRT fora do namespace XAML não são alteradas.

Prompt de início

I'm migrating a UWP app to WinUI 3 using the Windows App SDK.

Apply these substitutions:
- Windows.UI.Xaml.* → Microsoft.UI.Xaml.*
- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue
- ApplicationView → AppWindow + AppWindowTitleBar
- CoreWindow → Microsoft.UI.Xaml.Window
- MessageDialog → ContentDialog (set XamlRoot, not InitializeWithWindow)
- FileOpenPicker / FileSavePicker / FolderPicker → add InitializeWithWindow
- Windows.UI.Notifications → Microsoft.Windows.AppNotifications
- SystemNavigationManager.BackRequested → NavigationView back handling

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Flag any APIs without a direct WinUI 3 equivalent rather than guessing.

Alterações no arquivo do projeto

Substitua a estrutura alvo do UWP:

<!-- Before (UWP) -->
<TargetPlatformVersion>10.0.19041.0</TargetPlatformVersion>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

<!-- After (WinUI 3) -->
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<WindowsSdkPackageVersion>10.0.19041.31</WindowsSdkPackageVersion>

Adicione o pacote SDK do Aplicativo Windows:

dotnet add package Microsoft.WindowsAppSDK

Conteúdo relacionado

  • Last updated on