外部に配置されたアプリまたはパッケージ化されていないアプリのためにWindows App SDKランタイムを使用する

MSIX を使用してアプリがインストールされていない場合 (つまり、外部の場所にパッケージ化されているか、パッケージ化されていない場合)、WinUI 3、アプリ ライフサイクル、MRT Core、DWriteCore などのWindows App SDK機能を呼び出すには、使用するWindows App SDKを初期化する必要があります。 アプリは、Windows App SDKの他の機能を使用する前に、Windows App SDK ランタイムを初期化する必要があります。

• Windows App SDK 1.0 以降では、アプリが自動初期化を使用して起動したときに自動的に実行できます (project プロパティを <WindowsPackageType>None</WindowsPackageType> に設定します)。 デモについては、最初の WinUI プロジェクトを作成するを参照してください。
• ただし、高度なニーズがある場合 (独自のカスタム UI やログ記録を表示してエラーを処理する場合や、ビルドしたバージョンとは異なるバージョンのWindows App SDKを読み込む必要がある場合など)、このトピックを読み進めてください。 このようなシナリオでは、自動初期化ではなく、ブートストラップ API を明示的に呼び出すことができます。

上記の 2 つの手法のいずれかを使用すると、MSIX を使用しないアプリは、実行時にWindows App SDKに動的な依存関係を取得できます。

動的依存関係の背景情報については、「 MSIX フレームワーク パッケージと動的依存関係を参照してください。

舞台裏での自動初期化子の解除

前述の WindowsPackageType プロパティによって生成されたコードは、ブートストラップ API を呼び出すために auto-initializers を利用します。 ブートストラッパーは、Windows App SDKを見つけて、現在のプロセスで使用できるようにするために、主要な役割を担います。 生成されたコードは、初期化とシャットダウンの両方を処理します。 初期化の動作は、次のprojectプロパティで制御できます。

• <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
  • 既定のオプションを使用します。
• <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
  • オプションは使用しません。
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • エラーが発生した場合 DebugBreak() を呼び出します。
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
  • デバッガーがプロセスにアタッチされている場合にのみエラーが発生した場合は、 DebugBreak() を呼び出します。
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
  • エラーが発生した場合は、フェールファーストを実行します。
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
  • 一致するランタイムが見つからない場合は、Windows App SDK ランタイムを取得するようにユーザーに求めるメッセージを表示します。
• <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
  • パッケージ ID を持つプロセスで呼び出された場合は成功します (それ以外の場合は失敗し、エラーが返されます)。

アプリで明示的な制御を行う場合は、アプリケーションの起動の早い段階で boostrapper API を直接呼び出すことができます。 その場合、project ファイルに WindowsPackageType は必要ありません。

自動初期化子のオプトアウトまたはオプトイン

project プロパティ <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> は、前述の自動初期化子を無効にします (ブートストラップ API は呼び出されません)。 これにより、アプリが責任を負い、ブートストラップ API を直接呼び出すことができます。

Windows App SDKのバージョン 1.2 (安定したチャネルから) の時点で、自動初期化子は実行可能ファイルを生成するプロジェクトにのみ適用されます (つまり、 OutputType project プロパティは Exe または WinExe) に設定されます。 これは、既定でクラス ライブラリ DLL やその他の非実行可能ファイルに自動初期化子を追加しないようにするためです。 do非実行可能ファイル (ブートストラップを初期化しないホスト プロセス実行可能ファイルによって読み込まれたテスト DLL など) に自動初期化子が必要な場合は、<WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize> を使用してprojectで自動初期化子を明示的に有効にすることができます。

ブートストラップ API の使用

ブートストラップ API は、Windows App SDK内の mddbootstrap.h ヘッダー ファイルで宣言されている 3 つの C/C++ 関数で構成されます: MddBootstrapInitialize, MddBootstrapInitialize2、 MddBootstrapShutdown。 これらの関数は、Windows App SDKのブートストラップ ライブラリによって提供されます。 そのライブラリは、アプリと共に配布する必要がある小さな DLL です。フレームワーク パッケージ自体の一部ではありません。

MddBootstrapInitialize2

この関数は、関数パラメーターに渡す条件に最も一致するWindows App SDK フレームワーク パッケージのバージョンを使用するように呼び出し元プロセスを初期化します。 通常、その結果、インストールされている Windows App SDK NuGet パッケージと一致するフレームワーク パッケージのバージョンが参照されます。 複数のパッケージが条件を満たしている場合は、最適な候補が選択されます。 この関数は、ブートストラップ コンポーネントがWindows App SDKを適切に初期化し、フレームワーク パッケージにランタイム参照を追加できるようにするために、アプリの起動時の最初の呼び出しの 1 つである必要があります。

