Usar a API de dependência dinâmica para referenciar pacotes MSIX em tempo de execução

  • Artigo

As duas implementações

Existem duas implementações da API de dependência dinâmica que você pode escolher, dependendo da plataforma e do cenário de destino:

  • A API de dependência dinâmica do Windows App SDK. O Windows App SDK fornece funções C e C++ (em msixdynamicdependency.h) e tipos Windows Runtime (WinRT) (no namespace Microsoft.Windows.ApplicationModel.DynamicDependency) que implementam a API de dependência dinâmica. Você pode usar esta implementação da API em qualquer versão do Windows que suporte o SDK de aplicativo do Windows.
  • API de dependência dinâmica do Windows 11. O Windows 11 também tem funções C e C++ que implementam a API de dependência dinâmica (em appmodel.h). Essa implementação da API pode ser usada apenas por aplicativos destinados ao Windows 11, versão 22H2 (10.0; Build 22621) e posterior.

Veja também Diferenças entre as duas implementações.

Observação

Como você verá neste tópico, as APIs do SDK do Aplicativo do Windows (C/C++) têm os mesmos nomes que as APIs do Windows 11 (C/C++) com um prefixo Mdd adicional. Mdd significa dependências dinâmicas da Microsoft.

E existem diferentes tipos de pacotes MSIX, incluindo pacotes framework, resource, opcional e main. A API de dependência dinâmica permite que aplicativos não empacotados referenciem e usem pacotes de estrutura como o WinUI 2 e o DirectX Runtime. Para saber mais sobre as dependências do pacote de estrutura, confira Pacotes de estrutura MSIX e dependências dinâmicas.

Especificamente, a API de dependência dinâmica oferece maneiras de gerenciar as referências em tempo de instalação e as referências em tempo de execução de pacotes MSIX. Para obter mais informações, confira Modelo de manutenção para pacotes de estrutura.

Usar a API de dependência dinâmica

Para usar a API de dependência dinâmica em seu aplicativo não empacotado para obter uma dependência de um pacote MSIX, siga este padrão geral em seu código:

1. Criar uma referência em tempo de instalação

No instalador do aplicativo ou durante a primeira execução do aplicativo, chame uma das funções ou dos métodos a seguir para especificar um conjunto de critérios para o pacote MSIX que você deseja usar. Isso informa ao SO (sistema operacional) que o aplicativo tem uma dependência de um pacote MSIX que atende aos critérios especificados. Se um ou mais pacotes MSIX que atendem aos critérios estiverem instalados, o Windows garantirá que pelo menos um deles permaneça instalado até que a referência em tempo de instalação seja excluída.

Os critérios especificados incluem o nome da família do pacote, versão mínima e arquiteturas; mas você não pode indicar um pacote MSIX específico. Quando você adiciona uma referência em tempo de execução ao pacote MSIX, a API escolhe a versão mais alta que atende aos critérios especificados.

Você também precisa especificar um artefato de tempo de vida, que pode ser o processo atual, um arquivo ou uma chave do Registro do Windows que indica ao sistema que o aplicativo ainda está disponível. Se o artefato especificado não existir mais, o sistema operacional poderá assumir que a dependência não é mais necessária e desinstalar o pacote MSIX se nenhum outro aplicativo tiver declarado uma dependência dele. Esse recurso é útil para cenários em que um aplicativo não pode remover o marcador de tempo de instalação quando ele é desinstalado.

Essa API retorna uma ID de dependência que precisa ser usada em outras chamadas para criar referências em tempo de execução e excluir a referência em tempo de instalação.

2. Adicionar uma referência em tempo de execução

Quando seu aplicativo precisar usar o pacote MSIX, chame uma das funções ou métodos a seguir para solicitar acesso ao pacote MSIX especificado e adicionar uma referência de tempo execução a ele. A chamada a essa API informa ao sistema operacional que o pacote MSIX está em uso ativo e para lidar com as atualizações de versão lado a lado (atrasando efetivamente a desinstalação ou, de outra forma, mantendo a versão mais antiga até que o aplicativo tenha terminado de usá-la). Se for bem-sucedido, o aplicativo poderá ativar classes e usar o conteúdo do pacote MSIX.

Ao chamar essa API, você deve passar a ID de dependência que foi retornada quando você criou a referência em tempo de instalação e a classificação desejada a ser usada para o pacote MSIX no grafo de pacote do processo. Essa API retorna o nome completo do pacote MSIX que foi referenciado e um identificador que é usado para controlar a dependência de uso ativo. Se houver vários pacotes MSIX instalados que atendam aos critérios que você especificou ao criar a referência em tempo de instalação, a API escolherá a versão mais alta que atender aos critérios.

3. Remover a referência em tempo de execução

Quando o aplicativo terminar de usar o pacote MSIX, chame uma das funções ou métodos a seguir para remover a referência de tempo execução. Normalmente, seu aplicativo chamará essa API durante o desligamento. Essa API informa ao sistema operacional que é seguro remover todas as versões desnecessárias do pacote MSIX.

Ao chamar essa API, você deve passar o identificador que foi retornado quando você adicionou a referência em tempo de execução.

4. Excluir a referência em tempo de instalação

Quando seu aplicativo for desinstalado, chame uma das funções ou dos métodos a seguir durante a exclusão da referência em tempo de instalação. Essa API informa ao sistema operacional que é seguro remover o pacote MSIX se nenhum outro aplicativo tiver nenhuma dependência dele.

Ao chamar essa API, você precisa passar a ID de dependência que foi retornada quando você criou a referência em tempo de instalação.

Diferenças entre as duas implementações

A necessidade de um gerenciador vitalício (limitação do Windows App SDK)

Quando você usa a API de dependência dinâmica do Windows App SDK para obter uma dependência de um pacote MSIX, a API requer ajuda por meio de outro pacote instalado e processo em execução para informar ao Windows que o pacote MSIX está em uso e para bloquear a manutenção da estrutura enquanto estiver sendo usado. Esse componente é chamado de gerenciador vitalício.

Para o pacote de estrutura dele, o SDK do Aplicativo do Windows fornece um componente de gerenciador de tempo de vida chamado DDLM (Dynamic Dependency Lifetime Manager). No entanto, nenhum outro pacote de estrutura atualmente fornece um componente de gerenciador de tempo de vida semelhante ao da Microsoft.

A API de dependência dinâmica do Windows 11 não tem essa limitação.

Referencie e use um pacote principal (limitação do Windows App SDK)

Uma dependência dinâmica sempre pode ter como alvo um pacote framework. Mas apenas a API de dependência dinâmica do Windows 11 também pode fazer referência e usar pacotes principais.

O pacote principal precisa ter configurado corretamente o arquivo de origem do manifesto do pacote do aplicativo (o arquivo Package.appxmanifest no Visual Studio). Especificamente, o pacote principal (o alvo, não o chamador) precisa definir <uap15:DependencyTarget>true</> (confira uap15:DependencyTarget). Portanto, o objetivo de <uap15::DependencyTarget> é permitir que uma dependência dinâmica tenha como alvo um pacote principal. Em outras palavras, o pacote principal precisa optar por permitir que ele próprio seja usado como uma dependência dinâmica (enquanto os pacotes da estrutura sempre permitem isso implicitamente).

Faça referência ao pacote de estrutura do Windows App SDK (limitação do Windows App SDK)

Em um aplicativo desempacotado, você não pode usar a API de dependência dinâmica do SDK do Windows App para fazer referência ao pacote de estrutura do SDK do Windows App (da mesma forma que você pode referenciar outros pacotes MSIX com ele). Em vez disso, você precisa usar a API bootstrapper fornecida pelo Windows App SDK. A API do bootstrapper é uma forma especializada da API de dependência dinâmica projetada para assumir dependências do pacote de estrutura do SDK do Aplicativo do Windows. Para obter mais informações, confira Usar o runtime SDK do Aplicativo do Windows para aplicativos empacotados com localização externa ou não empacotados.

A API de dependência dinâmica do Windows 11 não tem essa limitação.