Usar o runtime do SDK do Aplicativo Windows para aplicativos empacotados com localização externa ou não empacotado

Observação

Se o aplicativo estiver instalado usando a tecnologia MSIX, consulte guia de implantação do SDK do Aplicativo Windows para aplicativos empacotados dependentes de framework.

Se o seu aplicativo não estiver instalado usando o MSIX (ou seja, se estiver empacotado com uma localização externa ou não empacotado), você deve inicializar o SDK do Aplicativo Windows para uso antes de poder chamar recursos do SDK do Aplicativo Windows, como WinUI 3, Ciclo de Vida do Aplicativo, MRT Core e DWriteCore. Seu aplicativo deve inicializar o runtime do SDK do Aplicativo Windows antes de usar qualquer outro recurso do SDK do Aplicativo Windows.

  • A partir do SDK do Aplicativo Windows 1.0, isso pode ser feito automaticamente quando seu aplicativo é iniciado por meio da inicialização automática (defina a propriedade project <WindowsPackageType>None</WindowsPackageType>). Para uma demonstração, veja Criar seu primeiro projeto WinUI.
  • Mas se você tiver necessidades avançadas (como lidar com erros mostrando sua própria interface do usuário personalizada ou log ou se precisar carregar uma versão do SDK do Aplicativo Windows diferente da versão com a qual você criou), continue lendo este tópico. Nesses cenários, em vez da inicialização automática, você pode chamar a API bootstrapper explicitamente.

Qualquer uma das duas técnicas acima permite que um aplicativo que não usa o MSIX use uma dependência dinâmica no SDK do Aplicativo Windows em tempo de execução.

Para obter informações básicas sobre dependências dinâmicas, consulte Pacotes de estrutura MSIX e dependências dinâmicas.

Nos bastidores e optando por não usar inicializadores automáticos

O código gerado pela propriedade WindowsPackageType mencionada acima aproveita auto-initializers para chamar a API bootstrapper. O bootstrapper faz o trabalho pesado para encontrar o SDK do Aplicativo Windows e habilitar o processo atual para usá-lo. O código gerado lida com a inicialização e o desligamento. Você pode controlar o modo como a inicialização se comporta com as seguintes propriedades de projeto:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Use as opções padrão.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Não use opções.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Chame DebugBreak() se ocorrer um erro somente se um depurador estiver ligado ao processo.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Execute um fail-fast se ocorrer um erro.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Solicite que o usuário adquira o runtime do SDK do Aplicativo Windows caso não haja um disponível.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Terá êxito se chamado em um processo com o identificador do pacote (caso contrário, ele falhará e um erro será retornado).

Se você quiser que seu aplicativo tenha controle explícito, poderá chamar diretamente a API boostrapper no início da inicialização do aplicativo. Nesse caso, você não precisa do WindowsPackageType no seu arquivo de projeto.

Observação

Além da inicialização automática e da API bootstrapper, o SDK do Aplicativo Windows também fornece uma implementação da API de dependência dinâmica. Essa API permite que seus aplicativos não empacotados tenham uma dependência de qualquer pacote de estrutura (não apenas no pacote de estrutura do SDK do Aplicativo Windows) e é usada internamente pela API do bootstrapper. Para obter mais informações sobre a API de dependência dinâmica, consulte Usar a API de dependência dinâmica para fazer referência a pacotes MSIX em tempo de execução.

Optar por desativar (ou ativar) os inicializadores automáticos

A propriedade project <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> desabilita o inicializador automático descrito acima (a API bootstrapper não é chamada). Isso permite que seu aplicativo assuma a responsabilidade e chame diretamente a API bootstrapper.

A partir da versão 1.2 do SDK do Aplicativo Windows (do canal estável), os inicializadores automáticos se aplicam somente a projetos que produzem um executável (ou seja, A propriedade OutputType project está definida como Exe ou WinExe). Isso é para impedir a adição de inicializadores automáticos em DLLs de biblioteca de classes e outros não executáveis por padrão. Se você precisar de um inicializador automático em um ambiente não executável (por exemplo, uma DLL de teste carregada por um executável de processo host que não inicializa o bootstrapper), poderá habilitar explicitamente um auto-inicializador no seu projeto com <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Usando a API bootstrapper

Importante

A função MddBootstrapInitialize2 mencionada abaixo está disponível a partir da versão 1.1.

A API bootstrapper consiste em três funções C/C++ declaradas no arquivo de cabeçalho mdbootstrap.h no SDK do Aplicativo Windows: MddBootstrapInitializeMddBootstrapInitialize2 e MddBootstrapShutdown. Essas funções são fornecidas pela biblioteca bootstrapper no SDK do Aplicativo Windows. Essa biblioteca é uma pequena DLL que você deve distribuir com seu aplicativo; não faz parte do pacote de estrutura em si.

