Partilhar via

Notas sobre a versão do canal de pré-visualização para o SDK de Aplicativo do Windows 1.0

  • Artigo

Importante

O canal de preview não é compatível com o uso em ambientes de produção e os aplicativos que usam as versões de preview não podem ser publicados na Microsoft Store.

O canal de pré-visualização do SDK de Aplicativo do Windows com recursos de canal de pré-visualização nos últimos estágios de desenvolvimento. As versões de pré-visualização não incluem recursos experimentais e APIs, mas ainda podem estar sujeitas a alterações significativas antes da próxima versão estável.

Links importantes:

Versão de canal de pré-visualização mais recente:

Versão de canal estável mais recente:

Versão 1.0 Preview 3 (1.0.0-preview3)

O Preview 3 é a versão mais recente do canal de preview da versão 1.0 do SDK do Aplicativo Windows. O Preview 3 suporta todos os recursos do canal de visualização.

Fazer download de 1.0 Preview 3 extensões do Visual Studio (VSIX)

Observação

Caso tenha o VSIX (extensões de SDK do Aplicativo Windows do Visual Studio) já instalada, desinstale-as antes de instalar uma nova versão. Para obter instruções, confira Gerenciar extensões para o Visual Studio.

Na tabela abaixo, você pode fazer download das extensões do Visual Studio (VSIX) para a versão 1.0 Preview 3. Para obter todas as versões, confira Downloads mais recentes do SDK de Aplicativo do Windows. Se você ainda não tiver feito isso, comece configurando seu ambiente de desenvolvimento, usando as etapas em Ferramentas de instalação para o SDK do Aplicativo Windows.

As extensões abaixo são personalizadas para sua linguagem de programação e versão do Visual Studio.

1.0 Preview 3 downloads Descrição
Extensão do Visual Studio 2019 para C# Crie aplicativos C# com a extensão do SDK do Aplicativo Windows Visual Studio 2019.
Extensão do Visual Studio 2019 para C++ Crie aplicativos C++ com a extensão do SDK do Aplicativo Windows Visual Studio 2019.
Extensão do Visual Studio 2022 para C# Crie aplicativos C# com a extensão do SDK do Aplicativo Windows Visual Studio 2022.
Extensão do Visual Studio 2022 para C++ Crie aplicativos C++ com a extensão do SDK do Aplicativo Windows Visual Studio 2022.
O .exe instalador e os pacotes MSIX Implante o SDK do Aplicativo Windows com seu aplicativo usando o instalador .exe e os pacotes MSIX.

As seções a seguir descrevem recursos novos e atualizados, limitações e issues conhecidos para 1.0 Preview 3.

WinUI 3 (1.0.0-preview3)

Agora oferecemos suporte à implantação de aplicativos WinUI 3 sem empacotamento MSIX. Consulte Criar seu primeiro projeto WinUI 3 (SDK de Aplicativo do Windows) para configurar seu aplicativo WinUI 3 para oferecer suporte à implantação não empacotada.

Limitações importantes:

  • Aplicativos WinUI 3 não empacotados são suportados somente nas versões 1909 e posteriores do Windows.
  • Aplicativos WinUI 3 não empacotados são suportados em x86 e x64, e o suporte a arm64 será adicionado na próxima versão estável.
  • Ferramentas de empacotamento MSIX de projeto único para o Visual Studio 2019 ou o Visual Studio 2022 são necessárias para aplicativos não empacotados.
  • Em um aplicativo não empacotado, você pode receber uma solicitação para instalar o .NET 3.5; se você fizer isso, então você pode ignorá-lo.
  • Algumas APIs não são suportadas atualmente em aplicativos não empacotados. Nosso objetivo é corrigir isso na próxima versão estável. Alguns exemplos:
  • Os controles ListView, CalendarView e GridView estão usando os estilos incorretos, e pretendemos corrigir isso na próxima versão estável.

Para obter mais informações ou para começar a desenvolver com o WinUI 3, confira:

