Use a API de dependência dinâmica para fazer referência a pacotes MSIX em tempo de execução

As duas implementações

Há 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 SDK do Windows. O SDK do Aplicativo Windows fornece funções C e C++ (em msixdynamicdependency.h) e tipos do Tempo de Execução do Windows (WinRT) (no namespace Microsoft.Windows.ApplicationModel.DynamicDependency ) que implementam a API de dependência dinâmica. Pode utilizar esta implementação da API em qualquer versão do Windows que suporte o SDK de Aplicações Windows.
API de dependência dinâmica do Windows 11. O Windows 11 também fornece 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 posteriores.

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

Observação

Como você verá neste tópico, as APIs do Windows App SDK (C/C++) têm os mesmos nomes que as APIs do Windows 11 (C/C++) com um prefixo Mdd adicional. Mdd significa Microsoft Dynamic Dependencies.

E há diferentes tipos de pacotes MSIX, incluindo de estrutura, de recursos, opcionaise pacotes de principais. A API de dependência dinâmica permite que aplicativos não empacotados façam referência e usem estrutura pacotes como WinUI 2 e o DirectX Runtime. Para obter mais informações sobre dependências de pacotes de estrutura, consulte pacotes de estrutura MSIX e dependências dinâmicas.

Especificamente, a API de dependência dinâmica fornece maneiras de gerenciar as referências de tempo de instalação e de tempo de execução para pacotes MSIX. Para mais informações, consulte 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 assumir uma dependência em um pacote MSIX, siga este padrão geral em seu código:

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

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

Windows 11 (C/C++): TentaCriarDependenciaDePacote
SDK de Aplicativos Windows (C/C++): MddTryCreatePackageDependency
SDK de Aplicativo Windows (WinRT): PackageDependency.Create

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

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

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

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

Quando seu aplicativo precisar usar o pacote MSIX, chame uma das seguintes funções ou métodos para solicitar acesso ao pacote MSIX especificado e adicione uma referência de tempo de execução para ele. Chamar esta API informa o sistema operativo que o pacote MSIX está em uso ativo e para lidar com quaisquer atualizações de versão de forma paralela (efetivamente a adiar a desinstalação ou a prestar manutenção na versão mais antiga até que a aplicação termine de a utilizar). Se for bem-sucedido, o aplicativo poderá ativar classes e usar conteúdo do pacote MSIX.

Windows 11 (C/C++): AddPackageDependency
SDK do Aplicativo Windows (C/C++): MddAddPackageDependency
SDK de Aplicativo Windows (WinRT): PackageDependency.Add

Ao chamar essa API, você deve passar a ID de dependência que foi retornada quando você criou a referência de tempo de instalação e a classificação desejada a ser usada para o pacote MSIX no gráfico 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 especificados quando você criou a referência de tempo de instalação, a API escolhe a versão mais alta que satisfaz os critérios.

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

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

Windows 11 (C/C++): RemovePackageDependency
SDK de Aplicativo Windows (C/C++): MddRemovePackageDependency
SDK de Aplicativo Windows (WinRT): PackageDependencyContext.Remove

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

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

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

Windows 11 (C/C++): DeletePackageDependency
SDK de Aplicações Windows (C/C++): MddDeletePackageDependency
SDK de Aplicativo Windows (WinRT): PackageDependency.Delete

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

Diferenças entre as duas implementações

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

Quando você usa a API de dependência dinâmica do SDK de Aplicativo Windows para assumir uma dependência em 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 ela está sendo usada. Esse componente é chamado de gestor de ciclo de vida .

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

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

Referenciar e usar um pacote principal (limitação do SDK de Aplicativo Windows)

Uma dependência dinâmica sempre pode ter como alvo uma estrutura pacote. Apenas a API de dependência dinâmica do Windows 11 pode fazer referência e usar também os pacotes principais e.

O pacote principal deve ter configurado corretamente seu arquivo de origem de manifesto do pacote do aplicativo (o Package.appxmanifest arquivo no Visual Studio). Especificamente, o pacote principal (o destino, não o chamador) precisa ser definido <uap15:DependencyTarget>true</> (consulte uap15:DependencyTarget). Portanto, o objetivo é <uap15::DependencyTarget> permitir que uma dependência dinâmica tenha como alvo um pacote principal . Por outras palavras, o pacote principal tem de optar por se permitir ser utilizado como uma dependência dinâmica (enquanto os pacotes-quadro permitem sempre implicitamente isso).

Fazer referência ao pacote de estrutura do SDK de Aplicativo Windows (limitação do SDK de Aplicativo Windows)

Em um aplicativo não empacotado, você não pode usar a API de dependência dinâmica do SDK de Aplicativo do Windows para fazer referência ao de estrutura do SDK de Aplicativo Windows (como você pode fazer referência a outros pacotes MSIX com ele). Em vez disso, você precisa usar a API de bootstrapper fornecida pelo SDK do Aplicativo Windows. A API de bootstrapper é uma forma especializada da API de dependência dinâmica projetada para assumir dependências no pacote de estrutura do SDK de Aplicativo Windows. Para mais informações, consulte sobre o uso do tempo de execução do Windows App SDK para aplicativos empacotados com local externo ou não empacotados.