プロジェクトのプロパティと自動初期化子

このトピックでは、自動初期化子の構成など、アプリの展開方法をカスタマイズするために、Visual Studio project ファイル (.csproj や .vcxproj など) で設定できるprojectプロパティについて説明します。

Windows アプリ SDK のオートイニシャライザ

Windows アプリ SDKには、Windows アプリ ランタイムが適切に初期化されるようにジョブを実行するルーチンがいくつかあります。 これらのルーチンは、アプリケーションのエントリ ポイントの前に自動的に実行され、初期化作業を行うため、自動初期化子と呼ばれます。

ヒント

技術的な詳細に興味がある場合。 C++ では、自動初期化子は静的クラス コンストラクターを使用して実装されます。 C# では、自動初期化子は .NET モジュール初期化子を使用して実装されます。 そのため、適切な用語が自動初期化子である場合にモジュール初期化子が使用されることがあります。

すべての自動初期化子は、アプリのパッケージ化とデプロイの構成に基づいて、既定で条件付きで有効になります。 これらの詳細を次に示します。

  • ブートストラッパー (動的依存関係とも呼ばれます) の自動初期化機能。 この自動初期化子は、アプリの起動時にブートストラップ API を自動的に呼び出します。 Windows アプリ ランタイムがアプリのパッケージ グラフに確実に追加されるようにするには、フレームワークに依存するパッケージ化されていないアプリに必要です。 フレームワークに依存する (自己完結型) アプリの詳細については、「Windows アプリ SDK 展開の概要を参照してください。 パッケージ化されていない（およびパッケージ化されている）アプリの詳細については、Windows アプリのパッケージング、展開、および処理に関するページを参照してください。
    • パッケージ アプリの場合、 appxmanifest.xml ファイルはフレームワークの依存関係を表しているため、ブートストラップ/動的依存関係の自動初期化子は必要ありません。 また、自己完結型アプリの場合、ブートストラップ/動的依存関係の自動初期化子は必要ありません。これらのアプリではフレームワークが使用されないためです。
    • .csprojを使用して、.vcxprojまたは<WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> ファイル内のブートストラップ/動的依存関係の自動初期化子をオプトアウトできます。
  • デプロイメントマネージャーのオートイニシャライザー。 これは、メイン/シングルトン機能 (プッシュ通知など) を利用するフレームワーク依存のパッケージ アプリでは、 appxmanifest.xml ファイルでそれらの依存関係を表現できないために必要です。
    • 自己完結型アプリの場合、これらのアプリはメイン/シングルトン機能をサポートしていないため、Deployment Manager 自動初期化子は必要ありません。
    • 詳細については、このトピックで後述する 「Deployment Manager 自動初期化子 」セクションを参照してください。
  • 登録不要のアクティブ化自動初期化子。 これは、アプリが 2019 年 5 月の更新プログラム (バージョン 1903、コード名は "19H1") より Windows 10前のバージョンのオペレーティング システムでダウンレベルで実行されている場合に、自己完結型アプリがマニフェスト ベースのドッキングされていない登録フリー Windows ランタイム (WinRT) のアクティブ化 (UndockedRegFreeWinRT) を使用するために必要です。
    • フレームワークに依存するアプリや、Windows 10バージョン 1903 以降を対象とする自己完結型アプリの場合、登録不要のアクティブ化自動初期化子は必要ありません。 これらのアプリは、 <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>経由でオプトアウトできます。
  • 互換性の自動初期化子。 これは、アプリが A/B コンテインメント機能を使用してサービス リリースの動作を制御するために必要です。 詳細については、「 RuntimeCompatibilityOptions」を参照してください。
    • A/B 包含を使用しないアプリ (既定) の場合、互換性自動初期化子は必要ありません。

デプロイメントマネージャー自動初期化機能

Windows アプリ SDK 1.8 以降を使用するアプリが起動すると、Deployment Manager の自動初期化子は既定で実行されます。 ただし、その発生をオプトアウトできます。 このセクションでは、Deployment Manager 自動初期化子の実行を許可する利点と注意事項について説明し、オプトアウトするかどうかを決定するのに役立ちます。

アプリで Main/Singleton パッケージ (プッシュ通知など) の機能を利用するには、1. Deployment API を使用して、それらのパッケージが確実にデプロイされるようにする必要があります (Main/Singleton パッケージはフレームワークではなく、アプリなどの "メイン" パッケージであるため、アプリの appx マニフェストに依存関係として登録できません。代わりに、Deployment API には、これらのパッケージをデプロイする機能が用意されています)。 2. 1 のため、アプリは DeploymentManager.Initialize を呼び出すことによって、Deployment Manager を初期化する必要があります。 ご利用のアプリでは、表示されるとおり、自動的に、または明示的に実行できます。 3. メイン/シングルトン パッケージに依存するように、アプリはフレームワークに依存するパッケージ 化されたアプリである必要があります。

Deployment Manager を初期化する方法の 1 つとして、自動初期化機能を持つ Deployment Manager の実行を許可することがあります(このトピックの「Windows アプリ SDK における自動初期化」のセクションを参照してください)。 Deployment Manager 自動初期化子は DeploymentManager.Initialize を呼び出します。 Deployment Manager を初期化するもう 1 つの方法は、 DeploymentManager.Initialize を明示的に呼び出す方法です。