Outras limitações e problemas conhecidos:

  • Não há suporte para aplicativos não empacotados no Windows 10 versão 1809. Nosso objetivo é corrigir isso na próxima versão no canal estável.

  • O aplicativo MSIX de projeto único em C# não será compilado se as Ferramentas UWP do C++ não estiverem instaladas. Se você tiver um projeto MSIX de projeto único em C#, precisará instalar o componente opcional Ferramentas C++ (v14x) da Plataforma Universal do Windows.

  • Esta versão apresenta os modelos de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) para C# e C++. Esses modelos permitem que você crie seu aplicativo em um pacote MSIX sem o uso de um projeto de empacotamento separado (confira Empacotar seu aplicativo usando MSIX de projeto único). Esses modelos têm alguns issues conhecidos nesta versão:

    • Item de menu Publicar ausente até reiniciar o Visual Studio. Ao criar um aplicativo no Visual Studio 2019 e no Visual Studio 2022 usando o modelo de projeto Aplicativo em branco empacotado (WinUI 3 na Área de Trabalho), o comando para publicar o projeto não aparece no menu até você fechar e reabrir o Visual Estúdio.

    • Erro ao adicionar referências de projeto de biblioteca estática/dinâmica C++ a aplicativos C++ usando o Empacotamento MSIX de projeto único. Visual Studio exibe um erro que o projeto não pode ser adicionado como referência porque os tipos de projeto não são compatíveis.

    • Erro ao fazer referência a um controle de usuário personalizado em um projeto de biblioteca de classes. O aplicativo falhará com o erro de que o sistema não consegue encontrar o caminho especificado.

    • Modelo C# ou C++ para Visual Studio 2019. Ao tentar criar o projeto, você encontrará o erro "O projeto não sabe como executar o nome do projeto de perfil". Para resolver esse Issue, instale a extensão de ferramentas de empacotamento MSIX de projeto único.

    • Modelo C# para Visual Studio 2019 e Visual Studio 2022. No Visual Studio, quando você inicia a depuração ou inicia sem depuração, se seu aplicativo não for implantado e executado (e não houver feedback do Visual Studio), clique no nó do projeto no Gerenciador de Soluções para selecioná-lo e tente novamente.

    • Modelo C# para Visual Studio 2019 e Visual Studio 2022. Você encontrará o seguinte erro ao tentar executar ou depurar seu projeto no computador de desenvolvimento: "O projeto precisa ser implantado antes de podermos depurar. Habilite Implantar no Configuration Manager." Para resolver esse issue, habilite a implantação para seu projeto no Configuration Manager. Para obter instruções mais detalhadas, consulte Criar seu primeiro projeto WinUI 3 (SDK de Aplicativo do Windows).

    • Modelo C++ para Visual Studio 2022 versão 17.0 versões até Preview 4. Você encontrará o seguinte erro na primeira vez que tentar executar seu projeto: "Houve erros de implantação". Para resolver esse issue, execute ou implante seu projeto uma segunda vez. Esse issue será corrigido no Visual Studio 2022 versão 17.0 Preview 7.

  • Sem suporte para qualquer configuração de build de CPU: ao adicionar o SDK do Aplicativo Windows a um aplicativo ou componente do .NET existente que dê suporte a Qualquer CPU, especifique a arquitetura desejada: x86, x64 ou arm64.

  • Os projetos C# que usam a versão 1.0 do Preview 3 devem usar o seguinte SDK do .NET: SDK do .NET 6 ou posterior (confira Fazer download do .NET e o .NET 5 chegará ao fim do suporte em 10 de maio de 2022).

  • Uma alternativa ao DispatcherQueue.TryEnqueue (para retomar a execução no thread da fila do dispatcher) é usar a função auxiliar resume_foreground na WIL (Biblioteca de Implementação do Windows):

    1. Adicione uma referência ao seu projeto ao pacote NuGet Microsoft.Windows.ImplementationLibrary.
    2. Adicione #include <wil/cppwinrt_helpers.h> ao seu pch.h.
    3. Adicione #include <winrt/Microsoft.UI.Dispatching.h> ao seu pch.h.
    4. Agora co_await wil::resume_foreground(your_dispatcherqueue);.

