Usar o SDK do Aplicativo Windows em um aplicativo WPF

  • Artigo

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

  • Em muitos casos, convém recriar o aplicativo WPF na forma de um aplicativo Biblioteca de Interface do Usuário 3 do Windows (WinUI 3). Apenas uma das vantagens de migrar para o WinUI 3 é ter acesso ao Sistema Fluent Design (consulte também Design e código de aplicativos do Windows). E o WinUI 3 faz parte do SDK do Aplicativo Windows, portanto, naturalmente, um aplicativo WinUI 3 também pode usar os outros recursos e APIs do SDK do Aplicativo Windows. Este tópico não aborda o processo de migrar do aplicativo WPF para o WinUI 3.
  • Porém, se você achar que está usando recursos do WPF que ainda não estão disponíveis no WinUI 3, ainda poderá usar os recursos do 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 inclui etapas para criar um projeto WPF para que você possa acompanhar e configurá-lo para chamar APIs do SDK do Aplicativo Windows.

Pré-requisitos

  1. Instalar ferramentas para o SDK do Aplicativo Windows.
  2. Este tópico aborda aplicativos WPF empacotados e não empacotados. Se seu aplicativo WPF for não empacotado (o que os aplicativos WPF são, por padrão), verifique se todas as dependências para aplicativos não empacotados estão instaladas (consulte Guia de implantação do SDK do Aplicativo Windows para aplicativos dependentes de estrutura empacotados com localização externa ou não empacotados). Uma maneira rápida de fazer isso é visitar Downloads mais recentes do SDK do Aplicativo Windows, baixar e descompactar e executar um dos Downloads de runtime da versão estável.

Importante

A versão do Runtime que você instalar precisa corresponder à versão do pacote NuGet Microsoft.WindowsAppSDK que você instalará em uma etapa posterior.

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

Criar um projeto do WPF caso ainda não tenha um

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

  1. No Visual Studio, crie um projeto de Aplicativo WPF em C# (que é um projeto .NET). Tenha cuidado ao escolher o modelo de projeto com o nome exato Aplicativo WPF, e não o Aplicativo WPF (.NET Framework).
  2. Atribua um nome ao projeto e aceite todas as opções padrão.

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

Configurar seu projeto WPF para suporte ao SDK do Aplicativo Windows

Primeiro, editaremos o arquivo de projeto.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e escolha Editar Arquivo de Projeto.

  2. Esta etapa permite chamar APIs do Windows Runtime (WinRT) (incluindo APIs do 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 seu aplicativo visar o Windows 10, versão 2004:

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

  3. Além disso, dentro do elemento PropertyGroup, adicione um elemento RuntimeIdentifiers, conforme mostrado abaixo. Se você estiver visando o .NET 8 ou posterior, use o valor win-x86;win-x64;win-arm64.

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

  4. Por padrão, um aplicativo WPF é não empacotado (o que significa que ele não é 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. Você apenas define (também dentro do elemento PropertyGroup) a propriedade do projeto WindowsPackageType adequadamente, da seguinte forma:

    <WindowsPackageType>None</WindowsPackageType>

    Se você tiver necessidades avançadas (como tratamento de erros personalizado ou carregar uma versão específica do SDK do Aplicativo Windows), em vez de inicialização automática, poderá chamar a API de bootstrapper explicitamente. Para obter mais informações, consulte Usar o runtime do SDK do Aplicativo Windows para aplicativos empacotados com localização externa ou não empacotado.

  5. Salve e feche o arquivo de projeto.

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

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependencies de seu projeto e escolha Gerenciar Pacotes Nuget....
  2. Na janela Gerenciador de Pacotes NuGet, selecione a guia Procurar e instale o pacote Microsoft.WindowsAppSDKestável mais recente.

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

Esta seção oferece um exemplo muito simples de chamar APIs do 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 WPF (e se você tiver criado um novo para este passo a passo, então ele irá), 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 algum 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 Arquivo de Recursos (.resw) ao seu projeto (deixe-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 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.

Dica

Se, no runtime, você vir uma caixa de mensagem indicando que o aplicativo precisa de uma versão específica do Windows App Runtime e perguntar se você deseja instalá-lo agora, clique em Sim. Isso o levará para Downloads mais recentes do SDK do Aplicativo Windows. Para obter mais informações, confira a seção Pré-requisitos acima.

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

Empacotar e implantar seu aplicativo WPF com o MSIX

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

  1. No Gerenciador de Soluções no Visual Studio, clique com o botão direito do mouse na solução e escolha Adicionar>Novo Projeto....
  2. Na caixa de diálogo Adicionar um novo projeto, procure empacotamento,, escolha o modelo de projeto Projeto de Empacotamento de Aplicativo do Windows em C# e clique em Avançar.
  3. Nomeie o projeto e clique em Criar.
  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ó Dependências e escolha Adicionar Referência de Projeto....
  5. Na lista de projetos na solução, escolha seu projeto do WPF e clique em OK.
  6. Expanda o nó Dependências>Aplicativos do projeto de empacotamento e confirme se o projeto WPF está referenciado e realçado em negrito. Isso significa que ele será usado como um 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 no projeto WPF e escolha Editar Arquivo de Projeto.
  9. Exclua <WindowsPackageType>None</WindowsPackageType>, salve e feche.
  10. Na lista suspensa Plataformas da Solução, escolha x64 (em vez de Any Cpu).
  11. Confirme se você pode compilar e executar.

Agora que você empacotou seu aplicativo WPF, poderá chamar APIs que requeiram identidade de 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 do sistema é 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.

Observação

As etapas nesta seção mostraram como criar um aplicativo empacotado. Uma alternativa é criar um aplicativo empacotado com localização externa. Para obter um lembrete de todos esses termos, consulte Vantagens e desvantagens de empacotar o aplicativo.