動的依存関係 API を使用して、実行時に MSIX パッケージを参照する

  • [アーティクル]

2 つの実装

選択できる動的依存関係 API には、ターゲット プラットフォームとシナリオに応じて、次の 2 つの実装があります。

  • Windows App SDK の動的依存関係 API。 Windows App SDK には、動的依存関係 API を実装する C と C++ の関数 (msixdynamicdependency.h 内)、Windows ランタイム (WinRT) 型 (Microsoft.Windows.ApplicationModel.DynamicDependency 名前空間内) が用意されています。 この API の実装は、Windows App SDK をサポートする任意のバージョンの Windows で使用できます。
  • Windows 11 の動的依存関係 API。 Windows 11 には、動的依存関係 API を実装する C と C++ の関数も用意されています (appmodel.h 内)。 この API の実装は、Windows 11 バージョン 22H2 (10.0; ビルド 22621) 以降を対象とするアプリで使用できます。

2 つの実装の相違点も参照してください。

注意

このトピックで後ほど説明するように、Windows App SDK (C/C++) の API の名前は、Windows 11 (C/C++) の API と同じ名前に Mdd プレフィックスが追加されたものです。 Mdd は、Microsoft Dynamic Dependencies (Microsoft 動的依存関係) の頭文字です。

フレームワーク、リソース、オプション、メインの各パッケージを含め、各種の MSIX パッケージがあります。 "動的依存関係 API" を使用すると、パッケージ化されていないアプリで、WinUI 2 や DirectX ランタイムなどのフレームワーク パッケージを参照して使用できるようになります。 フレームワーク パッケージの依存関係の詳細については、「MSIX フレームワーク パッケージと動的依存関係」を参照してください。

具体的には、動的依存関係 API を使用すると、MSIX パッケージの "インストール時参照" と "実行時参照" を管理できます。 詳細については、「フレームワーク パッケージのサービス モデル」を参照してください。

動的依存関係 API を使用する

パッケージ化されていないアプリで動的依存関係 API を使用して MSIX パッケージへの依存関係を取得するには、コード内で次の一般的なパターンに従います。

1. インストール時参照を作成する

アプリのインストーラーで、またはアプリの最初の実行中に、次の関数またはメソッドのいずれかを呼び出して、使用する MSIX パッケージの条件のセットを指定します。 これにより、指定された条件を満たす MSIX パッケージにアプリが依存していることがオペレーティング システム (OS) に通知されます。 条件を満たす 1 つ以上の MSIX パッケージがインストールされている場合、Windows では、インストール時参照が削除されるまで、それらの少なくとも 1 つはインストールされたままになることが保証されます。

指定する条件には、パッケージ ファミリ名、最小バージョン、アーキテクチャが含まれますが、特定の MSIX パッケージを指定することはできません。 実行時参照を MSIX パッケージに追加すると、API により、指定された条件を満たす最上位バージョンが選択されます。

また、"有効期間成果物" を指定する必要があります。これには、現在のプロセス、ファイル、またはアプリがまだ利用可能であることをシステムに示す Windows レジストリ キーを指定できます。 指定した成果物が存在しなくなった場合、OS では依存関係が不要になったと見なされます。さらに、他のアプリが依存関係を宣言していない場合、MSIX パッケージは OS によってアンインストールすることができます。 この機能は、アプリで、アンインストール時にインストール時の PIN の削除を怠るシナリオで役立ちます。

この API によって返される依存関係 ID を、実行時参照を作成したり、インストール時参照を削除したりするための他の呼び出しで、使用する必要があります。

2. 実行時参照を追加する

アプリで MSIX パッケージを使用する必要がある場合、次の関数またはメソッドのいずれかを呼び出して、指定された MSIX パッケージへのアクセスを要求し、その実行時参照を追加します。 この API を呼び出すと、MSIX パッケージがアクティブに使用されていることと、バージョンの更新を並列で処理することが OS に通知されます (アプリでの使用が完了するまで、古いバージョンのアンインストールまたはサービスを効果的に遅らせます)。 成功した場合、アプリによってクラスがアクティブ化され、MSIX パッケージのコンテンツが使用される可能性があります。