Issue importante que afeta o 1.0 Preview 1 e o Preview 2

A versão 1.0 Preview 1 e Preview 2 do SDK do Aplicativo Windows inclui um mecanismo para limpar quaisquer alterações de variáveis de ambiente feitas por um aplicativo empacotado quando esse aplicativo é desinstalado. Esse recurso está em um estado experimental e a primeira versão inclui um bug conhecido que pode corromper a variável de ambiente PATH do sistema.

A Preview 1 e a Preview 2 corrompem qualquer variável de ambiente PATH que contenha o caractere de expansão %. Isso acontece sempre que qualquer aplicativo empacotado é desinstalado, independentemente de esse aplicativo usar o SDK do Aplicativo Windows.

Confira também o issue de dano de variável de ambiente PATH.

Detalhes

A entrada PATH do sistema é armazenada no valor Path na seguinte chave no Registro do Windows:

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

Se você iniciar o Editor do Registro (regedit.exe), poderá copiar e colar o caminho acima na barra de trilha (imediatamente abaixo da barra de menus) e pressionar Enter para localizar a chave.

O valor Path dessa chave deve ser do tipo REG_EXPAND_SZ, mas o bug o altera para REG_SZ. E isso torna a variável de ambiente PATH do sistema inutilizável se ela contiver o caractere de expansão da variável %.

Versões afetadas

Mitigação

Para colocar suo computador de volta em um bom estado, execute as seguintes etapas:

  1. Verifique se o PATH no Registro está corrompido e, em caso afirmativo, redefina-o executando o script abaixo.

    Você pode realizar a etapa 1 com o seguinte script do Windows PowerShell (o PowerShell Core não funcionará). Execute-o elevado.

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# If the PATH in the Registry has been set to REG_SZ, then delete
# it, and recreate it as REG_EXPAND_SZ.

$EnvPath = 'Registry::HKLM\System\CurrentControlSet\Control\Session Manager\Environment'
$Environment=Get-Item $EnvPath
$PathKind = $Environment.GetValueKind('Path')

if ($PathKind -ne 'ExpandString') {
  $Path = $Environment.GetValue('Path')
  Remove-ItemProperty $EnvPath -Name Path
  New-ItemProperty $EnvPath -Name Path -PropertyType ExpandString -Value $Path
}

  2. Desinstale todos os aplicativos que usam o SDK do Aplicativo Windows 1.0 Preview1 ou Preview2 (confira o script abaixo).

  3. Desinstale os pacotes do SDK do Aplicativo Windows 1.0 Preview1/Preview2, incluindo o pacote que contém o bug (confira o script abaixo).

    Você pode realizar as etapas 2 e 3 com o seguinte script do Windows PowerShell (o PowerShell Core não funcionará). Execute-o elevado.

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# Remove the Windows App SDK 1.0 Preview1/2, and all apps that use it.

$winappsdk = "Microsoft.WindowsAppRuntime.1.0-preview*"
Get-AppxPackage | Where-Object { $_.Dependencies -like $winappsdk } | Remove-AppxPackage
Get-AppxPackage $winappsdk | Remove-AppxPackage

Correção no SDK do Aplicativo Windows 1.0 Preview 3

O recurso que faz com que a variável de ambiente PATH seja corrompida será removido na próxima versão do SDK do Aplicativo Windows 1.0 Preview 3. Ele pode ser reintroduzido em uma data posterior, quando todos os bugs tiverem sido corrigidos e completamente testados.

Recomendamos o uso da versão 1.0 Preview 3.

Versão 1.0 Preview 2 (1.0.0-preview2)

Importante

As versões 1.0 Preview 1 e Preview 2 contêm um bug crítico. Se você já instalou uma dessas pré-visualizações, veja como resolver o problema. Em vez disso, recomendamos usar a versão 1.0 Preview 3.

Esta é a versão mais recente do canal de preview para a versão 1.0. Ela oferece suporte a todos os recursos do canal de preview.

