winui-app

WinUI アプリ

WinUI 3 と Windows App SDK の作業で、根拠のあるセットアップガイダンス、アプリのブートストラップ、最新の Windows UX に関する判断、または具体的な実装パターンが必要な場合に、このスキルを使用します。

必須の手順

1. タスクを環境／セットアップ、新規アプリのブートストラップ、設計、実装、レビュー、トラブルシューティングのいずれかに分類します。
2. WinUI 用のマシンの準備、準備状況の監査、または新規アプリの作成に関するタスクでは、より広範な設計、実装、トラブルシューティングに進む前に、このスキルに含まれるセットアップとひな形作成の手順から始めます。
   • 新規アプリを作成する依頼の場合は、アプリ名を決めます。
   • ユーザーが指定した名前が安全なフォルダー名として使える場合は、その名前をそのまま使用します。
   • ユーザーが名前を指定していない場合は、依頼内容から短い PascalCase の名前を導き、選んだ名前を伝えます。
   • 別の場所を指定されていない限り、ユーザーの現在のワークスペースにプロジェクトを作成します。
   • 既存のファイルを上書きするよう明示的に依頼されていない限り、--force は使用しません。
   • 相対パスが厳密に config.yaml のままになるよう、スキルのディレクトリから同梱の WinGet 構成を実行します。

winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity

• この構成は、開発者モードの有効化、Visual Studio Community 2026 のインストールまたは更新、WinUI 開発に必要な Managed Desktop、Universal、Windows App SDK の C# コンポーネントのインストールを目的としています。
• 続行する前に、構成の結果を評価します。成功した場合は続行します。失敗した場合は推測せず、出力を確認します。winui テンプレートがすでに利用可能で、ツールチェーンも使用できる場合は、一部失敗したことを伝えて続行します。前提条件がまだ不足している場合は、作業を中止し、妨げとなっている要因を明確に報告します。
• ひな形を作成する前に、テンプレートが利用可能であることを確認します。

dotnet new list winui

• 診断のみを目的とした環境リクエストについては、バンドルされたブートストラップがマシンを変更する可能性があることを説明し、実行前に確認を得てください。ユーザーが変更を拒否した場合は、references/foundation-environment-audit-and-remediation.md の手動検証ガイダンスを使用し、present、missing、uncertain、recommended optional tools の下で準備状況を要約してください。
• まったく新しいアプリの場合は、dotnet new winui -o <name> でスキャフォールドします。テンプレートオプションは、ユーザーが要求した場合にのみ追加してください。サポートされているオプション: -f|--framework net10.0|net9.0|net8.0、-slnx|--use-slnx、-cpm|--central-pkg-mgmt、-mvvm|--use-mvvm、-imt|--include-mvvm-toolkit、-un|--unpackaged、-nsf|--no-solution-file、--force。サポートされていないフラグを考案しないでください。ユーザーがパッケージ化された動作を求めた場合は、--unpackaged false を渡してください。それ以外の場合はテンプレートのデフォルトを維持してください。
• 新しいスキャフォールドを検証するには、期待されるプロジェクトファイルが存在することを確認し、生成された .csproj に対して dotnet build を実行します。
• 新しくスキャフォールドされたアプリは、その実際のパッケージングモデルに応じた正しいパスで起動し、ランチャープロセスの終了コードだけに頼るのではなく、実際のトップレベルウィンドウが存在することを確認してください。

