次の方法で共有


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

Note

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 する必要はありません。

Note

自動初期化とブートストラッパー 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++ 関数 (MddBootstrapInitializeMddBootstrapInitialize2、および MddBootstrapShutdown で構成されます。 これらの関数は、Windows アプリ SDKのブートストラップ ライブラリによって提供されます。 そのライブラリは、アプリと共に配布する必要がある小さな DLL です。フレームワーク パッケージ自体の一部ではありません。

MddBootstrapInitialize2

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

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

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

MddBootstrapShutdown

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

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

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

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

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

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

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

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

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

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

プロジェクトに並列アプリケーション マニフェストがまだない場合は、新しい 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>

参照