As seções a seguir descrevem os recursos novos e atualizados, as limitações e os problemas conhecidos para essa versão.

WinUI 3 (1.0.0-preview2)

Novas atualizações:

  • Os controles foram atualizados para refletir os estilos mais recentes do Windows do WinUI 2.6.
  • Há suporte para o MSIX de projeto único.
  • O pacote WinUI 3 agora pode ser direcionado para o build 17763 e posterior. Confira o issue n° 921 para obter mais informações.
  • Há suporte para a barra de ferramentas no aplicativo. No entanto, a barra de ferramentas no aplicativo e o suporte existente à Recarga Dinâmica/Live Visual Tree exigem a próxima versão do Visual Studio 17.0 Preview 5, disponível no final de outubro.

Bug corrigido: o texto do WebView2Runtime agora está localizado.

Para obter mais informações ou para começar a desenvolver com o WinUI 3, confira:

Windowing (1.0.0-preview2)

Esta versão introduz atualizações para a classe AppWindow. Não há novos recursos importantes adicionados nesta versão, mas há alterações em nomes de métodos, propriedades e alguns valores de retorno foram removidos. Confira a documentação e os exemplos para obter atualizações detalhadas. Se você trabalhou com o AppWindow nas versões 1.0 Experimental ou 1.0 Preview 1, espere algumas alterações no seu código.

Novas atualizações:

  • A classe AppWindowConfiguration foi removida. As propriedades dessa classe agora estão disponíveis no próprio AppWindow ou nas classes Apresentador.
  • A maioria dos valores de retorno bool para os métodos de API do WinRT neste espaço foi removida e agora é void, pois esses métodos sempre teriam êxito.
  • As chamadas ImportDll do C# não são mais necessárias para GetWindowIdFromWindow e GetWindowFromWindowId. Em vez disso, use os métodos wrapper .NET disponíveis na classe Microsoft.UI.Win32Interop.

Limitações importantes:

  • O SDK do Aplicativo Windows atualmente não fornece métodos para anexar o conteúdo da estrutura da IU a um AppWindow; você está limitado a usar os métodos de acesso de interoperabilidade HWND.
  • A personalização da barra de título da janela funciona apenas no Windows 11. Use o método IsCustomizationSupported para verificar o suporte ao recurso de personalização da barra de título. Pretendemos reduzir essa funcionalidade.

Para obter mais informações, confira Gerenciar janelas de aplicativos (SDK de Aplicativo do Windows).

Entrada (1.0.0-preview2)

Novas atualizações:

  • Suporte aprimorado para entrada de touchpad de precisão.

Limitações importantes:

  • Todas as funções de fábrica estáticas do PointerPoint foram removidas: GetCurrentPoint, GetCurrentPointTransformed, GetIntermediatePoints e GetIntermediatePointsTransformed.
  • O SDK do Aplicativo Windows não oferece suporte à recuperação de objetos PointerPoint com IDs de ponteiro. Em vez disso, use a função membro PointerPointGetTransformedPoint para recuperar uma versão transformada de um objeto PointerPoint existente. Para pontos intermediários, use as funções membro PointerEventArgsGetIntermediatePoints e GetTransformedIntermediatePoints. Confira a documentação para obter mais detalhes.

MRT Core (1.0.0-preview2)

Novas atualizações:

  • Os desenvolvedores de aplicativos agora podem recusar a indexação de um arquivo de imagem ou de um arquivo RESW no arquivo PRI em projetos .NET. Confira o issue n.º 980 para obter mais informações.

Limitações importantes:

  • Em projetos do .NET, os arquivos de recurso copiados colados na pasta do projeto não serão indexados em F5 se o aplicativo já tiver sido criado. Como solução alternativa, recompile o aplicativo. Confira o issue n.º 1503 para obter mais informações].
  • Em projetos .NET, os arquivos de recursos existentes adicionados de uma pasta externa não são indexados sem a configuração manual da Ação de build. Para contornar esse issue, defina a ação de build no Visual Studio: conteúdo para arquivos de imagem e PRIResource para arquivos RESW. Confira o issue n.º 1504 para obter mais informações.

