winui-dev-workflow

WinApp CLI 0.7 以降が必要です。

プロジェクトを作成または開く

新しいアプリ — WinApp CLI に公式テンプレートをインストールまたは更新させ、スキャフォールディングを実行します：

winapp new --name <AppName> --template winui-mvvm --template-version latest --use-defaults
cd <AppName>

winapp new --list を実行して、現在インストールされているテンプレートの短縮名を確認します。テンプレートパックを個別にインストールしたり、先に出力ディレクトリを作成したりしないでください。

既存のアプリ — .csproj を読み、次の点を確認します：

• <TargetFramework>（例：net10.0-windows10.0.26100.0）
• <PackageReference> のバージョン（WindowsAppSDK、CommunityToolkit）
• プロジェクト構成と確立されているパターン

アプリごとのアナライザーを追加または確認する

各アプリプロジェクトに最新の安定版アナライザーを追加します。テンプレートに含まれていると決めつけないでください：

dotnet add .\MyApp.csproj package Microsoft.Windows.SDK.BuildTools.WinUIAnalyzer

参照には PrivateAssets="all" を設定したままにします。通常の CLI、IDE、CI ビルドで読み込まれます。WinApp CLI がこれを自動で追加することはありません。パッケージを利用できない場合は処理を続行し、潜在的なランタイム問題に関するチェックが実行されなかったことをユーザーに伝えてください。この試行で追加した不完全な参照のみを取り消し、既存の参照を削除したり、その他の復元エラーを隠したりしないでください。

その他のパッケージについては、プロジェクトにバージョンポリシーがある場合や、ユーザーが特定のバージョンを指定した場合を除き、最新の安定版を優先します。API に関する前提に基づいてコーディングする前に、復元済みのアプリを対象に winapp find-api を実行し、--project-dir <app-project-dir> を指定します（ソリューション内では --project <name> を使用します）。winui-design を参照してください。

ビルドと実行（JIT 開発）

winapp run . --detach --json

UI テストについては、実行ターゲットを自動的に選択する winui-ui-testing を参照してください。

通常の winapp run は、-c Release を指定しても、ビルド／JIT パスを使用します。Native AOT は検証しません。プロジェクトの選択が曖昧な場合は、明示的に .csproj を指定してください。オプションについては winapp run --help を参照してください。

ビルドに失敗した場合： すべてのエラーを確認し、一度にまとめて修正してから、同じコマンドを再実行します。

Native AOT の公開実行

AOT デプロイを予定している場合は、アプリプロジェクトで <PublishAot>true</PublishAot> を設定します（開発中の分析も有効になります）。一度だけ試す場合は、-p PublishAot=true を渡します。--aot はビルドではなく公開を実行します。このマシンで実行可能な --arch を選択してください：

winapp run . --aot -c Release --arch <x64|arm64> --detach --json
winapp run . --aot -c Release --arch <x64|arm64> -p PublishAot=true --detach --json

IL／CsWinRT の警告は抑制せず、修正してください。winui-packaging の references/sourcegen-patterns.md を参照してください。

クラッシュの診断

--debug-output を指定してアタッチ実行し、mode: "async" で呼び出してから、同じシェルを読み取ります。WinUI がクラッシュすると、stowed-exception トリアージによって、不透明な 0x8000FFFF／E_FAIL の背後にある実際の XAML エラーが明らかになります。より詳しいネイティブフレームを確認するには、--symbols を追加します。初回のクラッシュ時にはデバッガーコンポーネントがダウンロードされます。オフラインの場合は、既存の Debugging Tools for Windows のインストール先を WINAPP_DBGTOOLS_DIR に設定してください。--debug-output は --json または --no-launch と併用できません。

よくあるエラー

