Compartilhar via

Usar o SDK do Aplicativo Windows em um aplicativo Windows Forms (WinForms)

  • 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 de Aplicativo do Windows (e as APIs do Windows Runtime) em um aplicativo Windows Forms (WinForms)!

  • Em muitos casos, convém recriar o aplicativo WinForms na forma de um aplicativo 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 WinForms para o WinUI 3.
  • Porém, se você achar que está usando recursos do WinForms 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 WinForms. Este tópico mostra como fazer isso.

E, caso você ainda não tenha um projeto WinForms 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 de Aplicativo do Windows.

Pré-requisitos

  1. Instalar ferramentas para o SDK do Aplicativo Windows.
  2. Este tópico aborda aplicativos WinForms empacotados e não empacotados. Se seu aplicativo WinForms for não empacotado (o que os aplicativos WinForms 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 de Aplicativo do 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.

Crie um projeto do WinForms se ainda não tiver um.

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

  1. No Visual Studio, crie um projeto de Aplicativo Windows Forms em C# (que é um projeto .NET). Tenha cuidado ao escolher o modelo de projeto com o nome exato Aplicativo Windows Forms, e não o Aplicativo Windows Forms (.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 WinForms não empacotado.

Configurar seu projeto WinForms para suporte ao SDK de Aplicativo do 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.

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

  4. Por padrão, um aplicativo WinForms é 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.WindowsAppSDK estável mais recente.

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

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

  1. Abra Form1.cs (usando o comando Designer de Exibição), e arrastar um Botão e um Rótulo da Caixa de ferramentas e no designer.

  2. Clique duas vezes no botão1 para gerar um manipulador de eventos.

  3. 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. Abra Form1.cs (usando o comando Visualizar código) e edite o manipulador de eventos para ter a seguinte aparência:

    private void button1_Click(object sender, EventArgs 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.
    label1.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
}

  4. 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 WinForms 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 WinForms), 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 WinForms e clique em OK.
  6. Expanda o nó Dependências>Aplicativos do projeto de empacotamento e confirme se o projeto WinForms 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 WinForms 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 WinForms, poderá chamar APIs que requeiram identidade de pacote. Portanto, abra Form1.cs (usando o comando Visualizar código) e edite o manipulador de eventos para ter a seguinte aparência:

private void button1_Click(object sender, EventArgs 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.