(Windows アプリ SDK 1.8 以降を使用する) アプリで Main/Singleton パッケージが必要ない場合は、アプリのproject ファイルで WindowsAppSdkDeploymentManagerInitialize プロパティを false に設定して、Deployment Manager の自動初期化子を無効にする必要があります。

アプリ (Windows アプリ SDK 1.8 以降を使用) が Main/Singleton パッケージを必要とする場合は、次のいずれかを実行できます。

  • Deployment Manager 自動初期化子の実行を許可します (既定では実行されます)。
  • または、アプリのproject ファイルで WindowsAppSdkDeploymentManagerInitialize プロパティを false に設定して、Deployment Manager の自動初期化子をオプトアウトします。 その後、 DeploymentManager.Initialize を明示的に呼び出す必要があります。

Important

AppContainer で実行されているプロセスで DeploymentManager.Initialize を呼び出す場合は、アプリでpackageManagementで制限された機能を宣言する必要があります。

プロジェクトのプロパティ

次の表に、アプリのproject ファイルで設定できるプロパティを示します。 Windows アプリ SDKの自動初期化子の詳細については、前のセクション (上記) を参照してください。

プロパティ名と説明 価値観 詳細については、次のページを参照してください。
AppxPackage。 WinUI アプリをパッケージ化するかどうかを指定します。 false (パッケージ化されていないアプリの場合)、または存在しない (パッケージアプリの場合) WinUI アプリのパッケージ化を解除する
EnableMsixTooling。 単一プロジェクト用のMSIX機能をプロジェクトに対して有効にします。 true (有効にする場合)、または存在しない (無効にする場合) 単一プロジェクトMSIXを使用してアプリをパッケージ化します
UseCrtSDKReferenceStaticWarning。 C++ パッケージ アプリが CRT を静的にリンクしたときに発生するビルド警告を抑制します (ハイブリッド CRT を使用した自己完結型展開に必要)。 ハイブリッド CRT をオプトインするパッケージ アプリ プロジェクトで false に設定します。 false (パッケージ化された自己完結型アプリの警告を抑制する場合)、または存在しない (既定値、警告が有効) Windows アプリ SDK自己完結型アプリの展開ガイド
UseWinUI。 アプリで WinUI ユーザー インターフェイス フレームワークを使用するかどうかを指定します。 true、または absent ( false の場合) Windows アプリ SDK（WinUI）のWinUI
WindowsAppSDKSingleFileVerifyConfiguration。 PublishSingleFileが設定されているときに SDK がビルド時検証ターゲットを実行するかどうかを制御します。 有効 (既定値) の場合、ターゲットは、必要なプロパティが不足している場合は エラー (EnableMsixTooling、 WindowsPackageType=None、 IncludeAllContentForSelfExtract) を出力し、自己完結型の設定がない場合は 警告 (WindowsAppSDKSelfContained、 SelfContained) を出力します。 コンプライアンスを手動で検証した CI パイプラインなど、すべてのチェックを抑制する場合にのみ false に設定します。 true (既定値 — 検証の実行)、 false (すべてのチェックを抑制) Microsoft.WindowsAppSDK.SingleFile.targetsで定義されます (PublishSingleFileが設定されると、NuGet パッケージによって自動的に含まれます)
WindowsAppSdkBootstrapInitialize。 Windows アプリ SDKがブートストラップ/動的依存関係自動初期化子を利用するかどうかを決定します。 true (実行可能ファイルの既定値)、 false (非実行可能ファイルの既定値) 自動初期化子の使用をオプトアウト（またはオプトイン）
WindowsAppSdkDeploymentManagerInitialize。 Windows アプリ SDKが Deployment Manager 自動初期化子を利用するかどうかを決定します。 true (既定値)、 false
WindowsAppSDKRuntimePatchLevel1、WindowsAppSDKRuntimePatchLevel2およびWindowsAppSDKDisabledChanges。 Windows アプリ SDKが互換性自動初期化子を利用するかどうかを判断し、サービス更新プログラムに追加された変更のWindows アプリランタイム動作に必要な互換性オプションを構成します。 さまざま、または無効 (自動初期化を無効にするため) RuntimeCompatibilityOptions
WindowsAppSDKSelfContained。 アプリが 自己完結型にデプロイされているかどうかを判断します。 true、または absent ( false の場合) Windows アプリ SDK自己完結型アプリの展開ガイド
WindowsAppSdkUndockedRegFreeWinRTInitialize。 Windows アプリ SDKが登録不要のアクティブ化自動初期化子を利用するかどうかを決定します。 true (実行可能ファイルの既定値)、 false (非実行可能ファイルの既定値) UndockedRegFreeWinRT の自動サポートをオプトアウトまたはオプトインする
WindowsPackageType。 パッケージ化されていないアプリの<WindowsPackageType>None</WindowsPackageType>を設定すると、ブートストラップ/動的依存関係の自動初期化子は、アプリに最適なバージョンのWindows アプリ SDKを見つけて読み込みます。 なし、または存在しない (自動初期化子を無効にする場合) WinUI アプリのパッケージ化を解除する

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

Example

C# WinUI 3 projectの一般的な.csproj ファイルからの抜粋を次に示します。上の表のprojectプロパティの一部が使用されています。

...
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>
...
  • 最終更新: