Usar o SDK do Aplicativo Windows em um aplicativo WPF

O SDK do Aplicativo Windows é a próxima evolução na plataforma de desenvolvimento de aplicativos Windows. Mas este tópico mostra como você pode usar APIs SDK do Aplicativo Windows (e APIs Windows Runtime) em um aplicativo Windows Presentation Foundation (WPF)!

• Em muitos casos, você desejará recriar seu aplicativo WPF na forma de um aplicativo WinUI 3. Apenas uma das vantagens de migrar para o WinUI é ter acesso ao Fluent Design System (consulte também Design e code Windows apps). E o WinUI faz parte do SDK do Aplicativo Windows, portanto, naturalmente, um aplicativo WinUI também pode usar os outros recursos e APIs do SDK do Aplicativo Windows. Este tópico não aborda o processo de migração do aplicativo WPF para o WinUI.
• Mas se você descobrir que está usando recursos de WPF que ainda não estão disponíveis no WinUI, ainda poderá usar recursos SDK do Aplicativo Windows (como Ciclo de Vida do Aplicativo, MRT Core, DWriteCore e outros) em seu aplicativo WPF. Este tópico mostra como fazer isso.

E caso você ainda não tenha um projeto WPF existente ou queira praticar o processo, este tópico incluirá etapas para criar um projeto WPF para que você possa acompanhar e configurá-lo para chamar SDK do Aplicativo Windows APIs.

Pré-requisitos

1. Instalar ferramentas para o SDK do Aplicativo Windows.
2. Este tópico aborda aplicativos de WPF não empacotados e empacotados. Se o aplicativo WPF estiver desempacotado (quais WPF aplicativos são por padrão), verifique se todas as dependências de aplicativos não empacotados estão instaladas (consulte SDK do Aplicativo Windows guia de implantação para aplicativos dependentes de estrutura empacotados com localização externa ou não empacotados). Uma maneira rápida de fazer isso é visitar os Últimos downloads para o SDK do Aplicativo Windows, e então baixar, descompactar e executar um dos downloads de Runtime de versão estável.

Para obter mais informações sobre os termos não empacotado e empacotado, consulte Vantagens e desvantagens de empacotar o aplicativo.

Criar um projeto de WPF se você ainda não tiver um

Se você já tiver um projeto WPF, poderá passar para a próxima seção.

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

Agora você tem um projeto que cria um aplicativo WPF não empacotado.

Configuração do seu projeto WPF para suporte ao SDK do Aplicativo Windows

Primeiro, editaremos o arquivo project.

1. Em Gerenciador de Soluções, clique com o botão direito do mouse em seu project e escolha Edit Project File.

2. Esta etapa permite que você chame APIs Windows Runtime (WinRT) (incluindo APIs SDK do Aplicativo Windows). Dentro do elemento PropertyGroup está o elemento TargetFramework, que é definido como um valor, por exemplo, net6.0. Acrescente a esse valor de estrutura de destino um moniker (especificamente, um Moniker da Estrutura de Destino). Por exemplo, use o seguinte se o aplicativo esteja direcionado para 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, conforme mostrado abaixo. Se você estiver visando o .NET 8 ou posterior, então use o valor win-x86;win-x64;win-arm64.

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

4. Por padrão, um aplicativo WPF é descompactado (o que significa que ele não está instalado usando o MSIX). Um aplicativo não empacotado deve inicializar o runtime do SDK do Aplicativo Windows antes de usar qualquer outro recurso do SDK do Aplicativo Windows. Você pode fazer isso automaticamente quando seu aplicativo é iniciado por meio da inicialização automática. Basta definir (também dentro do elemento PropertyGroup) a propriedade do WindowsPackageType projeto adequadamente, desta forma:

   <WindowsPackageType>None</WindowsPackageType>
   

   Se você tiver necessidades avançadas (como tratamento de erros personalizados, ou para carregar uma versão específica do SDK do Aplicativo Windows), em vez de auto-initialization você pode chamar a API bootstrapper explicitamente— para obter mais informações, consulte Use o runtime SDK do Aplicativo Windows para aplicativos empacotados com local externo ou não empacotados.

5. Salve e feche o arquivo do projeto.

Em seguida, instalaremos o SDK do Aplicativo Windows pacote NuGet no projeto.

6. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependencies do seu projeto e escolha Manage Nuget Packages... .
7. Na janela NuGet Gerenciador de Pacotes, selecione a guia Browse e instale o Latest stableMicrosoft. WindowsAppSDK pacote.

