Tutorial: Usar a API bootstrapper em um aplicativo empacotado com localização externa ou desempacotado que utiliza o Windows App SDK

Siga estas instruções para configurar um projeto WinUI em C# que esteja empacotado em local externo ou desempacotado.

1. Em Visual Studio, crie um novo aplicativo C# Console project. Nomear o projeto DynamicDependenciesTest. Depois de criar o project, você deverá ter um aplicativo de console C# "Olá, Mundo!".

2. Em seguida, configure o projeto.

   1. Em Solution Explorer, clique com o botão direito do mouse no seu projeto e escolha Editar Arquivo de Projeto.
   2. Substitua o valor do elemento TargetFramework por um Identificador de Estrutura de Destino. Por exemplo, use o seguinte se o aplicativo for direcionado para o Windows 10, versão 2004.

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

   1. Salve e feche o arquivo do projeto.

3. Altere a plataforma da solução para x64. O valor padrão em um .NET project é AnyCPU, mas o WinUI não dá suporte a essa plataforma.

   1. Selecione Build>Configuration Manager.
   2. Selecione o menu suspenso em Plataforma de solução ativa e clique em Novo para abrir a caixa de diálogo Nova Plataforma de Solução.
   3. Na caixa suspensa em Digite ou selecione a nova plataforma, selecione x64.
   4. Clique em OK para fechar a caixa de diálogo Nova Plataforma de Solução .
   5. Em Configuration Manager, clique em Close.

4. Instale o pacote NuGet Windows App SDK em seu project.

   1. Em Solution Explorer, clique com o botão direito do mouse no nó Dependencies e escolha Manage Nuget Packages.
   2. Na janela NuGet Package Manager, selecione a guia Browse e instale o pacote Microsoft.WindowsAppSDK.

5. Agora você está pronto para usar a API bootstrapper (consulte usando o runtime do Windows App SDK para aplicativos empacotados em localização externa ou não empacotados) para estabelecer dinamicamente uma dependência do pacote de estrutura do Windows App SDK. Isso permite que você use as APIs de Windows App SDK 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 método Bootstrap.Initialize para inicializar o bootstrapper. Esse código define de qual versão do Windows App SDK 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 Windows App SDK instalada.

   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();
           }
       }
   }
   

   Na raiz, a API bootstrapper é uma API C/C++ nativa que permite que você use as APIs de Windows App SDK 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 bootstrapper. Esse wrapper fornece uma maneira mais fácil de chamar a API bootstrapper em um aplicativo .NET do que chamar diretamente as funções C/C++ nativas. O exemplo de código anterior chama os métodos estáticos Initialize e Shutdown da classe Bootstrap no wrapper .NET para a API bootstrapper.

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

   1. Adicione um novo arquivo Resources (.resw) ao project (deixe o nome padrão).

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

   4. Abra o arquivo de código Program.cs e substitua a Console.WriteLine("Hello, World!"); linha 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 em Iniciar sem depuração (ou Iniciar depuração) para criar e executar seu aplicativo. Você deve ver a cadeia de caracteres Hello, resources! exibida com êxito.

Siga estas instruções para configurar um projeto WinUI em C++ que esteja empacotado com localização externa ou não empacotado.

1. Em Visual Studio, crie um novo aplicativo C++ Console project. Nomear o projeto DynamicDependenciesTest.

   

   Depois de criar o project, você deverá ter um aplicativo de console C++ "Olá, Mundo!".

2. Em seguida, instale o pacote NuGet Windows App SDK em seu project.

   1. Em Solution Explorer, clique com o botão direito do mouse no nó References e escolha Manage Nuget Packages.
   2. Na janela NuGet Package Manager, selecione a guia Browse e pesquise Microsoft.WindowsAppSDK.

3. Agora você está pronto para usar a API bootstrapper (consulte Use o runtime do Windows App SDK para aplicativos empacotados com local externo ou não empacotados) para inicializar o runtime do Windows App SDK no seu aplicativo. Isso permite que você use as APIs de Windows App SDK no aplicativo.

   1. Adicione os seguintes arquivos de inclusão à parte superior do arquivo DynamicDependenciesTest.cpp. O cabeçalho mdbootstrap.h está disponível por meio do pacote NuGet Windows App SDK.

   #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 lidar com quaisquer erros. Esse código define de qual versão do Windows App SDK 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ê possa especificar uma das versões do Windows App SDK instalado.

   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. Por fim, adicione esse código para exibir a cadeia de caracteres Hello, World! e chame a função MddBootstrapShutdown para cancelar a inicialização do bootstrapper.

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

   1. O 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 em Iniciar sem depuração (ou Iniciar depuração) para criar e executar seu aplicativo.