Use o SDK de Aplicações Windows numa aplicação WPF

O SDK de Aplicações Windows é a próxima evolução na plataforma de desenvolvimento de aplicações Windows. Mas este tópico mostra como podes usar APIs SDK de Aplicações Windows (e APIs Windows Runtime) numa aplicação Windows Presentation Foundation (WPF)!

• Em muitos casos, vai querer recriar a sua aplicação WPF na forma de uma aplicação WinUI 3. Uma das vantagens de migrar para o WinUI é ter acesso ao Fluent Design System (ver também Design and code Windows apps). E o WinUI faz parte do SDK de Aplicações Windows — por isso, naturalmente, uma aplicação WinUI pode usar as outras funcionalidades e APIs do SDK de Aplicações Windows também. Este tópico não aborda o processo de migração da sua aplicação WPF para o WinUI.
• Mas se descobrir que está a usar funcionalidades do WPF que ainda não estão disponíveis no WinUI, então pode ainda usar funcionalidades do SDK de Aplicações Windows (como App Lifecycle, MRT Core, DWriteCore e outras) na sua aplicação WPF. Este tópico mostra como.

E caso ainda não tenha um projeto WPF existente — ou queira praticar o processo — este tópico inclui passos para criar um projeto WPF para que possa acompanhar e configurá-lo para chamar APIs do SDK de Aplicações Windows.

Pré-requisitos

1. Instalar ferramentas para o SDK de Aplicações Windows.
2. Este tópico abrange tanto aplicações WPF não empacotadas como aplicações empacotadas. Se a sua aplicação WPF estiver desempacotada (o que as aplicações WPF são por defeito), certifique-se de que todas as dependências para aplicações desempacotadas estão instaladas (veja o guia de implementação do SDK de Aplicações Windows para aplicações dependentes do framework empacotadas com localização externa ou desempacotadas). Uma forma rápida de o fazer é visitar o Últimos downloads do SDK de Aplicações Windows, depois descarregar, descompactar e executar um dos downloads de Runtime estáveis.

Para mais informações sobre os termos desempacotados e empacotados, consulte Vantagens e desvantagens de empacotar a sua aplicação.

Crie um projeto WPF se ainda não tiver um

Se já tem um projeto WPF, pode passar para a secção seguinte.

1. No Visual Studio, crie um novo projeto C# WPF Application (que é um projeto .NET). Tenha cuidado ao escolher o modelo de projeto com o nome exato WPF Application, e não o modelo de WPF App (.NET Framework).
2. Dá um nome ao project e aceita todas as opções padrão.

Agora tens um projeto que constrói uma aplicação WPF não empacotada.

Configure o seu projeto WPF para suporte ao SDK de Aplicações Windows

Primeiro vamos editar o ficheiro do project.

1. Em Explorador de Soluções, clique com o botão direito no seu projeto e escolha Editar Ficheiro de Projeto.

2. Este passo permite-lhe chamar APIs Windows Runtime (WinRT) (incluindo APIs SDK de Aplicações Windows). Dentro do elemento PropertyGroup está o elemento TargetFramework, que é configurado para um valor como net6.0. Acrescente a esse valor de estrutura-alvo um apelido (especificamente, um Target Framework Moniker). Por exemplo, use o seguinte se a sua aplicação tiver como objetivo o Windows 10, versão 2004:

   <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
   

3. Também dentro do elemento PropertyGroup, adicione um elemento RuntimeIdentifiers, como mostrado abaixo. Se estiver a destinar-se a .NET 8 ou superior, use o valor win-x86;win-x64;win-arm64 em vez disso.

   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
   

4. Por padrão, uma aplicação WPF está sem pacote (ou seja, não é instalada usando MSIX). Uma aplicação não empacotada deve inicializar o runtime do SDK de Aplicações Windows antes de usar qualquer outra funcionalidade do SDK de Aplicações Windows. Você pode fazer isso automaticamente quando seu aplicativo for iniciado por meio de inicialização automática . Basta definir (também dentro do elemento PropertyGroup) a propriedade WindowsPackageType project de forma apropriada, assim:

   <WindowsPackageType>None</WindowsPackageType>
   

   Se tiver necessidades avançadas (como tratamento personalizado de erros ou carregar uma versão específica do SDK de Aplicações Windows), então em vez de autoinicialização pode chamar explicitamente a API do bootstrapper — para mais informações, veja Use o runtime SDK de Aplicações Windows para aplicações empacotadas com localização externa ou não empacotadas.

5. Guarde e feche o ficheiro do project.

De seguida, vamos instalar o pacote NuGet do SDK de Aplicações Windows no projeto.

6. Em Explorador de Soluções, clique com o botão direito no nó Dependências do seu projeto e escolha Gerir Pacotes NuGet....
7. Na janela NuGet Gestor de Pacotes, selecione o separador Browse e instale o Latest stableMicrosoft. WindowsAppSDK pacote.

Use algumas funcionalidades do SDK de Aplicações Windows na sua aplicação WPF

Esta secção oferece um exemplo muito simples de como chamar APIs do SDK de Aplicações Windows a partir de uma aplicação WPF. Ele usa o recurso MRT Core (consulte Gerenciar recursos com o MRT Core). Se este exemplo funcionar para o teu projeto WPF (e se criaste um novo para este walkthrough, então funcionará), então podes seguir estes passos.

