Tutorial: Utilizar a API de bootstrapper numa aplicação empacotada com localização externa ou numa aplicação desempacotada que utiliza o Windows App SDK

Siga estas instruções para configurar um projeto C# WinUI 3 empacotado com localização externa ou desempacotado.

1. No Visual Studio, crie um novo aplicativo de console C# projeto. Nomeie o projeto DynamicDependenciesTest. Depois de criar o projeto, você deve ter um "Olá, Mundo!" Aplicativo de console C#.

2. Em seguida, configure seu projeto.

   1. No Gerenciador de Soluções, clique com o botão direito do mouse em seu projeto e escolha Editar arquivo de projeto.
   2. Substitua o valor do elemento TargetFramework por um Target Framework Moniker. Por exemplo, use o seguinte se seu aplicativo tiver como alvo o Windows 10, versão 2004.

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

   1. Salve e feche o arquivo de projeto.

3. Altere a plataforma da sua solução para x64. O valor padrão em um projeto .NET é AnyCPU, mas WinUI 3 não suporta essa plataforma.

   1. Selecione Compilação>Gestor de Configurações.
   2. Selecione a lista suspensa sob Plataforma de solução ativa e clique em Nova para abrir a caixa de diálogo Nova Plataforma de Solução.
   3. Na lista suspensa em , escolha ou introduza a nova plataforma, e selecione x64.
   4. Clique OK para fechar a caixa de diálogo Nova Plataforma de Solução.
   5. No Configuration Manager, clique em Fechar.

4. Instale o pacote NuGet do SDK de Aplicativo Windows em seu projeto.

   1. No Explorador de Soluções, clique com o botão direito do rato no nó Dependências e escolha Gerir Pacotes NuGet.
   2. Na janela Gerenciador de Pacotes NuGet, selecione a guia Procurar e instale o pacote Microsoft.WindowsAppSDK.

5. Agora você está pronto para usar a API de bootstrapper (consulte Usar o tempo de execução do SDK de Aplicações da Windows para aplicações empacotadas com local externo ou não empacotadas) para assumir dinamicamente uma dependência do pacote estrutural do Windows App SDK. Isso permite que você use as APIs do SDK de aplicativos Windows em seu aplicativo.

   Abra o arquivo de código Program.cs e substitua o código padrão pelo código a seguir para chamar o Bootstrap.Initialize método para inicializar o bootstrapper. Esse código define de qual versão do SDK do Aplicativo Windows o aplicativo depende ao inicializar o bootstrapper.

   Importante

   Você precisará editar o código abaixo para se adequar à sua configuração específica. Consulte as descrições dos parâmetros do método Bootstrap.Initialize para que você possa especificar uma das versões do SDK do Aplicativo Windows instaladas.

   using System;
   using Microsoft.Windows.ApplicationModel.DynamicDependency;
   
   namespace DynamicDependenciesTest
   {
       class Program
       {
           static void Main(string[] args)
           {
               Bootstrap.Initialize(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   Em sua raiz, a API de bootstrapper é uma API C/C++ nativa que permite que você use as APIs do SDK de aplicativos Windows em seu aplicativo. Mas em um aplicativo .NET que usa o Windows App SDK 1.0 ou posterior, você pode usar o wrapper .NET para a API de bootstrapper. Esse wrapper fornece uma maneira mais fácil de chamar a API de bootstrapper em um aplicativo .NET do que chamar as funções C/C++ nativas diretamente. O exemplo de código anterior chama os métodos estáticos Initialize e Shutdown da classe Bootstrap no envelope .NET para a API de arranque.

6. Para demonstrar que os componentes de runtime do Windows App SDK foram carregados corretamente, adicione algum código que utilize a classe ResourceManager no Windows App SDK para carregar um recurso de texto.

   1. Adicione um novo ficheiro de recursos (.resw) ao seu projeto (mantenha o nome padrão).

   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 o arquivo de recursos.

   4. Abra o arquivo de código Program.cs e substitua a linha Console.WriteLine("Hello, World!"); pelo código a seguir.

   // Create a resource manager using the resource index generated during build.
      var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri");
   
   // Look up a string in the .resw file using its name.
   Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);
   

   1. Clique Iniciar sem depuração (ou Iniciar a depuração) para compilar e executar a sua aplicação. Você deverá ver a string Hello, resources! exibida com êxito.

Siga estas instruções para configurar um projeto C++ WinUI 3 que seja empacotado com uma localização externa, ou desempacotado.

1. No Visual Studio, crie um novo projeto de C++ Console App. Nomeie o projeto DynamicDependenciesTest.

   

   Depois de criar o projeto, você deve ter um "Olá, Mundo!" Aplicativo de console C++.

2. Em seguida, instale o pacote NuGet do SDK de Aplicativo Windows em seu projeto.

   1. No Explorador de Soluções , clique com o botão direito do mouse no nó Referências e escolha Gerenciar Pacotes NuGet.
   2. Na janela Gestor de Pacotes NuGet, selecione o separador Procurar e pesquise Microsoft.WindowsAppSDK.

3. Agora você está pronto para usar a API de bootstrapper (consulte Usar o tempo de execução do SDK de Aplicativos Windows para aplicativos empacotados com local externo ounão empacotados) para inicializar o tempo de execução do SDK de Aplicativo Windows em seu aplicativo. Isso permite que você use as APIs do SDK de aplicativos Windows no aplicativo.

   1. Adicione os seguintes ficheiros de inclusão à parte superior do seu ficheiro DynamicDependenciesTest.cpp. O cabeçalho de mddbootstrap.h está disponível por meio do pacote NuGet do SDK de Aplicativo Windows.

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. Em seguida, adicione esse código no início do método principal para chamar a função MddBootstrapInitialize para inicializar o bootstrapper e manipular quaisquer erros. Esse código define de qual versão do SDK do Aplicativo Windows o aplicativo depende ao inicializar o bootstrapper.

   Importante

   Você precisará editar o código abaixo para se adequar à sua configuração específica. Consulte as descrições dos parâmetros da função MddBootstrapInitialize para que você/s possa/m especificar uma das versões do SDK do Windows App que você/s instalou/aram.

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. Finalmente, adicione esse código para exibir a cadeia de caracteres Hello, World! e chame a função MddBootstrapShutdown para desinicializar o bootstrapper.

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. Seu código final deve ter esta aparência.

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. Clique Iniciar sem depuração (ou Iniciar a depuração) para compilar e executar a sua aplicação.