Implantação para aplicativos não empacotados

Novos recursos:

  • O Windows App SDK 1.0 Preview 2 apresenta um wrapper .NET para a API de bootstrapper (confira Usar o runtime do SDK do Aplicativo Windows para aplicativos empacotados com localização externa ou não empacotados). A API do bootstrapper é um conjunto de funções C/C++ nativas que os aplicativos não empacotados devem usar para assumir dinamicamente uma dependência do pacote de estrutura do SDK do Aplicativo Windows em tempo de execução. O wrapper .NET fornece uma maneira mais fácil de chamar a API de bootstrapper de aplicativos .NET, incluindo aplicativos Windows Forms e WPF. O wrapper .NET para a API bootstrapper está disponível no assembly Microsoft.WindowsAppRuntime.Bootstrap.Net.dll que é local para seu projeto de aplicativo. Para obter mais informações sobre o wrapper do .NET, confira Biblioteca de wrapper do .NET.
  • Os aplicativos empacotados agora podem usar a API de implantação para obter os pacotes MSIX principal e singleton instalados no computador. Os pacotes main e singleton fazem parte do pacote de estrutura que é instalado com o aplicativo, mas devido a uma limitação com o modelo de aplicativo do Windows, os aplicativos empacotados precisarão executar essa etapa adicional para obter esses pacotes instalados. Para obter mais informações sobre como funciona a API de implantação, confira a Guia de implantação do SDK do Aplicativo Windows para aplicativos empacotados dependentes de estrutura.

Limitações importantes:

  • O wrapper do .NET para a API de Bootstrapper destina-se apenas a ser usado por aplicativos do .NET não empacotados para simplificar o acesso ao SDK do Aplicativo Windows.
  • Somente aplicativos em pacote MSIX que são de confiança total ou têm a funcionalidade restrita packageManagement têm a permissão para usar a API de implantação para instalar as dependências do pacote Main e Singleton. O suporte para aplicativos empacotados de confiança parcial será disponibilizado em versões posteriores.
  • Ao testar F5 um aplicativo x86 que usa o método DeploymentManager.Initialize em um sistema x64, verifique se a estrutura x64 é instalada pela primeira vez executando o WindowsAppRuntimeInstall.exe. Caso contrário, você encontrará um erro de NOT_FOUND devido ao Visual Studio não implantar a estrutura x64, que normalmente ocorre por meio da implantação da Store ou do sideload.

Ciclo de vida do aplicativo

A maioria dos recursos do Ciclo de Vida do Aplicativo já existe na plataforma UWP e foi trazida para o SDK do Aplicativo Windows para uso por tipos de aplicativo da área de trabalho, especialmente aplicativos de Console não empacotados, aplicativos Win32, aplicativos Windows Forms e aplicativos WPF. A implementação de SDK do Aplicativo Windows desses recursos não pode ser usada em aplicativos UWP, pois há recursos equivalentes na própria plataforma UWP.

Aplicativos que não sejam da UWP também podem ser empacotados em pacotes MSIX. Embora esses aplicativos possam usar alguns dos recursos do ciclo de vida do SDK do Aplicativo Windows, eles devem usar a abordagem de manifesto em que isso está disponível. Por exemplo, eles não podem usar as APIs de RegisterForXXXActivation do SDK do Aplicativo Windows e devem registrar-se para ativação avançada por meio do manifesto.

Todas as restrições para aplicativos empacotados também se aplicam aos aplicativos WinUI 3 empacotados; e há considerações adicionais conforme descrito abaixo.

