Migrar padrões de aplicativo WPF para o WinUI 3

O WinUI 3 compartilha muitos conceitos XAML com WPF e é otimizado para experiências Windows modernas. A maioria dos padrões WPF tem equivalentes diretos no WinUI 3. Em algumas áreas, o WinUI 3 apresenta uma abordagem aprimorada que substitui um padrão mais antigo e, em alguns casos, os recursos ainda estão em desenvolvimento ativo.

Este tópico mapeia padrões comuns de WPF para seus equivalentes WinUI 3 para que você possa planejar sua migração.

Dica

Para obter orientações gerais sobre WPF + SDK do Aplicativo Windows, consulte Use o SDK do Aplicativo Windows em um projeto existente.

Controles

A maioria dos controles WPF tem equivalentes diretos no WinUI 3. A tabela a seguir aborda os controles em que o mapeamento não é um para um.

controle WPF WinUI 3 equivalente Observações
DataGrid Nenhum equivalente de origem própria O WinUI 3 não inclui um DataGrid interno. O WinUI.TableView mantido pela comunidade é uma opção. Avalie projetos de comunidade com base em seus requisitos de suporte e manutenção.
Ribbon CommandBar / Laboratórios de Ferramentas da Comunidade Considere CommandBar e CommandBarFlyout para cenários de estilo de barra de ferramentas. Um controle Ribbon também está disponível no Community Toolkit Labs (experimental).
StatusBar InfoBar + layout personalizado Use o InfoBar para mensagens de status ou adicione uma área de rodapé dedicada ao seu layout.
FlowDocumentReader / FlowDocumentScrollViewer RichTextBlock Use RichTextBlock para exibição de texto rico apenas leitura. O WinUI 3 adota uma abordagem diferente para o conteúdo do documento que é mais adequado para cenários de aplicativos modernos.
PasswordBox com SecureString PasswordBox O PasswordBox do WinUI 3 fornece máscara de senha. SecureString foi preterido no .NET 5+; a abordagem recomendada é minimizar por quanto tempo as credenciais são mantidas na memória usando padrões de ReadOnlySpan<char>.
WebBrowser WebView2 WebView2 usa o mecanismo de Microsoft Edge (Chromium) moderno e é a abordagem recomendada para inserir conteúdo da Web em todos os tipos de aplicativos da área de trabalho.

Recursos XAML

O WinUI 3 XAML usa os mesmos conceitos principais que WPF – dicionários de recursos, estilos, associação de dados e extensões de marcação funcionam da mesma forma. Alguns padrões específicos do WPF evoluíram para alternativas aprimoradas e mais componíveis.

recurso WPF Abordagem do WinUI 3 Observações
DataTrigger / MultiTrigger Comportamentos (Kit de Ferramentas da Comunidade) O WinUI 3 usa comportamentos anexados em vez de gatilhos embutidos. O pacote de comportamentos XAML oferece suporte a DataTriggerBehavior, EventTriggerBehavior e muito mais. Os comportamentos são mais componíveis e testáveis unitariamente do que gatilhos do WPF.
DynamicResource ThemeResource ThemeResource fornece pesquisa de recursos de runtime e responde automaticamente às alterações de tema (claro, escuro, alto contraste). Use StaticResource para valores que nunca são alterados no runtime.
MultiBinding / PriorityBinding Conversores ou x:Bind Use um conversor de vários valores com associações individuais ou use x:Bind com uma propriedade computada em seu modelo de exibição. x:Bind é compilado e seguro de tipo, o que o torna mais eficiente do que Binding.
Style com BasedOn ✅ Com suporte Herança de estilo com BasedOn funciona no WinUI 3.
Estilos implícitos ✅ Com suporte Os estilos implícitos do dicionário de recursos (estilos sem x:Key) funcionam conforme o esperado.
AdornerLayer Abordagem de sobreposição personalizada O WinUI 3 não tem nenhuma camada de adorno equivalente. Use uma Canvas ou Grid sobreposição em seu layout para obter efeitos de decoração visuais semelhantes. Essa abordagem é mais explícita e fácil de raciocinar.

Threading e expedição

padrão de WPF WinUI 3 equivalente Observações
Dispatcher.Invoke / BeginInvoke DispatcherQueue.TryEnqueue O WinUI 3 usa DispatcherQueue. O padrão assíncrono await DispatcherQueue.EnqueueAsync(...) usando a extensão Community Toolkit.
Application.Current.Dispatcher DispatcherQueue.GetForCurrentThread() Capture o DispatcherQueue no momento da construção na thread da interface do usuário e armazene-o para uso posterior em threads de segundo plano.
BackgroundWorker Task / async-await Padrões assíncronos de .NET modernos são a abordagem certa no WinUI 3. Task, CancellationTokene IProgress<T> abrange todos os BackgroundWorker cenários e integra-se naturalmente com x:Bind.

Modelo de aplicativo e ciclo de vida

conceito de WPF WinUI 3 equivalente Observações
Application.Startup / Exit Eventos App.OnLaunched / Window.Closed O WinUI 3 usa OnLaunchedApp.xaml.cs como ponto de entrada. O teardown por janela é tratado em Window.Closed.
Application.Current.MainWindow Sua Window instância Mantenha uma referência à instância da sua janela em App.xaml.cs e exponha-a como uma propriedade.
Window Subclassificação Personalização do AppWindow As janelas do WinUI 3 são personalizadas através de AppWindow (barra de título, apresentador de janela, modos sobreposto/tela cheia/sobreposição compacta) em vez de subclasse. Consulte Gerenciar janelas do aplicativo.
SystemParameters DisplayArea / UISettings As propriedades de exibição do sistema estão disponíveis por meio de DisplayArea e UISettings.

Recursos e localização

padrão de WPF WinUI 3 equivalente Observações
.resx arquivos de recurso .resw + ResourceLoader O WinUI 3 usa .resw arquivos e a API do ResourceLoader . O Assistente de Atualização do .NET pode automatizar grande parte dessa conversão.
x:Static Extensão de marcação x:Bind para uma propriedade estática Use x:Bind com uma propriedade estática ou um acessador singleton. x:Bind é compilado e produz mensagens de erro mais claras do que x:Static.
Dicionários de recursos mesclados ✅ Com suporte ResourceDictionary.MergedDictionaries funciona no WinUI 3.
Dicionários de recursos específicos do tema ✅ Com suporte ResourceDictionary.ThemeDictionaries é o mecanismo WinUI 3 para recursos por tema e integra-se com a alternância automática de modo escuro/claro.

Impressão

recurso WPF Status do WinUI 3 Observações
PrintDialog / PrintDocument PrintManager O suporte completo à impressão está disponível por meio de PrintManager. Consulte Impressão a partir do seu aplicativo.

Ferramentas para desenvolvedores

ferramentas de WPF Status do WinUI 3 Observações
Designer XAML (guia Design) Ainda não suportado O Designer XAML do Visual Studio atualmente não dá suporte a projetos WinUI 3. XAML Recarga Dinâmica é suportado e é a maneira recomendada de iterar sobre estilos e layout sem interromper o depurador.
Blend para Visual Studio ⚠️ Suporte limitado O Blend é fornecido com o Visual Studio e pode abrir projetos do WinUI 3. A Estrutura de Tópicos do Documento XAML é funcional, mas o modo design não está disponível para WinUI 3.

Consulte também

  • Last updated on