Migrar uma aplicação UWP para o WinUI 3

A UWP já não está em desenvolvimento ativo. O WinUI 3 e o SDK de Aplicações Windows são os 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 com anos de amostras UWP, por isso, sem orientação, eles reproduzem os padrões de que estás a tentar afastar-te. Esta página fornece ao seu agente o contexto de que necessita para fazer as coisas corretamente.

Instale o plugin do agente WinUI

A winui-uwp-migration habilidade trata automaticamente das substituições comuns:

gh copilot plugin install winui@awesome-copilot

Consulte o plugin do agente WinUI para todos os detalhes.

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

Encadeamento

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 de voltar via AppWindowTitleBar

Diálogos e seletores

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

Importante

Os selecionadores requerem 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();

Notifications

UWP WinUI 3
Windows.UI.Notifications.ToastNotificationManager Microsoft.Windows.AppNotifications.AppNotificationManager
Windows.UI.Notifications.BadgeUpdateManager Microsoft.Windows.BadgeNotifications.BadgeNotificationManager
Windows.UI.Notifications.TileUpdateManager Os mosaicos foram preteridos — utilize 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 — ver nota)
Application.Current.Resuming AppInstance.GetCurrent().Activated (ver nota)
BackgroundTaskBuilder SDK de Aplicações Windows: tarefas em segundo plano

Note

A migração do ciclo de vida da aplicação WinUI 3 não é uma simples troca de nomes de API. O SDK de Aplicações Windows utiliza um modelo diferente de ativação e suspensão. Trate o código do ciclo de vida como se exigisse uma reescrita dedicada em vez de substituição automática. Consulte a documentação do ciclo de vida SDK de Aplicações Windows para o modelo completo.

Definiçõ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 WinRT fora do espaço de nomes XAML mantêm-se inalteradas.

Prompt inicial

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

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

Adicionar o pacote do SDK de Aplicações Windows:

dotnet add package Microsoft.WindowsAppSDK

Conteúdo relacionado

  • Last updated on