Considerações importantes:

  • Ativação avançada: GetActivatedEventArgs

  • Registrar/cancelar o registro para ativação avançada

  • Instanciação única/múltipla

    • Aplicativos não empacotados: totalmente utilizáveis.
    • Aplicativos empacotados: totalmente utilizáveis.
    • Aplicativos da WinUI 3: se um aplicativo quiser detectar outras instâncias e redirecionar uma ativação, ele deverá fazer isso o mais cedo possível e antes de inicializar qualquer janela etc. Para habilitar isso, o aplicativo deve definir DISABLE_XAML_GENERATED_MAIN e gravar um Main (C#) ou WinMain (C++) personalizado, em que ele pode fazer a detecção e o redirecionamento.
    • RedirectActivationToAsync é uma chamada assíncrona e você não deve esperar em uma chamada assíncrona se o aplicativo estiver em execução em um STA. Para aplicativos Windows Forms e C# WinUI 3, você pode declarar Main como assíncrono, se necessário. Para aplicativos C++ WinUI 3 e C# WPF, você não pode declarar Main como assíncrono; portanto, em vez disso, você precisa mover a chamada de redirecionamento para outro threading para garantir que não bloqueará o STA.
    • Para obter mais informações, confira Instanciação de aplicativo com a API de ciclo de vida do aplicativo.

  • Notificações de energia/estado

Problema conhecido:

As associações de Tipo de Arquivo codificam incorretamente %1 como %251 ao definir o modelo de linha de comando do manipulador do Verbo, que falha em aplicativos do Win32 não empacotados. Edite manualmente o valor do Registro para ser %1 como uma solução alternativa parcial. Se o caminho do arquivo de destino tiver um espaço, ele ainda falhará e não haverá solução alternativa para esse cenário.

Outras limitações e problemas conhecidos:

  • As versões 1.0 Preview 1 e Preview 2 contêm um bug crítico. Se você já instalou uma dessas pré-visualizações, veja como resolver o problema. Em vez disso, recomendamos usar a versão 1.0 Preview 3.

  • Esta versão apresenta os modelos do Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) para projetos C# e C++. Esses modelos permitem que você crie seu aplicativo em um pacote MSIX sem o uso de um projeto de empacotamento separado. Esses modelos têm alguns issues conhecidos nesta versão:

    • Modelo C# para Visual Studio 2019. Você encontrará o erro ao tentar criar o projeto: "O projeto não sabe como executar o nome do projeto de perfil". Para resolver esse Issue, instale a extensão de ferramentas de empacotamento MSIX de projeto único.

    • Modelo C# para Visual Studio 2019 e Visual Studio 2022. Você encontrará o seguinte erro ao tentar executar ou depurar seu projeto no computador de desenvolvimento: "O projeto precisa ser implantado antes de podermos depurar. Habilite Implantar no Configuration Manager." Para resolver esse issue, habilite a implantação para seu projeto no Configuration Manager. Para obter instruções mais detalhadas, consulte Criar seu primeiro projeto WinUI 3 (SDK de Aplicativo do Windows).

    • Modelo C++ para Visual Studio 2019 e Visual Studio 2022. Nesta versão, esses projetos são restritos a chamar o subconjunto de APIs Win32 que podem ser chamadas por aplicativos UWP. O modelo de Aplicativo em branco, empacotado com WAP (WinUI 3 na área de trabalho) não é afetado por esse issue.

    • Modelo C++ para Visual Studio 2022 versão 17.0 versões até Preview 4. Você encontrará o seguinte erro na primeira vez que tentar executar seu projeto: "Houve erros de implantação". Para resolver esse issue, execute ou implante seu projeto uma segunda vez. Esse problema será corrigido no Visual Studio 2022 versão 17.0 Preview 5.

  • API de notificações por push (namespace Microsoft.Windows.PushNotifications) incluída incorretamente na versão 1.0 Preview 2. Este ainda é um recurso experimental, e para você usá-lo você deve instalar a versão 1.0 Experimental em vez disso. Esse recurso será removido da próxima versão 1.0.

  • A API do ciclo de vida do aplicativo (namespace Microsoft.Windows.AppLifecycle) inclui incorretamente o atributo Experimental na versão 1.0 Preview 2. O atributo Experimental será removido dessa API na próxima versão.

  • Sem suporte para qualquer configuração de build de CPU: ao adicionar o SDK do Aplicativo Windows a um aplicativo ou componente do .NET existente que dê suporte a Qualquer CPU, especifique a arquitetura desejada: x86, x64 ou arm64.

  • Os projetos C# que usam a versão 1.0 do Preview 2 devem usar o seguinte SDK do .NET: SDK do .NET 6 ou posterior (confira Fazer download do .NET e o .NET 5 chegará ao fim do suporte em 10 de maio de 2022).

  • Uma alternativa ao DispatcherQueue.TryEnqueue (para retomar a execução no thread da fila do dispatcher) é usar a função auxiliar resume_foreground na WIL (Biblioteca de Implementação do Windows):

    1. Adicione uma referência ao seu projeto ao pacote NuGet Microsoft.Windows.ImplementationLibrary.
    2. Adicione #include <wil/cppwinrt_helpers.h> ao seu pch.h.
    3. Adicione #include <winrt/Microsoft.UI.Dispatching.h> ao seu pch.h.
    4. Agora co_await wil::resume_foreground(your_dispatcherqueue);.

