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

As tabelas seguintes resumem as substituições de API mais comuns. Para o mapeamento detalhado completo — incluindo membros, propriedades e APIs menos comuns — veja Mapear APIs e bibliotecas UWP para o SDK de Aplicações Windows.

Namespaces

Encadeamento

Windowing

Diálogos e seletores

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

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

Notifications

Rede e HTTP

Navegação

Padrões MVVM

dotnet add package CommunityToolkit.Mvvm

Ciclo de vida do aplicativo

Definições e armazenamento

var appData = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "YourAppName");
Directory.CreateDirectory(appData);
var json = JsonSerializer.Serialize(data);
await File.WriteAllTextAsync(Path.Combine(appData, "settings.json"), json);

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.

Controlos sem equivalente direto

Alguns controlos UWP não existem no WinUI 3. Escolha um substituto com base no seu cenário:

Tinta, Win2D e impressão

Estes subsistemas requerem passos específicos de migração para além das alterações no namespace.

Tinta do Windows

As InkCanvas APIs e InkPresenter mudam-se para Microsoft.UI.Input.Inking mas são idênticas de resto. A única alteração não óbvia é CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() e LoadAsync() ainda assim requerem IRandomAccessStream. Ponte a partir dos System.IO ribeiros:

// Saving ink strokes to a file using System.IO
using var memoryStream = new MemoryStream();
using var ras = memoryStream.AsRandomAccessStream();
await inkStrokeContainer.SaveAsync(ras);
await File.WriteAllBytesAsync(filePath, memoryStream.ToArray());

// Loading ink strokes from a file
var bytes = await File.ReadAllBytesAsync(filePath);
using var ms = new MemoryStream(bytes);
using var ras = ms.AsRandomAccessStream();
await inkStrokeContainer.LoadAsync(ras);

Win2D

O nome do pacote Win2D mudou, mas a superfície da API é idêntica:

Todas Microsoft.Graphics.Canvas.* as APIs (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) funcionam da mesma forma. Só a referência do pacote NuGet precisa de ser atualizada.

Impressão

A impressão UWP utiliza PrintManager.GetForCurrentView(). O WinUI 3 requer interoperação entre janelas:

// UWP
var printManager = PrintManager.GetForCurrentView();
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManager.ShowPrintUIAsync();

// WinUI 3 — must pass window handle
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
var printManager = PrintManagerInterop.GetForWindow(hwnd);
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManagerInterop.ShowPrintUIForWindowAsync(hwnd);

As PrintDocument APIs de renderização (Paginate, GetPreviewPage, AddPages) 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
- Pivot → TabView, NavigationView (top mode), or RadioButtons (no direct equivalent)
- InkToolbar custom subclasses → rebuild as CommandBar with AppBarToggleButton
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- Windows.UI.Input.Inking.* → Microsoft.UI.Input.Inking.*

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
x:Bind defaults to Mode=OneTime. Add Mode=OneWay for any binding that should update at runtime.
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

• Guia de migração do SDK de Aplicações Windows — guia manual completo de migração
• Mapear APIs e bibliotecas UWP para o SDK de Aplicações Windows — tabela abrangente de mapeamento da API
• O que é suportado ao migrar de UWP para WinUI — estado do suporte a funcionalidades
• Migrar de WPF