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

O WinUI inclui InkCanvas, InkToolbar, e InkPresenter como APIs experimentais em versões experimentais do SDK de Aplicações Windows. Os lançamentos estáveis não os incluem. Para configuração, personalização da barra de ferramentas e limitações conhecidas, veja Controlos de tinta para aplicações WinUI.

Em versões experimentais, os controlos e as classes que processam a entrada de tinta estão em Microsoft.UI.Xaml.Controls. Traços e atributos de desenho mantêm-se em Windows.UI.Input.Inking:

Cada tipo de UWP nas duas primeiras linhas tem um equivalente com o mesmo nome, mas o SDK de Aplicações Windows 2.5.4-experimental não inclui todos os seus membros:

• InkStrokeContainer não tem construtor público e InkPresenter.StrokeContainer é apenas de leitura. Para alternar entre conjuntos de traços, guarde cada conjunto com SaveAsync e restaure-o com LoadAsync, que substitui os traços atuais.
• SaveAsync e LoadAsync retornam IAsyncAction, por isso não reportam progresso, e SaveAsync não devolve o número de bytes que escreveu.
• InkStrokeContainer.GetRecognitionResults, InkStrokeContainer.UpdateRecognitionResults, e InkInputConfiguration.IsPenHapticFeedbackEnabled não estão disponíveis.
• InkToolbarRulerButton.Ruler e o evento InkToolbar.IsRulerButtonCheckedChanged não estão disponíveis. O UWP foi preterido InkToolbarRulerButton em favor de InkToolbarStencilButton, por isso use o botão de estêncil e o evento InkToolbar.IsStencilButtonCheckedChanged em vez disso.

O SDK de Aplicações Windows 2.4.1-experimental adicionou APIs de borracha, como InkToolbarEraserKind e InkToolbarEraserButton.SelectedEraser, que foram removidas na 2.5.4-experimental. Nunca fizeram parte do UWP, por isso não os adicione ao código migrado. Para a lista completa, veja Alterações em relação à 2.4.1-experimental.

Como tipos como InkPresenter e InkStrokeContainer existem em ambos os namespaces, importar ambos Microsoft.UI.Xaml.Controls e Windows.UI.Input.Inking causa o erro CS0104 ao usar esses nomes. Importa Microsoft.UI.Xaml.Controls, e adiciona diretivas de alias para os Windows.UI.Input.Inking tipos que usas:

using Microsoft.UI.Xaml.Controls;
using InkDrawingAttributes = Windows.UI.Input.Inking.InkDrawingAttributes;
using InkStroke = Windows.UI.Input.Inking.InkStroke;

InkStrokeContainer.SaveAsync escreve para um IOutputStream, e LoadAsync lê a partir de um IInputStream. Para usar System.IO fluxos de ficheiros, converta-os com AsOutputStream e AsInputStream. O ficheiro precisa de using System; para aguardar estes métodos do Windows Runtime, juntamente com using System.IO; e using Windows.Storage.Streams;:

// Save ink strokes to a file.
using (FileStream fileStream = File.Create(filePath))
using (IOutputStream output = fileStream.AsOutputStream())
{
    await inkStrokeContainer.SaveAsync(output);
    await output.FlushAsync();
}

// Load ink strokes from a file.
using (FileStream fileStream = File.OpenRead(filePath))
using (IInputStream input = fileStream.AsInputStream())
{
    await inkStrokeContainer.LoadAsync(input);
}

Podes continuar a ligar a barra de ferramentas ao ecrã com InkToolbar.TargetInkCanvas, ou definir TargetInkPresenter para a ligar diretamente a um InkPresenter. Para adicionar as suas próprias ferramentas à barra de ferramentas, use InkToolbarCustomToolButton e InkToolbarCustomToggleButton, como mostrado em Personalizar a barra de ferramentas de tinta. Antes de migrar, reveja as limitações conhecidas, como problemas reportados com os estênceis da régua e do transportador.

Se a sua aplicação tiver de usar uma versão estável, não existe controlo de escrita à tinta incorporado para migrar para ele. Renderiza os traços com Win2D e processa tu mesmo a entrada do ponteiro, ou usa uma biblioteca de escrita à mão de terceiros. Para substituir InkToolbar, use a CommandBar com AppBarToggleButton itens.

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)
- InkCanvas, InkToolbar, InkPresenter, InkStrokeContainer, and the other ink input types → Microsoft.UI.Xaml.Controls (experimental Windows App SDK releases only; if the project uses a stable release, flag them instead)
- Ink members that Windows App SDK 2.5.4-experimental doesn't include (new InkStrokeContainer(), assignments to InkPresenter.StrokeContainer, GetRecognitionResults, UpdateRecognitionResults, IsPenHapticFeedbackEnabled, InkToolbarRulerButton.Ruler, IsRulerButtonCheckedChanged, and progress or byte counts from SaveAsync and LoadAsync) → flag them
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- InkStroke, InkDrawingAttributes, InkPoint, InkStrokeBuilder → no change (Windows.UI.Input.Inking; use using aliases to avoid CS0104)

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Do not add InkToolbarEraserKind, SelectedEraser, or other eraser APIs from Windows App SDK 2.4.1-experimental. Version 2.5.4-experimental removed them.
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