Versão 1.0 Preview 1 (1.0.0-preview1)

Importante

As versões 1.0 Preview 1 e Preview 2 contêm um bug crítico. Se você já instalou uma dessas pré-visualizações, veja como resolver o problema. Em vez disso, recomendamos usar a versão 1.0 Preview 3.

Esta é a primeira versão do canal de preview para a versão 1.0. Ela oferece suporte a todos os recursos do canal de preview.

As seções a seguir descrevem os recursos novos e atualizados, as limitações e os problemas conhecidos para essa versão.

WinUI 3 (1.0.0-preview1)

Esta versão do WinUI 3 é focada na construção para 1.0 com Correções de bugs.

  • Novos recursos: sem novos recursos na Preview 1.
  • Issues corrigidos: para obter a lista completa de problemas abordados nesta versão, confira o nosso repositório do GitHub.

Para obter mais informações ou para começar a desenvolver com o WinUI 3, confira:

Windowing (1.0.0-preview1)

Esta versão traz a API de Janelas que introduzimos no Experimental 1 para um estado de preview. Não há grandes áreas de novos recursos nesta versão, pois ela é focada em Correções de bugs, estabilidade e ajustes na assinatura da API. As mudanças e adições em destaque são apresentadas abaixo.

Novos recursos:

  • O DisplayAreaWatcher foi adicionado às APIs de janela. Isso permite que um desenvolvedor observe as alterações na topologia de exibição e enumere as DisplayAreas atualmente definidas no sistema.
  • Agora, o AppWindow suporta a configuração do ícone da janela através do método SetIcon e o AppWindowTitleBar agora suporta selecionar se deseja mostrar/ocultar o ícone da janela junto com o menu de sistema por meio da propriedade IconShowOptions.

Limitações importantes:

  • Esta versão do AppWindow está atualmente disponível apenas para os aplicativos Win32 (empacotados e não empacotados).
  • O SDK do Aplicativo Windows atualmente não fornece métodos para anexar o conteúdo da estrutura da IU a um AppWindow; você está limitado a usar os métodos de acesso de interoperabilidade HWND.
  • A personalização da barra de título da janela funciona apenas no Windows 11. Use o método IsCustomizationSupported para verificar o suporte ao recurso de personalização da barra de título. Pretendemos reduzir essa funcionalidade.

Para obter mais informações, confira Gerenciar janelas de aplicativos (SDK de Aplicativo do Windows).

Entrada (1.0.0-preview1)

Esta versão traz alguns novos recursos para a API de entrada. As mudanças e adições em destaque são apresentadas abaixo.

