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

Artigo
07/05/2024

Observação

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

Se o aplicativo não estiver instalado usando o MSIX (ou seja, ele for empacotado com local externo ou não empacotado), você deverá inicializar o SDK do Aplicativo Windows para uso antes de chamar SDK do Aplicativo Windows recursos como WinUI 3, Ciclo de Vida do Aplicativo, MRT Core e DWriteCore. Seu aplicativo deve inicializar o runtime 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 o aplicativo é iniciado por meio da inicialização automática (defina a propriedade <WindowsPackageType>None</WindowsPackageType>do projeto). Para obter uma demonstração, consulte Criar seu primeiro projeto WinUI 3.
Mas se você tiver necessidades avançadas (como lidar com erros mostrando sua própria interface do usuário personalizada ou registro em 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 assuma uma dependência dinâmica do 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 desativação da inicialização automática do módulo

O código gerado pela WindowsPackageType propriedade mencionada acima aproveita os inicializadores de módulo para chamar a API bootstrapper. O bootstrapper faz o trabalho pesado para localizar 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 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() se ocorrer um erro somente se 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 que o usuário adquira o runtime SDK do Aplicativo Windows se um correspondente não puder ser encontrado.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
- Succceed 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 WindowsPackageType em 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 assumam uma dependência de qualquer pacote de estrutura (não apenas do SDK do Aplicativo Windows pacote de estrutura) e é usada internamente pela API 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.

Desativar (ou ativar) a inicialização automática do módulo

A propriedade <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> do projeto desabilita a inicialização automática do módulo descrita 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), a inicialização automática do módulo se aplica somente a projetos que produzem um executável (ou seja, a propriedade do projeto OutputType é definida como 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 você precisar de um inicializador automático em um não executável (por exemplo, uma DLL de teste carregada por um executável de processo de host que não inicializa o bootstrapper), poderá habilitar explicitamente um inicializador automático em 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++ que são declaradas no arquivo de cabeçalho mddbootstrap.h no SDK do Aplicativo Windows: MddBootstrapInitialize, MddBootstrapInitialize2 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 SDK do Aplicativo Windows pacote de estrutura que melhor corresponde aos critérios que você passa para os parâmetros de função. Normalmente, isso resulta na referência à 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 possa inicializar corretamente o SDK do Aplicativo Windows e adicionar a referência de tempo de execução ao pacote de estrutura.

A API bootstrapper usa a API de Dependências Dinâmicas para adicionar o pacote de estrutura do SDK do Aplicativo Windows ao grafo de pacote do processo atual e, caso contrário, 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 atenda ao 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 SDK do Aplicativo Windows APIs, 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 do .NET para a API bootstrapper

Embora você possa chamar a API de bootstrapper C/C++ diretamente de aplicativos .NET, isso requer o uso de invocação de plataforma para chamar as funções. No SDK do Aplicativo Windows 1.0 e versões posteriores, um wrapper do .NET para a API bootstrapper está disponível no Microsoft.WindowsAppRuntime.Bootstrap.Net.dll assembly. Esse assembly fornece uma API mais fácil e natural para os desenvolvedores do .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 usar o wrapper do .NET para a API bootstrapper, consulte as instruções em C# no Tutorial: Usar a API bootstrapper em um aplicativo empacotado com local externo ou não empacotado que usa o SDK do Aplicativo Windows.

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

APIs C# do Bootstrapper.
Seção 6.1.4 da especificação de dependências dinâmicas.
Bootstrap.cs: a implementação de software livre do wrapper do .NET para a API bootstrapper.

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 seja padronizado para o comportamento do Windows 8 (e possíveis falhas), você pode incluir um manifesto de aplicativo lado a lado com seu aplicativo empacotado com local externo ou não empacotado. Confira Manifestos do aplicativo (é o arquivo que faz declarações como reconhecimento de DPI e que está inserido no seu aplicativo .exe durante o build). 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 de projeto do Visual Studio.

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 conforme recomendado em Manifestos de aplicativo. 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), deixe o valor 10.0.17763.0 como está ou adicione vários elementos maxversiontested para os diferentes valores compatíveis com o 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>

Compartilhar via