Utilize o Windows App SDK numa aplicação Windows Forms (WinForms)

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

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

E caso ainda não tenha um project WinForms existente — ou queira praticar o processo — este tópico inclui passos para criar um project WinForms para que possa acompanhar e configurá-lo para chamar APIs do Windows App SDK.

Pré-requisitos

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

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

Crie um project no WinForms se ainda não tiver um

Se já tens um project WinForms, podes passar para a secção seguinte.

1. Em Visual Studio, cria uma nova aplicação C# Windows Forms project (que é uma .NET project). Tem cuidado ao 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 aceita todas as opções padrão.

Agora tem um projeto que constrói uma aplicação WinForms não empacotada.

Configure o seu project WinForms para suporte ao Windows App SDK

Primeiro vamos editar o ficheiro do project.

1. Em Solution Explorer, clique com o botão direito no seu projeto e escolha Editar Ficheiro do Projeto.

2. Este passo permite-lhe chamar APIs Windows Runtime (WinRT) (incluindo APIs Windows App SDK). 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, assim:

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

4. Por padrão, um aplicativo WinForms é desempacotado (o que significa que ele não é instalado usando MSIX). Uma aplicação não empacotada deve inicializar o runtime do Windows App SDK antes de usar qualquer outra funcionalidade do Windows App SDK. 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 Windows App SDK), então em vez de autoinicialização pode chamar explicitamente a API do bootstrapper — para mais informações, veja Use o runtime Windows App SDK 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 Windows App SDK no project.

6. Em Solution Explorer, clique com o botão direito no nó Dependências do seu projeto e escolha Gerir Pacotes NuGet....
7. Na janela NuGet Package Manager, selecione o separador Browse e instale o pacote Latest stableMicrosoft.WindowsAppSDK.

Use algumas funcionalidades do Windows App SDK na sua aplicação WinForms

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

1. Abra Form1.cs (usando o comando View Designer) e arraste um Button e um Label para fora da Caixa de Ferramentas e para o designer.

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

3. Agora vamos adicionar algum código que usa a classe ResourceManager no Windows App SDK 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. Abra Form1.cs (usando o comando View Code ) e edite o manipulador de eventos para ter esta 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. 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 Windows App SDK, e os componentes adicionais necessários para funcionar numa aplicação não empacotada.

Empacote e implante seu aplicativo WinForms com MSIX

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

1. Em Solution Explorer 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 por packaging, escolha o modelo de projeto C# Windows Application Packaging Project e clique em Seguinte.
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 o projeto WinForms), clique com o botão direito no nó Dependências e escolha Adicionar Referência ao Projeto....
5. Na lista de projetos na solução, escolha o seu project WinForms e clique em OK.
6. Expanda o nó de dependências do projeto de embalagem Dependencies>Applications e confirme que o seu projeto WinForms está referenciado e destacado em 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 Definir como Projeto de Inicialização.
8. Clique com o botão direito no projeto WinForms e escolha Editar Ficheiro de 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 você empacotou seu aplicativo WinForms, pode chamar APIs que exigem identidade de pacote. Portanto, abra Form1.cs (usando o comando View Code ) e edite o manipulador de eventos para ter esta 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 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.

Tópicos relacionados

• Windows Forms (WinForms)
• Instalar ferramentas para o Windows App SDK
• Guia de Implementação do Windows App SDK para Apps Dependentes de Framework, Empacotadas com Localização Externa ou Não Empacotadas
• Últimos downloads para o Windows App SDK
• Vantagens e desvantagens de empacotar seu aplicativo
• Utilizar o runtime do Windows App SDK para aplicações empacotadas com local externo ou não empacotadas
• Arquitetura de Execução
• Funcionalidades que exigem identidade do pacote