1. Adicione a seguinte marcação a MainWindow.xaml (poderá colá-la dentro da raiz Grid):

   <StackPanel>
       <Button HorizontalAlignment="Center" Click="Button_Click">Click me!</Button>
       <TextBlock HorizontalAlignment="Center" x:Name="myTextBlock">Hello, World!</TextBlock>
   </StackPanel>
   

2. Agora vamos adicionar algum código que usa a classe ResourceManager no SDK de Aplicações Windows para carregar um recurso de cadeia.

   1. Adicione um novo item Resources File (.resw) ao seu project (mantenha-o com o nome padrão Resources.resw).

   2. Com o arquivo de recursos aberto no editor, crie um novo recurso de cadeia de caracteres com as seguintes propriedades.

      • Nome: Mensagem
      • Valor: Olá, recursos!

   3. Salve e feche o arquivo de recursos.

   4. No MainWindow.xaml.cs, adicione o seguinte manipulador de eventos:

   private void Button_Click(object sender, RoutedEventArgs e)
   {
       // Construct a resource manager using the resource index generated during build.
       var manager = 
         new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
   
       // Look up a string in the resources file using the string's name.
       myTextBlock.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
   }
   

3. Compila o projeto e corre a app. Clique no botão para ver a cadeia de caracteres Hello, resources! exibida.

Consulte também Runtime architecture para saber mais sobre a dependência de pacotes Framework que a sua aplicação assume quando utiliza o SDK de Aplicações Windows, e os componentes adicionais necessários para funcionar numa aplicação não empacotada.

Empacota e implementa a tua aplicação WPF com o MSIX

Algumas funcionalidades Windows e APIs (incluindo as APIs SDK de Aplicações Windows notifications) exigem que a sua aplicação tenha > em tempo de execução (ou seja, a sua aplicação precisa de ser empacotada). Para mais informações, veja Funcionalidades que requerem identidade de pacote.

1. Em Explorador de Soluções em Visual Studio, clique com o botão direito na solução e escolha Add>New Project... .
2. Na caixa de diálogo Adicionar um novo projeto, procure em packaging, escolha o modelo de projeto C# Windows Application Packaging Project e clique em Próximo.
3. Nomeia o project e clica em Criar.
4. Queremos especificar quais aplicativos na solução devem ser incluídos no pacote. Assim, no projeto de embalagem (não no projeto WPF), clique com o botão direito no nó Dependências e escolha Adicionar Referência ao Projeto....
5. Na lista de projetos da solução, escolha o seu projeto WPF e clique em OK.
6. Expanda o nó Dependencies>Applications do projeto de embalagem e confirme que o seu projeto de WPF está referenciado e destacado a negrito. Isto significa que será utilizado como ponto de partida para o pacote.
7. Clique com o botão direito no projeto de empacotamento e escolha Set As Startup Project.
8. Clique com o botão direito no projeto WPF e escolha Editar Ficheiro do Projeto.
9. Exclua <WindowsPackageType>None</WindowsPackageType>, salve e feche.
10. No menu drop-down Plataformas de Solução, escolha x64 (em vez de Qualquer CPU).
11. Confirme se você pode compilar e executar.

Agora que já empacotou a sua aplicação WPF, pode chamar APIs que exigem identidade de pacote. Portanto, no MainWindow.xaml.cs, edite seu manipulador de eventos para ter esta aparência:

private void Button_Click(object sender, RoutedEventArgs e)
{
    var notification = new AppNotificationBuilder()
        .AddArgument("action", "viewConversation")
        .AddArgument("conversationId", "9813")
        .AddText("Andrew sent you a picture")
        .AddText("Check this out, The Enchantments in Washington!")
        .BuildNotification();

    AppNotificationManager.Default.Show(notification);
}

Compile e execute novamente. Clique no botão e confirme que uma notificação curta é exibida. Quando chamadas de um processo que não possui identidade de pacote em tempo de execução, as APIs de notificações lançam uma exceção.

Executar código em segundo plano

Para aplicações WPF que precisam de executar código quando a aplicação não está a correr, existem três abordagens dependendo do seu empacotamento e carga de trabalho:

Para SDK de Aplicações Windows tarefas em segundo plano, a sua aplicação WPF regista um componente COM usando BackgroundTaskBuilder tal como uma aplicação WinUI 3 — o evento Application.Startup em WPF corresponde ao papel que App.OnLaunched desempenha no WinUI 3. Veja Usar tarefas em segundo plano nas Windows apps para o guia completo.

Tópicos relacionados

• Windows Presentation Foundation (WPF)
• Instalar ferramentas para o SDK de Aplicações Windows
• Guia de Implementação do SDK de Aplicações Windows para aplicações dependentes do framework, empacotadas com localização externa ou sem embalagem
• Últimos downloads para o SDK de Aplicações Windows
• Vantagens e desvantagens de empacotar seu aplicativo
• Utilize o runtime do SDK de Aplicações Windows para aplicações empacotadas com conteúdo externo ou não empacotadas
• Arquitetura de Execução
• Funcionalidades que exigem identidade do pacote