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

As tabelas a seguir resumem as substituições de API mais comuns. Para obter o mapeamento completo e detalhado — incluindo membros, propriedades e APIs menos comuns — consulte Mapeando APIs e bibliotecas UWP para o SDK do Aplicativo Windows.

Namespaces

Threading

Windowing

Caixas de diálogo 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();

Notificações

Rede e HTTP

Navigation

Padrões MVVM

dotnet add package CommunityToolkit.Mvvm

Ciclo de vida do aplicativo

Configuraçõ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 do WinRT fora do namespace XAML não são alteradas.

Controles sem um equivalente direto

Alguns controles UWP não existem no WinUI 3. Escolha uma substituição com base em seu cenário:

Tinta, Win2D e impressão

Esses subsistemas exigem etapas de migração específicas além das alterações de namespace.

Tinta do Windows

As APIs InkCanvas e InkPresenter foram migradas para Microsoft.UI.Input.Inking, mas, fora isso, são idênticas. A única alteração não óbvia é CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() e LoadAsync() ainda exigem IRandomAccessStream. Ponte a partir de fluxos System.IO:

// 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 foi alterado, mas a superfície da API é idêntica:

Todas as Microsoft.Graphics.Canvas.* APIs (CanvasDevice, CanvasBitmap, , CanvasRenderTarget) DrawInkfuncionam da mesma maneira. Somente a referência do pacote NuGet precisa ser atualizada.

Impressão

A impressão UWP usa PrintManager.GetForCurrentView(). O WinUI 3 requer interoperação com manipulador de janela:

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

• guia de migração SDK do Aplicativo Windows – passo a passo completo da migração manual
• Mapeando APIs e bibliotecas UWP para o SDK do Aplicativo Windows — tabela de mapeamento de API abrangente
• O que tem suporte ao migrar da UWP para o WinUI — status de suporte ao recurso
• Migrar do WPF