3. references/_sections.md を読み、タスクに一致する参照ファイルのみを読み込んでください。
4. アプリを作成またはリファクタリングする前に、パッケージングモデルを明確にしてください。Store のような製品ワークフローや Visual Studio のデプロイ/F5 フローでは、デフォルトでパッケージ化を選択します。ユーザーが再現可能な CLI ビルドアンドランループや、変更のたびに直接 .exe を起動することを期待している場合は、デフォルトで非パッケージ化を選択します。
5. タスクが MSB3073 や XamlCompiler.exe のような不透明な XAML コンパイラ失敗である場合は、references/foundation-template-first-recovery.md を読み、独自のリカバリ構造を考案する前に、選択したパッケージングモデル向けの現在の dotnet new winui スキャフォールドへと簡素化してください。
6. WinUI アプリを作成または変更する作業では、完全かつ最小限の編集セットを作成し、ユーザーに応答する前にアプリをビルドして実行してください。ユーザーが明示的に検証を求めなかった場合でも、デフォルトでこれを行ってください。さらに作業が残っている間に実行中のアプリインスタンスが出力をロックしている場合は、それを停止し、再ビルドし、再起動して、検証を続けてください。作業が完了し、起動検証が成功した場合は、ユーザーが明示的にそうしないよう求めない限り、最終的に検証されたアプリインスタンスを実行したままにしてユーザーに引き渡してください。
7. 起動検証は、応答性の高いトップレベルウィンドウ、期待されるウィンドウタイトル、その他の明確な起動動作など、客観的な成功シグナルがアプリに現れるまでは不完全であるものとして扱ってください。プロセスが生成されただけでは十分ではありません。
8. 要件、API の期待事項、プラットフォームガイダンスについては、Microsoft Learn を優先してください。
9. 具体的なコントロールの使用方法、シェル構成、デザインの詳細については、WinUI Gallery を優先してください。
10. ウィンドウイング、ライフサイクル、通知、デプロイ、カスタムコントロールなどのシナリオレベルの API については、WindowsAppSDK-Samples を優先してください。
11. まず WinUI と Fluent のガイダンスに沿って構築してください。ネイティブの WinUI シェル、コントロール、インタラクション、コントロールクロームを、デフォルトの実装パスとして扱ってください。
12. ドキュメントアクション、エディターの書式設定、ビューの切り替え、ページレベルのツールバーなど、グループ化されたコマンドサーフェスについては、Grid、StackPanel、Border、またはその場限りのボタングルーピングでカスタム行を構築する前に、ネイティブの CommandBar またはその他の標準の WinUI コマンドサーフェスを優先してください。
13. ユーザーが明示的にそのカスタマイズを求めていない場合、既存の製品デザインシステムがすでにそれを要求している場合、または検証済みのプラットフォームのギャップによりクリーンなネイティブオプションが存在しない場合を除き、標準の WinUI の動作を置き換えるアプリ固有のコントロール、特注のコンポーネントライブラリ、カスタムクロームを考案しないでください。
14. カスタマイズが必要な場合は、CommunityToolkit の依存関係を追加したり新しいカスタムコントロールを作成したりする前に、まず組み込みの WinUI コントロールとシステムリソースをコンポーズ、テンプレート化、または再スタイル化してください。
15. CommunityToolkit は、組み込みの WinUI コントロールやヘルパーがそのニーズをクリーンにカバーできない場合にのみ使用してください。
16. デフォルトでライトモードとダークモードの両方をサポートしてください。単一テーマの出力は、ユーザーによる明示的な要求または既存の製品上の制約を必要とする例外として扱ってください。
17. UI を構築または改訂する際は、ライト専用またはダーク専用のハードコードされた色ではなく、テーマ対応リソース、システムブラシ、WinUI のスタイリングフックを使用してください。
18. コレクションレイアウトでは、スクロールの所有権を明確にしてください。ページがすでに垂直方向にスクロールする場合、ネストされた GridView やその他のスクロールを所有するコレクションが水平方向のポスター列を正しくレンダリングするとは想定しないでください。
19. セクション、リスト、カードの周囲に余分な Border ラッパーを追加しないでください。ただし、そのボーダーが、含まれるコントロールや親サーフェスがすでに提供しているものとは異なる独自の役割を果たしている場合は除きます。セクションの Border が、すでにカードとしてレンダリングされる子アイテムを包み込む「ダブルカード」構成は避けてください。
20. レスポンシブ対応は、単なるコントロールのリサイズ問題ではなく、シェルとページの問題として扱ってください。ナビゲーション、パディング、コンテンツ密度、フッター/ツール領域について、ワイド、ミディアム、フォン幅の動作を明示的に計画し、幅が縮小するにつれて不要な UI を簡素化または非表示にしてください。

よくあるルート

