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

  • Artigo

Observação

Se o aplicativo estiver 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 é empacotado com local externo ou não empacotado), você deve 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 ou registro em log personalizado 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 de inicialização automática, você pode chamar explicitamente a API de bootstrapper.

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 em segundo plano sobre dependências dinâmicas, consulte Pacotes de estrutura MSIX e dependências dinâmicas.

Nos bastidores e recusando a inicialização automática do módulo

O código gerado pela WindowsPackageType propriedade mencionada acima utiliza inicializadores de módulo para chamar a API de 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 manipula 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 nenhuma opção.
  • <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 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 não for possível encontrar um correspondente.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Succceed se chamado em um processo com a identidade do pacote (caso contrário, ele falha e um erro é retornado).

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

Observação

Além da inicialização automática e da API de 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 em qualquer pacote de estrutura (não apenas no pacote de estrutura SDK do Aplicativo Windows) e ela é usada internamente pela API de bootstrapper. Para obter mais informações sobre a API de dependência dinâmica, consulte Usar a API de dependência dinâmica para referenciar pacotes MSIX em tempo de execução.

Recusando a inicialização automática do módulo (ou em)

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 do 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 de projeto OutputType é 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 não executável (por exemplo, uma DLL de teste carregada por um executável de processo de host que não inicialize o bootstrapper), você 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++ 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; ele 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 de estrutura SDK do Aplicativo Windows 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 SDK do Aplicativo Windows pacote NuGet 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 em tempo de execução ao pacote de estrutura.

A API de bootstrapper usa a API de Dependências Dinâmicas para adicionar o pacote de estrutura do runtime de SDK do Aplicativo Windows ao grafo de pacote do processo atual e, de outra forma, habilitar o acesso ao pacote.

Essa função também inicializa o DDLM (Dynamic Dependency Lifetime Manager). Esse componente fornece infraestrutura para impedir que o sistema operacional atente 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 é chamada, seu aplicativo não pode mais chamar APIs SDK do Aplicativo 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 da estrutura conforme necessário.

Wrapper do .NET para a API de bootstrapper

Embora você possa chamar a API de bootstrapper C/C++ diretamente de aplicativos .NET, isso requer o uso da 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 de 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 cenários mais comuns. Para obter um exemplo que demonstra como usar o wrapper do .NET para a API de bootstrapper, consulte as instruções em C# no Tutorial: Usar a API de 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 de bootstrapper, consulte estes recursos:

Wrapper C++ para a API bootstrapper

Um wrapper C++ para a API de 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 padrão Windows 8 comportamento (e possíveis falhas), você pode incluir um manifesto de aplicativo lado a lado com seu empacotado com local externo ou aplicativo 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 projeto e nomeie-o como recomendado nos manifestos do aplicativo. Adicione ao arquivo o elemento de compatibilidade e os elementos filho mostrados no exemplo a seguir. Esses valores controlam o nível de peculiaridade 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 só sabem das 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>