Use o runtime do SDK de Aplicações Windows para aplicações empacotadas com localização externa ou não empacotadas

Se a sua aplicação não estiver instalada através do MSIX (ou seja, se for incluída com localização externa ou não empacotada), então deve inicializar o SDK de Aplicações Windows para uso antes de poder chamar funcionalidades do SDK de Aplicações Windows como WinUI 3, App Lifecycle, MRT Core e DWriteCore. A sua aplicação deve inicializar o runtime do SDK de Aplicações Windows antes de usar qualquer outra funcionalidade do SDK de Aplicações Windows.

• A partir da SDK de Aplicações Windows 1.0, isso pode ser feito automaticamente quando a sua aplicação inicia através da inicialização automática (defina a propriedade project <WindowsPackageType>None</WindowsPackageType>). Para uma demonstração, veja Crie o seu primeiro WinUI project.
• Mas se tiver necessidades avançadas (como lidar com erros mostrando a sua própria interface personalizada ou logando, ou se precisar de carregar uma versão do SDK de Aplicações Windows diferente da versão com que construiu), então continue a ler este tópico. Nesses cenários, em vez da inicialização automática, você pode chamar a API de bootstrapper explicitamente.

Qualquer uma das duas técnicas acima permite que uma aplicação que não usa MSIX assuma uma dependência dinâmica do SDK de Aplicações 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 desativação de inicializadores automáticos

O código gerado pela propriedade WindowsPackageType mencionada anteriormente utiliza auto-inicializadores para chamar a API bootstrapper. O bootstrapper faz o trabalho pesado para encontrar o SDK de Aplicações Windows e permitir que o processo atual o utilize. O código gerado lida com a inicialização e o desligamento. Pode controlar o comportamento da inicialização com as seguintes propriedades do 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>
  • Chame DebugBreak() se ocorrer um erro.
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
  • Chame DebugBreak() somente se um erro ocorrer e um depurador estiver anexado 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 ao utilizador que adquira o runtime do SDK de Aplicações Windows caso não seja encontrado um correspondente.
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
  • Se tiver sucesso quando chamado num processo com identidade de pacote (se não, falhará e um erro é emitido).

Se você quiser que seu aplicativo tenha controle explícito, então você pode chamar diretamente a API boostrapper no início da inicialização do seu aplicativo. Nesse caso, não precisas de WindowsPackageType no teu ficheiro de project.

Opção de ativar ou desativar inicializadores automáticos

A propriedade project <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> desativa o inicializador automático descrito acima (a API bootstrapper não é chamada). Isso permite que a sua aplicação assuma a responsabilidade e chame diretamente a API de inicialização.

A partir da versão 1.2 do SDK de Aplicações Windows (do canal stable), os auto-inicializadores aplicam-se apenas a projetos que produzem um executável (ou seja, a propriedade OutputType project está definida para Exe ou WinExe). Isso é para evitar a adição de inicializadores automáticos em DLLs de biblioteca de classes e outros não executáveis por padrão. Se do precisar de um autoinicializador num não-executável (por exemplo, uma DLL de teste carregada por um executável de um processo anfitrião que não inicializa o bootstrapper), pode ativar, de forma explícita, um autoinicializador no seu projeto com <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Usando a API de bootstrapper

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

MddBootstrapInitialize2

Esta função inicializa o processo de chamada para usar a versão do pacote framework do SDK de Aplicações Windows que melhor corresponde aos critérios que passa aos parâmetros da função. Normalmente, isso resulta em referência à versão do pacote framework que corresponde ao pacote NuGet do SDK de Aplicações Windows instalado. Se vários pacotes atenderem aos critérios, o melhor candidato será selecionado. Esta função deve ser uma das primeiras chamadas no arranque da aplicação para garantir que o componente bootstrapper pode inicializar corretamente o SDK de Aplicações Windows e adicionar a referência em tempo de execução ao pacote framework.

A API do bootstrapper utiliza a API das Dependências Dinâmicas para adicionar o pacote do framework do runtime do SDK de Aplicações Windows ao grafo do pacote do processo atual e, de outro modo, ativar o acesso ao pacote.

Esta função também inicializa o Dynamic Dependency Lifetime Manager (DDLM). Esse componente fornece infraestrutura para impedir que o sistema operativo sirva o pacote framework do SDK de Aplicações Windows enquanto este está a ser usado por uma aplicação não empacotada.

MddBootstrapShutdown

Esta função remove as alterações no processo atual que foram feitas por uma chamada para MddBootstrapInitialize. Depois desta função ser chamada, a sua aplicação já não pode chamar APIs do SDK de Aplicações Windows, incluindo a API de dependências dinâmicas.

Essa função também desliga o DDLM (Dynamic Dependency Lifetime Manager) para que o Windows possa atender ao pacote de estrutura conforme necessário.

.NET envoltório para a API bootstrapper

Embora possas chamar a API bootstrapper C/C++ diretamente a partir de .NET aplicações, isso requer o uso de plataforma invoke para chamar as funções. Nas versões do SDK de Aplicações Windows 1.0 e posteriores, um wrapper de .NET para a API bootstrapper está disponível no assembly Microsoft.WindowsAppRuntime.Bootstrap.Net.dll. Este assembly proporciona uma API mais fácil e mais natural para os programadores .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 um exemplo que demonstra como usar o wrapper .NET para a API bootstrapper, veja as instruções C# em Tutorial: Use a API bootstrapper numa aplicação com localização externa ou não empacotada que use o SDK de Aplicações Windows.

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

• Bootstrapper APIs C#.
• Secção 6.1.4 da especificação de dependências dinâmicas.
• Bootstrap.cs: A implementação open source do wrapper .NET para a API bootstrapper.

Wrapper C++ para a API de bootstrapper

Um wrapper C++ para a API bootstrapper está disponível a partir do SDK de Aplicações Windows 1.1.

Consulte API C++ do Bootstrapper.

Declarar a compatibilidade do SO no manifesto da aplicação

Para declarar compatibilidade com o sistema operacional (SO) e evitar que o SDK de Aplicações Windows recai para o comportamento padrão do Windows 8 (e potenciais falhas), pode incluir um manifesto de aplicação lado a lado com a sua aplicação embalada localizada externamente ou aplicação desembalada. Consulte Manifestos do aplicativo (é o arquivo que declara coisas como reconhecimento de DPI e é incorporado ao seu aplicativo .exe durante a compilação). Isto pode ser um problema se estiver a adicionar suporte SDK de Aplicações Windows a uma aplicação existente, em vez de criar uma nova através de um modelo Visual Studio project.

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

Substitua o atributo Id do elemento maxversiontested pelo número da 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 sabem apenas das versões anteriores a ele. Portanto, se quiser que a sua aplicação corra no Windows 10, versão 1809 (10.0; Build 17763), então deve ou manter o valor 10.0.17763.0 como está, ou adicionar múltiplos elementos maxversiontested para os diferentes valores que a sua aplicação suporta.

<?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>

Ver também

• SDK de Aplicações Windows e versões suportadas para Windows
• Guia de Implementação do SDK de Aplicações Windows para Apps Dependentes de Framework, Empacotadas com Localização Externa ou Não Empacotadas
• Especificação de dependências dinâmicas
• Pacotes de estrutura MSIX e dependências dinâmicas
• Arquitetura de runtime para o SDK de Aplicações Windows
• Tutorial: Use a API bootstrapper numa aplicação com localização externa ou não empacotada que use o SDK de Aplicações Windows