リクエスト	最初に読む資料
この PC で WinUI アプリをビルドできるか確認する	references/foundation-environment-audit-and-remediation.md
不足している WinUI の前提条件をインストールする	references/foundation-environment-audit-and-remediation.md
新しいパッケージ化アプリまたはパッケージ化されていないアプリを開始する	references/foundation-setup-and-project-selection.md
テンプレートのスキャフォールドを基準に保ちながら、不透明な XAML コンパイラーのエラーや起動エラーから復旧する	references/foundation-template-first-recovery.md
WinUI アプリをビルド、実行する、または実際に起動したことを確認する	references/build-run-and-launch-verification.md
アプリの構造、ページ、リソース、バインディングを確認する	references/foundation-winui-app-structure.md
シェル、ナビゲーション、タイトルバー、複数ウィンドウのパターンを選ぶ	references/shell-navigation-and-windowing.md
コントロールやレスポンシブレイアウトのパターンを選ぶ	references/controls-layout-and-adaptive-ui.md
Mica、テーマ、タイポグラフィ、アイコン、Fluent スタイルを適用する	references/styling-theming-materials-and-icons.md
アクセシビリティ、キーボード操作、ローカライズを改善する	references/accessibility-input-and-localization.md
応答性や UI スレッドのパフォーマンスを診断する	references/performance-diagnostics-and-responsiveness.md
CommunityToolkit を使うべきか判断する	references/community-toolkit-controls-and-helpers.md
ライフサイクル、通知、デプロイに対応する	references/windows-app-sdk-lifecycle-notifications-and-deployment.md
レビューチェックリストを実施する	references/testing-debugging-and-review-checklists.md

環境ルール

• マシンが WinUI 開発に対応できると推測しないでください。検証してください。
• 新規セットアップ、修復、最初のプロジェクトのスキャフォールディングには、別のスキルに委任するのではなく、このスキルに含まれるセットアップとスキャフォールドのフローを使用してください。
• このスキルのディレクトリにある config.yaml を、同梱のブートストラップに関する信頼できる唯一の情報源として扱ってください。
• 不確かな環境の兆候は、不確かなものとして扱い、成功と見なさないでください。
• タスクが監査のみで、ユーザーがマシンへの変更を拒否した場合は、references/foundation-environment-audit-and-remediation.md の手動検証ガイダンスを使用し、成功を示唆せず、不確かな兆候を明示してください。
• config.yaml が見つからない場合は、そのことを明確に伝え、同梱の手順が存在するかのように装うのではなく、Microsoft 公式のワークフローに切り替えてください。
• 環境の準備状況、パッケージ化の選択、アプリの起動検証は、それぞれ別個のチェックとして扱ってください。いずれかに合格しても、ほかのチェックに合格したことにはなりません。
• 起動結果が曖昧な場合は、成功と見なさないでください。アプリが明確に開かなかった場合は、デバッグを続けてください。
• WinUI アプリを作成または編集した後は、ビルドに成功しただけで終わらないでください。アプリを起動して、客観的な起動動作を確認し、ユーザーが実行しないよう明示していない限り、制御をユーザーに戻す前に最終検証済みのアプリインスタンスを起動したままにしてください。

参照ルール

• C# を主要な手段として使用してください。違いが重要な場合に限り、C++ または C++/WinRT に触れてください。
• 汎用的なサンプル構造を無理に適用するのではなく、既存のコードベースの規約を維持してください。
• WinUI のデザインガイダンスとネイティブコントロールを基本としてください。ユーザーが明示的に求めた場合や、既存のコードベースがすでに依存している場合を除き、独自のコンポーネントシステムや標準コントロールのアプリ固有の代替手段に逸れないでください。
• ユーザーが単一テーマの結果を明示的に求めた場合、または製品がすでに単一テーマを適用している場合を除き、アプリの UI 作業ではデフォルトでライトモードとダークモードをサポートしてください。
• CommunityToolkit の依存関係、カスタムコントロール、アプリ固有のサーフェスシステムを追加する前に、組み込みの WinUI コントロールとシステムのスタイリングフックを優先してください。
• コントロール、テーマ、シェル、スクロール、応答性、パッケージ化、復旧に関する詳細なガイダンスは、ここで重複させるのではなく、対応する参照ファイルに記載してください。