Tutorial: Usar a API bootstrapper em um aplicativo empacotado com localização externa ou não empacotado que usa o SDK do Aplicativo Windows

  • Artigo

Este artigo mostra como configurar um aplicativo que não está instalado usando o MSIX (ou seja, ele é empacotado com local externo ou não empacotado) para usar a API de bootstrapper para que ele carregue explicitamente o runtime SDK do Aplicativo Windows e chame SDK do Aplicativo Windows APIs. Os aplicativos que não são instalados por meio do MSIX incluem aplicativos empacotados com localização externa e aplicativos não empacotados.

Importante

Do SDK do Aplicativo Windows 1.0 em diante, a abordagem padrão para carregar o SDK do Aplicativo Windows de um aplicativo empacotado com localização externa ou não empacotado é usar a inicialização automática por meio da propriedade <WindowsPackageType> do projeto (bem como fazer alterações de configuração adicionais). Para obter as etapas envolvidas na inicialização automática no contexto do projeto WinUI 3, consulte Criar seu primeiro projeto WinUI 3. Ou, se tiver um projeto existente que não seja WinUI 3, confira Usar o SDK do Aplicativo Windows em um projeto existente.

Se você tiver necessidades avançadas (como tratamento de erro personalizado ou carregar uma versão específica do SDK do Aplicativo Windows), poderá chamar explicitamente a API do bootstrapper. E essa é a abordagem que este tópico demonstra. Além disso, para obter mais informações, consulte Usar o runtime SDK do Aplicativo Windows para aplicativos empacotados com local externo ou não empacotados.

Este tópico demonstra explicitamente a chamada da API bootstrapper de um projeto de aplicativo de console básico; mas as etapas se aplicam a qualquer aplicativo de área de trabalho não empacotado que use o SDK do Aplicativo Windows.

Antes de concluir este tutorial, recomendamos que você examine a arquitetura de runtime para saber mais sobre a dependência do pacote framework que seu aplicativo usa quando usa o SDK do Aplicativo Windows e os componentes adicionais necessários para trabalhar em um aplicativo empacotado com local externo ou desempacotado.

Pré-requisitos

  1. Instalar ferramentas para o SDK do Aplicativo Windows.
  2. Verifique se todas as dependências para empacotadas com localização externa e aplicativos não empacotados estão instaladas (consulte SDK do Aplicativo Windows guia de implantação para aplicativos dependentes de estrutura empacotados com local externo ou não empacotados). Uma maneira fácil de fazer isso é executar o SDK do Aplicativo Windows instalador de runtime.

Instruções

Você pode seguir este tutorial usando um projeto C# ou C++.

Observação

As dependências dinâmicas e as APIs de bootstrapper falham quando são chamadas por um processo elevado. Como resultado, o Visual Studio não deve ser iniciado com privilégios elevados. Consulte Dependências dinâmicas não dão suporte à elevação nº 567 para obter mais detalhes.

Siga estas instruções para configurar um projeto winui 3 do C# empacotado com local externo ou não empacotado.

  1. No Visual Studio, crie um novo projeto de Aplicativo de Console C#. 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. Em 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 Moniker de Estrutura de Destino. Por exemplo, use o seguinte se o aplicativo for direcionado Windows 10, versão 2004.
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    1. Salve e feche o arquivo de projeto.

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

    1. Selecione Compilar>Configuration Manager.
    2. Selecione a lista suspensa em Plataforma de solução ativa e clique em Novo para abrir a caixa de diálogo Nova Plataforma de Solução .
    3. Na lista suspensa em Tipo 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 Fechar.

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

    1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências e escolha Gerenciar 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 bootstrapper (consulte Usar o runtime SDK do Aplicativo Windows para aplicativos empacotados com local externo ou não empacotados) para assumir dinamicamente uma dependência do pacote de estrutura SDK do Aplicativo Windows. Isso permite que você use as APIs SDK do Aplicativo 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 método Bootstrap.Initialize para inicializar o bootstrapper. Esse código define 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 à 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 que você instalou.

    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 bootstrapper é uma API C/C++ nativa que permite usar as APIs SDK do Aplicativo Windows em seu aplicativo. Mas em um aplicativo .NET que usa o SDK do Aplicativo Windows 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 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 SDK do Aplicativo Windows runtime foram carregados corretamente, adicione um código que usa a classe ResourceManager no SDK do Aplicativo Windows para carregar um recurso de cadeia de caracteres.

    1. Adicione um novo Arquivo de Recursos (.resw) ao seu projeto (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: Mensagem
      • Valor: Olá, recursos!

    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 compilar e executar seu aplicativo. Você deverá ver a cadeia de caracteres Hello, resources! exibida com êxito.

Se o projeto for WPF

Para um aplicativo WPF (Windows Presentation Foundation), consulte Usar o SDK do Aplicativo Windows em um aplicativo WPF.