この API を呼び出す場合、インストール時参照を作成したときに返された依存関係 ID と、プロセスのパッケージ グラフで MSIX パッケージに使用したいランクを渡す必要があります。 この API により、参照された MSIX パッケージの完全な名前と、アクティブに使用される依存関係を追跡するために使用されるハンドルが返されます。 インストール時参照の作成時に指定した条件を満たす複数の MSIX パッケージがインストールされている場合、API により、条件を満たす最も高いバージョンが選択されます。

3. 実行時参照を削除する

アプリで MSIX パッケージの使用が完了したら、次の関数またはメソッドのいずれかを呼び出して、実行時参照を削除します。 通常、シャットダウン時にアプリでこの API を呼び出します。 この API により、 MSIX パッケージの不要なバージョンを削除しても安全であることが OS に通知されます。

この API を呼び出す場合、実行時参照を追加したときに返されたハンドルを渡す必要があります。

4. インストール時参照を削除する

アプリがアンインストールされるときに、次の関数またはメソッドのいずれかを呼び出して、インストール時参照を削除します。 他のアプリに依存関係がない場合、この API により、MSIX パッケージを削除しても安全であることが OS に通知されます。

この API を呼び出す場合、インストール時参照を作成したときに返された依存関係 ID を渡す必要があります。

2 つの実装の相違点

有効期間マネージャーの必要性 (Windows App SDK の制限)

Windows App SDK の動的依存関係 API を使用して MSIX パッケージへの依存関係を取得する場合、API では、MSIX パッケージが使用中であることを Windows に通知し、使用中のフレームワークのサービスをブロックするために、別のインストール済みパッケージと実行中のプロセスによる支援が必要です。 このコンポーネントは、有効期間マネージャーと呼ばれます。

フレームワーク パッケージの場合は、Windows App SDK により動的依存関係有効期間マネージャー (DDLM) と呼ばれる有効期間マネージャー コンポーネントが提供されます。 ただし、現在、他のフレームワーク パッケージでは、Microsoft と同様の有効期間マネージャー コンポーネントは提供されていません。

Windows 11 の動的依存関係 API には、この制限はありません。

メイン パッケージを参照して使用する (Windows App SDK の制限)

動的依存関係は、常にフレームワーク パッケージをターゲットにすることができます。 ただし、メイン パッケージも参照して使用できるのは、Windows 11 の動的依存関係 API のみです。

メイン パッケージで、そのアプリ パッケージ マニフェスト ソース ファイル (Visual Studio の Package.appxmanifest ファイル) を正しく構成する必要があります。 具体的には、メイン パッケージ (呼び出し元ではなくターゲット) を設定 <uap15:DependencyTarget>true</> する必要があります (uap15:DependencyTarget を参照)。 そのため、<uap15::DependencyTarget> の目的は動的依存関係を有効にしてメイン パッケージをターゲットにすることです。 言い換えると、メイン パッケージは、動的な依存関係としてそれ自体を使用できるようにオプトインする必要があります (一方、フレームワーク パッケージでは常に暗黙的に許可されます)。

Windows App SDK フレームワーク パッケージを参照する (Windows App SDK の制限)

パッケージ化されていないアプリでは、Windows App SDK の動的依存関係 API を使用して Windows App SDK フレームワーク パッケージを参照することはできません (他の MSIX パッケージは参照できます)。 代わりに、Windows App SDK に用意されている bootstrapper API を使用する必要があります。 ブートストラップ API は API の特殊な形式であり、Windows App SDK フレームワーク パッケージへの依存関係を取得するように設計されています。 詳細については、「外部の場所でパッケージ化されているか、パッケージ化されていないアプリの Windows App SDK ランタイムを使用する」を参照してください。

Windows 11 の動的依存関係 API には、この制限はありません。