Novos recursos e atualizações:

  • O PointerPredictor oferece aos aplicativos de entrada com sensibilidade de latência, como aplicativos de tinta digital, a capacidade de prever locais de ponto de entrada de até 15ms no futuro para obter melhor latência e animação suave.
  • O PenDeviceInterop permite que você adquira uma referência ao Windows.Devices.Input.PenDevice usando o método FromPointerPoint.
  • O InputCursor fornece uma distinção explícita entre os tipos de cursor de sistema predefinidos e os tipos de cursor personalizados, removendo o tipo "Personalizado" presente no CoreCursor e dividindo o objeto CoreCursor em objetos separados.
  • Atualizações para APIs InputCursor.
  • O GestureRecognizer saiu do experimental para Microsoft.UI.Input.
  • O PointerPoint saiu do experimental para Microsoft.UI.Input.
  • Entrada de mouse, toque e caneta totalmente suportada para arrastar e soltar WinUI 3.

Limitações importantes:

  • Esta versão das APIs de entrada tem issues conhecidos com o Windows versão 1809.
  • O MRT Core ainda não é suportado por nenhum subtipo de InputCursor.
  • O uso direto da API do SDK da plataforma Windows.UI.Core.CoreDragOperation não funcionará com os aplicativos da WinUI 3.
  • As propriedades PointerPoint, RawPosition e ContactRectRaw foram removidas porque se referiam a valores não previstos, que eram os mesmos que os valores normais no sistema operacional. Em vez disso, use a Posição e o ContactRect. A previsão de ponteiro agora é tratada com o objeto da API do Microsoft.UI.Input.PointerPredictor.

MRT Core (1.0.0-preview1)

A partir da versão 1.0 Preview 1, as APIs do MRT Core foram movidas do namespace Microsoft.ApplicationModel.Resources para o namespace Microsoft.Windows.ApplicationModel.Resources.

Outras limitações e problemas conhecidos:

  • As versões 1.0 Preview 1 e Preview 2 contêm um bug crítico. Se você já instalou uma dessas pré-visualizações, veja como resolver o problema. Em vez disso, recomendamos usar a versão 1.0 Preview 3.

  • Projetos criados usando o modelo de projeto C++ Aplicativo em branco e empacotado com WAP (WinUI 3 na área de trabalho) encontram o seguinte erro de build por padrão: fatal error C1083: Cannot open include file: 'winrt/microsoft.ui.dispatching.co_await.h': No such file or directory. Para resolver esse issue, remova a seguinte linha de código do arquivo pch.h. Esse problema será corrigido na próxima versão.

    #include <winrt/microsoft.ui.dispatching.co_await.h>

  • Uma alternativa ao DispatcherQueue.TryEnqueue (para retomar a execução no thread da fila do dispatcher) é usar a função auxiliar resume_foreground na WIL (Biblioteca de Implementação do Windows):

    1. Adicione uma referência ao seu projeto ao pacote NuGet Microsoft.Windows.ImplementationLibrary.
    2. Adicione #include <wil/cppwinrt_helpers.h> ao seu pch.h.
    3. Adicione #include <winrt/Microsoft.UI.Dispatching.h> ao seu pch.h.
    4. Agora co_await wil::resume_foreground(your_dispatcherqueue);.

  • Não há suporte para qualquer configuração da compilação de CPU: o SDK do Aplicativo Windows é escrito em código nativo e, portanto, não oferece suporte para qualquer configuração da compilação de CPU. Os modelos do WinUI 3 no Visual Studio só permitem compilações específicas da arquitetura. Ao adicionar o SDK do Aplicativo Windows a um aplicativo ou componente do .NET existente que seja compatível com qualquer CPU, especifique a arquitetura desejada: x86, x64 ou arm64.

  • Os aplicativos do .NET devem ter como destino o build 18362 ou posterior: o TFM deve ser definido como net6.0-windows10.0.18362 ou posterior e o projeto de empacotamento <TargetPlatformVersion> deve ser definido como 18362 ou posterior. Para obter mais informações, confira o issue conhecido no GitHub.

  • Os projetos C# que usam a versão 1.0 do Preview 1 devem usar o seguinte SDK do .NET: SDK do .NET 6 ou posterior (confira Fazer download do .NET e o .NET 5 chegará ao fim do suporte em 10 de maio de 2022).

  • Aplicativos não empacotados não suportados no Windows 10 versão 1809: isso deve ser resolvido na próxima versão.