MddBootstrapInitialize2

Essa função inicializa o processo de chamada para usar a versão do pacote da estrutura SDK do Aplicativo Windows que melhor corresponde aos critérios que você passa para os parâmetros de função. Normalmente, isso resulta em referenciar a versão do pacote de estrutura que corresponde ao pacote NuGet SDK do Aplicativo Windows instalado. Se vários pacotes atenderem aos critérios, o melhor candidato será selecionado. Essa função deve ser uma das primeiras chamadas na inicialização do aplicativo para garantir que o componente bootstrapper inicialize corretamente o SDK do Aplicativo Windows e adicione a referência em tempo de execução ao pacote de estrutura.

A API bootstrapper usa a API de dependências dinâmicas para adicionar o pacote de framework do runtime do SDK do Aplicativo Windows ao grafo de pacotes do processo atual e habilitar o acesso ao pacote.

Essa função também inicializa o DDLM (Gerenciador de Tempo de Vida de Dependência Dinâmica). Esse componente fornece infraestrutura para impedir que o sistema operacional atue o pacote de estrutura SDK do Aplicativo Windows enquanto ele está sendo usado por um aplicativo não empacotado.

MddBootstrapShutdown

Essa função remove as alterações no processo atual que foram feitas por uma chamada para MddBootstrapInitialize. Depois que essa função for chamada, seu aplicativo não poderá mais chamar APIs SDK do Aplicativo Windows, incluindo a API de dependências dinâmicas.

Essa função também desliga o DDLM (Gerenciador de Tempo de Vida de Dependência Dinâmica) para que o Windows possa atender ao pacote de estrutura conforme necessário.

Wrapper .NET para a API bootstrapper

Embora você possa chamar diretamente a API bootstrapper de C/C++ de aplicativos .NET, isso requer o uso de invocação de plataforma para chamar as funções. Em versões SDK do Aplicativo Windows 1.0 e posteriores, um wrapper .NET para a API bootstrapper está disponível no assembly Microsoft.WindowsAppRuntime.Bootstrap.Net.dll. Esse assembly fornece uma API mais fácil e natural para desenvolvedores .NET acessarem a funcionalidade do bootstrapper. A classe Bootstrap fornece funções estáticas Initialize, TryInitialize e Shutdown que encapsulam chamadas para as funções MddBootstrapInitialize e MddBootstrapShutdown para os cenários mais comuns. Para obter um exemplo que demonstra como utilizar o wrapper .NET para a API bootstrapper, veja as instruções de C# no Tutorial: Usar a API bootstrapper em um aplicativo empacotado com localização externa ou não empacotado que utiliza o SDK do Aplicativo Windows.

Para obter mais informações sobre o wrapper de .NET para a API bootstrapper, consulte estes recursos:

Wrapper C++ para a API bootstrapper

Um wrapper C++ para a API bootstrapper está disponível a partir do SDK do Aplicativo Windows 1.1.

Consulte API do Bootstrapper C++.

Declarar compatibilidade do sistema operacional no manifesto do aplicativo

Para declarar a compatibilidade do sistema operacional (SO) e evitar que o SDK do Aplicativo Windows adote o comportamento padrão do Windows 8 (o que pode resultar em falhas), você pode incluir um manifesto de aplicativo lado a lado com seu aplicativo empacotado em local externo ou não empacotado. Confira Manifestos de Aplicativo (é o arquivo que declara aspectos como o reconhecimento de DPI e que é incorporado ao seu aplicativo .exe durante a construção). Isso pode ser um problema se você estiver adicionando SDK do Aplicativo Windows suporte a um aplicativo existente, em vez de criar um novo por meio de um modelo Visual Studio project.

Se você ainda não tiver um manifesto de aplicativo lado a lado em seu projeto, adicione um novo arquivo XML ao seu projeto e nomeie-o como recomendado nos manifestos de Aplicativos. Adicione ao arquivo o elemento de compatibilidade e os elementos filho mostrados no exemplo a seguir. Esses valores controlam o nível de peculiaridades dos componentes em execução no processo do aplicativo.

Substitua o atributo Id do elemento maxversiontested pelo número de versão do Windows que você está direcionando (deve ser 10.0.17763.0 ou uma versão posterior). Observe que definir um valor mais alto significa que as versões mais antigas do Windows não executarão seu aplicativo corretamente porque todas as versões do Windows conhecem apenas as versões anteriores. Portanto, se você quiser que seu aplicativo seja executado no Windows 10, versão 1809 (10.0; Build 17763), você deve deixar o valor 10.0.17763.0 como está ou adicionar vários elementos maxversiontested para os diferentes valores compatíveis com seu aplicativo.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

Confira também

  • Last updated on