Usar alguns recursos de SDK do Aplicativo Windows em seu aplicativo WPF

Esta seção oferece um exemplo muito simples de chamar APIs de SDK do Aplicativo Windows de um aplicativo WPF. Ele usa o recurso MRT Core (consulte Gerenciar recursos com o MRT Core). Se este exemplo funcionar para seu projeto de WPF (e se você criou um novo para este passo a passo, então ele funcionará), você poderá seguir estas etapas.

1. Adicione a seguinte marcação a MainWindow.xaml (você pode 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, adicionaremos um código que usa a classe ResourceManager no SDK do Aplicativo Windows para carregar um recurso de cadeia de caracteres.

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

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

      • Nome: Message
      • Valor: Hello, resources!

   3. Salve e feche o arquivo de recursos.

   4. Em 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. Compile o projeto e execute o aplicativo. Clique no botão para ver a cadeia de caracteres Hello, resources! exibida.

Consulte também a arquitetura Runtime para saber mais sobre a dependência do pacote Framework que seu aplicativo usa quando usa o SDK do Aplicativo Windows e os componentes adicionais necessários para funcionar em um aplicativo não empacotado.

Empacotar e implantar seu aplicativo WPF com o MSIX

Alguns recursos do Windows e APIs (incluindo as APIs de notificações do SDK do Aplicativo Windows) exigem que seu aplicativo tenha identidade de pacote em tempo de execução (em outras palavras, seu aplicativo precisa ser empacotado). Para obter mais informações, consulte os Recursos que exigem a identidade do pacote.

1. Em Gerenciador de Soluções no Visual Studio, clique com o botão direito do mouse na solução e escolha Add>New Project... .
2. Na caixa de diálogo Adicionar um novo projeto, pesquise por embalagens, escolha o modelo de projeto Windows Application Packaging do C# e clique em Avançar.
3. Nomeie o project e clique em Create.
4. Queremos especificar quais aplicativos na solução devem ser incluídos no pacote. Portanto, no projeto de empacotamento (não o projeto WPF), clique com o botão direito do mouse no nó Dependencies e escolha Adicionar Referência ao Projeto....
5. Na lista de projetos na solução, escolha seu projeto de WPF e clique em OK.
6. Expanda o nó de Dependencies>Applications e verifique se o projeto WPF está listado e destacado em negrito. Isso significa que será utilizado como ponto de partida para o pacote.
7. Clique com o botão direito do mouse no projeto de empacotamento e escolha Definir como Projeto de Inicialização.
8. Clique com o botão direito do mouse no WPF project e escolha Edit Project File.
9. Exclua <WindowsPackageType>None</WindowsPackageType>, salve e feche.
10. Na lista suspensa Plataformas de Solução, selecione x64 (em vez de Any Cpu).
11. Confirme se você pode compilar e executar.

Agora que você empacotou seu aplicativo WPF, você pode chamar APIs que exigem a identidade do pacote. Portanto, no MainWindow.xaml.cs, edite seu manipulador de eventos para ter a seguinte 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 se uma notificação de toast é exibida. Quando chamadas de um processo que não tem identidade de pacote no runtime, as APIs de notificações lançam uma exceção.

Executar código em segundo plano

Para aplicativos WPF que precisam executar código quando o aplicativo não estiver em execução, há três abordagens dependendo do empacotamento e do volume de trabalho.

Para as tarefas em segundo plano do SDK do Aplicativo Windows, seu aplicativo WPF registra um componente COM usando BackgroundTaskBuilder, assim como um aplicativo WinUI 3. O evento Application.Startup em WPF corresponde à função que App.OnLaunched desempenha no WinUI 3. Consulte tarefas em segundo plano em aplicativos do Windows para obter o passo a passo completo.

Tópicos relacionados

• Windows Presentation Foundation (WPF)
• Instalar ferramentas para o SDK do Aplicativo Windows
• Guia de implantação do SDK do Aplicativo Windows para aplicativos dependentes de framework empacotados com localização externa ou não empacotados
• Últimos downloads para o SDK do Aplicativo Windows
• Vantagens e desvantagens de empacotar ou não o aplicativo
• Use o runtime do SDK do Aplicativo Windows para aplicativos empacotados com localização externa ou não empacotados
• Arquitetura de runtime
• Recursos que exigem a identidade do pacote