エラー	修正方法
Developer Mode が有効になっていない	Settings → System → For developers → On
CS0234/CS0246 型が見つからない	using を追加するか、dotnet add package を実行します
NETSDK1136 プラットフォームが必要	Windows TFM をターゲットにします（例：net10.0-windows10.0.26100.0）。プロジェクトがすでに複数のターゲットを設定している場合は、-f <windows-tfm> を使用します
XLS0414 XAML 型が見つからない	xmlns 宣言を追加します
XDG0062 バインディングパスが見つからない	ViewModel に x:Bind プロパティが存在することを確認します
バインドされた動的な値が更新されない	継承された x:DefaultBindMode を含め、有効なモードを確認します。必要に応じて OneWay／TwoWay と変更通知を使用します
アプリが何も表示せず終了する	プロジェクトモードの winapp run を使用します。.exe を直接実行してパッケージ化されたアクティベーションを回避しないでください
アプリが不明瞭な 0x8000FFFF／E_FAIL でクラッシュする	クラッシュの診断を参照してください
XAML コンパイラーが何も表示せずクラッシュする	PresentationCore.dll／System.Windows への参照をすべて削除します
MSB3073／XamlCompiler.exe ... exited with code 1 が発生し、.xaml が指定されない	古い WindowsAppSDK の XAML コンパイラーのバグです。Microsoft.WindowsAppSDK NuGet を最新バージョン（≥ 2.1.3、または 1.x 系列では ≥ 1.8）に更新します
0x80073CF6 パッケージのインストールに失敗する	マニフェストの発行元と Developer Mode を確認します。winapp new で作成したアプリに、個別の winapp init は必要ありません
深くネストされたプロジェクトで 0x80073CF9／「Failed to reach state Staged」が発生する	パッケージ化されたアプリの場合、--output-appx-directory "$env:LOCALAPPDATA\winapp-layout\<app>-<config>-<arch>" を指定して再実行するか、リポジトリをドライブのルートに近い場所へ移動します。構成とアーキテクチャごとに別のディレクトリを使用してください。登録済みの開発用パッケージはそのディレクトリへの有効な参照を保持するため、Debug と Release で同じディレクトリを共有してはいけません。また、再利用する前にディレクトリを空にし、前回のビルド後に配置されたペイロードファイルが残らないようにしてください
0x8007000B イメージ形式が正しくない	プラットフォームターゲットが誤っています。AnyCPU ではなく、x64 または ARM64 を使用します

前提条件

要件	このワークフローで必要な条件
Windows	Windows 10 v1903 以降、およびアプリの OS 要件を満たすこと
Developer Mode	開発用デプロイで有効にすること
.NET SDK	最低 8.0.100 に加えて、アプリの TFM に必要な SDK（例：net10.0-windows… には .NET 10）
WinApp CLI	0.7 以降
Native AOT のみ	MSVC C++ ビルドツール（Visual Studio または Build Tools、Desktop development with C++ ワークロード、ターゲットアーキテクチャ用ツール）。通常のビルドには不要です

WinApp CLI が見つからないか、バージョンが 0.7 より古い場合は、確認を求めずに winui-setup を使用してインストールまたはアップグレードし、ユーザーに伝えてください（管理者権限は不要です）。管理者権限が必要なもの（.NET SDK、Developer Mode、または Native AOT ツールチェーン）をインストールする前には、必ず確認してください。回避策を使ってはなりません。

重要なルール

• パッケージ化をデフォルトとして維持し、アクティベーションにはプロジェクトモードの winapp run を使用します。
• 明示的に依頼されたアンパッケージ／デバッグ実験の場合に限り、WindowsPackageType=None を設定します。パッケージ ID に依存する API は失敗する可能性があり、ランタイム要件も引き続き適用されます。これを、ユーザーに知らせずに起動の回避策として使用しないでください。マニフェストを保持し、実験後は元のパッケージ設定に戻します。
• Package.appxmanifest を削除しないでください。
• ❌ AnyCPU は絶対に使用せず、必ず x64 または ARM64 を使用します

参照

• winui-packaging — 開発用の登録を必要とせず、プロジェクトから直接リリースパッケージを作成します。