Usar o Windows App SDK em um aplicativo Windows Forms (WinForms)

O Windows App SDK é a próxima evolução na plataforma de desenvolvimento Windows app. Mas este tópico mostra como você pode usar APIs Windows App SDK (e APIs Windows Runtime) em um aplicativo Windows Forms (WinForms)!

• Em muitos casos, você desejará recriar seu aplicativo WinForms 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 codifique aplicativos do Windows). E o WinUI faz parte do Windows App SDK, portanto, naturalmente, um aplicativo WinUI também pode usar os outros recursos e APIs do Windows App SDK. Este tópico não aborda o processo de migração do aplicativo WinForms para o WinUI.
• No entanto, se você descobrir que está usando recursos do WinForms que ainda não estão disponíveis no WinUI, ainda poderá usar Windows App SDK recursos (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 WinForms para que você possa acompanhar e configurá-lo para chamar as APIs do Windows App SDK.

Pré-requisitos

1. Instalar ferramentas para o Windows App SDK.
2. Este tópico aborda aplicativos WinForms empacotados e não empacotados. Se o aplicativo WinForms estiver descompactado (quais aplicativos WinForms são por padrão), verifique se todas as dependências de aplicativos não empacotados estão instaladas (consulte Windows App SDK 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 Windows App SDK, depois baixar, descompactar e executar um dos downloads de Runtime da versão estável Runtime.

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

Criar um projeto WinForms caso você ainda não tenha um

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

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

Agora você tem um projeto que compila um aplicativo WinForms não empacotado.

Configure seu projeto WinForms para suporte ao Windows App SDK

Primeiro, editaremos o arquivo project.

1. Em Solution Explorer, 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 Windows App SDK). 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 for destinado a Windows 10, versão 2004:

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

3. Também dentro do elemento PropertyGroup, adicione um elemento RuntimeIdentifiers desta forma:

   <RuntimeIdentifiers>win-x86;win-x64;win-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 Windows App SDK antes de usar qualquer outro recurso do Windows App SDK. 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 Windows App SDK), em vez de auto-initialization você pode chamar a API bootstrapper explicitamente— para obter mais informações, consulte Use o runtime Windows App SDK para aplicativos empacotados com local externo ou não empacotados.

5. Salve e feche o arquivo do projeto.

Em seguida, instalaremos o pacote NuGet Windows App SDK no project.

6. Em Solution Explorer, clique com o botão direito do mouse no nó Dependencies do projeto e escolha Gerenciar Pacotes NuGet....
7. Na janela NuGet Package Manager, selecione a guia Browse e instale o pacote Latest stableMicrosoft.WindowsAppSDK.

Usar alguns recursos de Windows App SDK em seu aplicativo WinForms

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

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

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

3. Agora, adicionaremos um código que usa a classe ResourceManager no Windows App SDK 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. 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.

Consulte também a arquitetura Runtime para saber mais sobre a dependência do pacote Framework que seu aplicativo usa quando usa o Windows App SDK e os componentes adicionais necessários para funcionar 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ções do Windows App SDK) exigem que seu aplicativo tenha identidade do pacote no 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 Solution Explorer 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 empacotamento, escolha o modelo de projeto de empacotamento de aplicativo C# Windows Application Packaging Project 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 WinForms), 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 o project do WinForms e clique em OK.
6. Expanda o nó de Dependencies>Applications do projeto de embalagem e confirme se o projeto de WinForms é referenciado e realçado 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 Set As Startup Project.
8. Clique com o botão direito do mouse no projeto WinForms e escolha Editar Arquivo de Projeto.
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 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 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.

Tópicos relacionados

• Windows Forms (WinForms)
• Instalar ferramentas para o Windows App SDK
• Guia de implantação do Windows App SDK para apps dependentes de framework empacotados com local externo ou desempacotados
• Últimos downloads para o Windows App SDK
• Vantagens e desvantagens de empacotar ou não o aplicativo
• Use o runtime do Windows App SDK para aplicativos empacotados com embalagem externa ou não empacotados
• Arquitetura de runtime
• Recursos que exigem a identidade do pacote