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

  • [アーティクル]

注意

MSIX テクノロジを使用してアプリがインストールされている場合は、「フレームワークに依存するパッケージ 化されたアプリWindows アプリ SDK展開ガイド」を参照してください。

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

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

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

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

バックグラウンドでモジュールの自動初期化をオプトアウトする

上記の WindowsPackageType プロパティによって生成されたコードは、モジュール初期化子を利用してブートストラップ API を呼び出します。 ブートストラップは、Windows アプリ SDKを見つけて、現在のプロセスでそれを使用できるように、重い持ち上げを行います。 生成されたコードは、初期化とシャットダウンの両方を処理します。 次のプロジェクト プロパティを使用して、初期化の動作を制御できます。

  • <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 アプリ SDK ランタイムを取得するようにユーザーに求めるメッセージを表示します。
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • パッケージ ID を持つプロセスで呼び出された場合は成功します (それ以外の場合は失敗し、エラーが返されます)。

アプリが明示的に制御できるようにする場合は、アプリケーションの起動時に boostrapper API を直接呼び出すことができます。 その場合は、プロジェクト ファイルに必要 WindowsPackageType ありません。

注意

自動初期化とブートストラッパー API に加えて、Windows App SDK には "動的依存関係 API" の実装も用意されています。 この API を使用すると、非パッケージ アプリに "任意の" フレームワーク パッケージ (Windows App SDK フレームワーク パッケージだけでなく) への依存関係を持たせることができます。それはブートストラッパー API によって内部的に使用されます。 動的依存関係 API の詳細については、「 動的依存関係 API を使用して実行時に MSIX パッケージを参照する」を参照してください。

モジュールの自動初期化のオプトアウト (または自動初期化)

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

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

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

重要

以下に示す MddBootstrapInitialize2 関数は、バージョン 1.1 以降で使用できます。

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

MddBootstrapInitialize2

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

ブートストラップ API は動的依存関係 API を使用して、Windows アプリ SDK ランタイムのフレームワーク パッケージを現在のプロセスのパッケージ グラフに追加し、それ以外の場合はパッケージへのアクセスを有効にします。

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

MddBootstrapShutdown

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

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

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

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

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

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

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

ブートストラップ C++ API に関するページを参照してください。

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

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

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

maxversiontested 要素の Id 属性を、対象とする Windows のバージョン番号に置き換えます (10.0.17763.0 以降のリリースである必要があります)。 値を大きく設定すると、以前のバージョンの Windows ではアプリが正しく実行されません。これは、すべての Windows リリースで前のバージョンのみが認識されるためです。 そのため、アプリを Windows 10 Version 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>