Compartilhar via

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 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 a chamada explícita da API bootstrapper de um projeto básico de aplicativo de console; mas as etapas se aplicam a qualquer aplicativo da área de trabalho não empacotado que usa 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 de pacote do Framework que seu aplicativo assume quando usa o SDK do Aplicativo Windows e os componentes adicionais necessários para trabalhar em um pacote com local externo ou aplicativo não empacotado.

Pré-requisitos

  1. Instalar ferramentas para o SDK do Aplicativo Windows.
  2. Verifique se todas as dependências para empacotado com local externo 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 instalador de runtime SDK do Aplicativo Windows.

Instruções

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

Observação

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

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

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

  2. Em seguida, configure seu novo projeto.

    1. No Gerenciador de Soluções, clique com o botão direito do mouse no 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 seu aplicativo visar o 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 WinUI 3 não oferece suporte a essa plataforma.

    1. Selecione Gerencie>Gerenciador de Configuração.
    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 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. No Gerenciador de Configurações, clique em Fechar.

  4. Instale o pacote NuGet do SDK do Aplicativo Windows no projeto.

    1. No 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 do SDK do Aplicativo Windows no 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 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 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 que você use 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 do .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 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 wrapper do .NET para a API bootstrapper.

  6. Para demonstrar que os componentes de runtime do SDK do Aplicativo Windows foram carregados corretamente, adicione um código que use a classe ResourceManager no SDK do Aplicativo Windows para carregar o 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: 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.

Se o seu projeto for WPF

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