ブートストラップ API は、Dynamic Dependencies API を使用して、Windows App SDK ランタイムのフレームワーク パッケージを現在のプロセスの package グラフに追加し、それ以外の場合はパッケージへのaccessを有効にします。

動的依存関係有効期間マネージャー (DDLM) もこの関数の初期化の対象となります。 このコンポーネントは、パッケージ化されていないアプリで使用されている間に OS が Windows App SDK フレームワーク パッケージにサービスを提供できないようにするためのインフラストラクチャを提供します。

MddBootstrapShutdown

この関数は、 MddBootstrapInitialize の呼び出しによって行われた現在のプロセスへの変更を削除します。 この関数が呼び出されると、アプリは動的依存関係 API を含め、Windows App SDK API を呼び出すできなくなります。

また、この関数では、必要に応じて、Windows がフレームワーク パッケージにサービスを提供できるように動的依存関係有効期間マネージャー (DDLM) をシャットダウンします。

ブートストラップ API の.NET ラッパー

.NET アプリから直接 C/C++ ブートストラップ API を呼び出すことができますが、platform invoke を使用して関数を呼び出す必要があります。 Windows App SDK 1.0 以降のリリースでは、ブートストラップ API の.NET ラッパーを Microsoft.WindowsAppRuntime.Bootstrap.Net.dll アセンブリで使用できます。 このアセンブリは、.NET開発者がブートストラップの機能をaccessするための、より簡単で自然な API を提供します。 Bootstrap クラスは、最も一般的なシナリオでMddBootstrapInitialize および MddBootstrapShutdown 関数の呼び出しをラップする静的な Initialize、TryInitialize、および Shutdown 関数を提供します。 ブートストラップ API の .NET ラッパーの使用方法を示す例については、「Tutorial: 外部の場所でパッケージ化されたアプリでブートストラップ API を使用するか、Windows App SDK」の C# の手順を参照してください。

ブートストラップ API の.NET ラッパーの詳細については、次のリソースを参照してください。

• ブートストラップ C# API。
• 動的依存関係の仕様のセクション 6.1.4。
• Bootstrap.cs: ブートストラップ API の.NET ラッパーのopen source実装。

ブートストラップ API の C++ ラッパー

ブートストラップ API の C++ ラッパーは、Windows App SDK 1.1 以降で使用できます。

Bootstrapper C++ API を参照してください。

アプリケーション マニフェストで OS の互換性を宣言

オペレーティング システム (OS) の互換性を宣言し、Windows App SDK が既定で Windows 8 の動作をするのを避け、クラッシュの可能性を防ぐためには、外部の場所でのパッケージ化、または非パッケージ型アプリにサイドバイサイドのアプリケーションマニフェストを含めることができます。 「アプリケーション マニフェスト」を参照してください (これは DPI 認識などを宣言するファイルで、ビルド中にアプリの .exe に埋め込まれます)。 これは、Visual Studio project テンプレートを使用して新しいアプリを作成するのではなく、既存のアプリWindows App SDKサポートを追加する場合に問題になる可能性があります。

projectに side-by-side アプリケーション マニフェストがまだない場合は、projectに新しい XML ファイルを追加し、Application マニフェストで推奨される名前を付けます。 互換性要素と次の例に示す子要素をファイルに追加します。 これらの値は、アプリのプロセスで実行されているコンポーネントの風変わりなレベルを制御します。

maxversiontested 要素の Id 属性を、対象とする Windows のバージョン番号に置き換えます (10.0.17763.0 以降のリリースである必要があります)。 値を高く設定すると、以前のバージョンの Windows ではアプリが正しく実行されません。これは、すべての Windows リリースで、その前のバージョンのみが認識されるためです。 アプリを Windows 10 バージョン 1809 (10.0; ビルド 17763) で実行したい場合、10.0.17763.0 の値を変更せずに残すか、あなたのアプリがサポートするさまざまな値に対応するために複数の maxversiontested 要素を追加する必要があります。

<?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>

参照

• Windows App SDKおよびサポートされている Windows リリース
• 外部の場所でパッケージ化された、またはパッケージ化されていないフレームワーク依存アプリ向けのWindows App SDK展開ガイド
• 動的依存関係の仕様
• MSIX フレームワーク パッケージと動的依存関係
• Windows App SDK の Runtime アーキテクチャ
• チュートリアル: 外部の場所でパッケージ化されたアプリまたは Windows App SDK を使用する非パッケージアプリでブートストラップ API を利用する方法