WinUI での winapp CLI の使用

このガイドでは、WinUI 3 アプリの完全な内部ループで winapp CLI を使用する方法について説明します。公式テンプレートからプロジェクトを作成し、パッケージ ID を使用してプロジェクトをビルドして起動し、クラッシュをデバッグし、コントロールと API を見つけ、UI を自動化し、署名済みの MSIX パッケージを生成します。 すべてのステップはコマンド ラインから実行されるため、任意のエディター、CI、AI コーディング エージェントで動作します。

WinUI プロジェクト テンプレートには既に Package.appxmanifest が含まれているため、WinUI アプリでは winapp init を実行する必要はありません。 WinUI を使用しない既存の .NET アプリにパッケージ ID を追加する場合は、代わりに「.NET での winapp CLI の使用」を参照してください。

Prerequisites

  • Windows 10 バージョン 1809 以降、または Windows 11。

  • .NET SDK バージョン 8.0.100 以降。 実験用の Reactor テンプレートには、.NET 10 SDK が必要です。 winapp CLI ではツールチェーンがインストールされないため、.NET SDK が見つからない場合は、winapp new と winapp run はガイダンスを表示して停止します。

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • 開発者モード。これは、ビルド出力からアプリを登録するために Windows で必要です。 設定 > システム > デベロッパー向け でそれをオンにします。 コンピューターでのこの変更については、「 セキュリティ」を参照してください。

WinUI アプリを作成する

winapp new は、公式の Microsoft.WindowsAppSDK.WinUI.CSharp.Templates パックから WinUI アプリを生成します。 テンプレート パックがオンデマンドでインストールまたは更新され、その後、自動的に dotnet new が呼び出されます。

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

winapp new --listを実行して、インストールされたパックのテンプレートを確認します。 パックには、次のテンプレートが含まれています。

Template Description
winui 最小限の空の XAML アプリ (既定)。 スクリーンショットを参照してください
winui-navview NavigationView シェルを使用した XAML アプリ。 スクリーンショットを参照
winui-tabview TabView シェルを使用した XAML アプリ。 スクリーンショットを参照してください
winui-mvvm CommunityToolkit.Mvvm で MVVM パターンを使用する XAML アプリ。 スクリーンショットを参照
winui-lib WinUI クラス ライブラリ
winui-unittest WinUI 単体テスト用のパッケージ化された MSTest プロジェクト
reactor、reactor-mvu、reactor-navview、reactor-tabview 実験的。 XAML を使用しない、C# のみで記述された WinUI アプリ

Note

Reactor テンプレートはプレリリース Microsoft.UI.Reactor パッケージを参照します。 それらの API は、将来のリリースで変更または削除される可能性があります。

すべてのオプションについては、 new コマンド リファレンスを参照してください。

ID を使用したビルドと実行

プロジェクト フォルダーから、winapp runプロジェクトをビルドし、アーキテクチャに一致する Windows アプリ SDK ランタイムが存在しない場合はインストールし、アプリをパッケージ ID に登録して起動します。

cd MyApp
winapp run

winapp run は、プロジェクト ファイル、ソリューション ファイル、そのうちの 1 つを含むフォルダー、またはビルド出力のフォルダーを受け取ります。

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

winapp CLI は、プロジェクトの WindowsPackageType プロパティを読み取って、プロジェクトの起動方法を決定します。 パッケージ 化されたプロジェクトは、パッケージ ID で実行されます。 WindowsPackageTypeを None に設定するプロジェクトは、ID を持たないパッケージ化されていないアプリとして実行されます。 パッケージ化されたプロジェクトを非パッケージとして実行するには、コマンド ラインでプロパティを渡します。

winapp run -p WindowsPackageType=None

その他の便利なオプションには、前回の登録とアプリの保存データ（LocalState と設定）を削除して初回実行をまっさらな状態にする --clean、アプリを起動せずに登録する --no-launch、およびプロセス ID を返して終了し、アプリの実行中もスクリプトとエージェントが処理を続けられるようにする --detach --json があります。 完全な一覧については、「Project モード (.NET SDK プロジェクト)」を参照してください。

代わりに dotnet run を使用してください

dotnet run を使用したい場合は、Microsoft.Windows.SDK.BuildTools.WinApp NuGet パッケージを使用します。 パッケージは dotnet run をフックして、winapp run を呼び出し、ID 付きでアプリを起動します。 winapp newで作成したプロジェクトは既にパッケージを参照しているため、dotnet runは追加のセットアップなしで動作します。 他のプロジェクトの場合は、最初にパッケージを追加してください：

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

dotnet run -p:WinAppRunDebugOutput=true オプションを dotnet run -p:WinAppRunDebugOutput=true MSBuild プロパティとして渡すことができます。たとえば WinAppRun* です。 統合を無効にするには、プロジェクト ファイルで EnableWinAppRunSupport を false に設定します。 詳細については、dotnet run のサポートに関するページを参照してください。

クラッシュをデバッグ

OutputDebugStringを追加して、アプリの実行中に--debug-outputメッセージとファースト チャンス例外をキャプチャします。 WinUI アプリが stowed exception で失敗した場合、winapp CLI はクラッシュ ダンプを分析し、一般的な失敗コードではなく、元のエラーと呼び出し履歴を出力します。

winapp run --debug-output

--symbols を追加すると、完全なネイティブ関数名のシンボルをダウンロードします。 --debug-outputはデバッガーとして winapp CLI をアタッチするため、Visual Studioまたは別のデバッガーを同じプロセスにアタッチすることはできません。 代わりに IDE を使用してデバッグするには、「 winapp CLI を使用したデバッグ」を参照してください。 stowed-exception 分析の詳細については、WinUI stowed-exception トリアージを参照してください。

コントロールとAPIを探す

winapp find-uiWinUI ギャラリーと Windows Community Toolkit の XAML と C# のサンプルを目的別に検索し、選択したシナリオのコードを返します。 winapp find-apiは、プロジェクトが参照するWindowsと WinRT API サーフェス (Windows アプリ SDK、Windows SDK の型、メンバー、列挙型など) を検索します。

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

どちらのコマンドも --jsonをサポートしているため、AI コーディング エージェントはそれらを使用してコントロールを選択し、API 名を確認できます。 詳細については、 find-ui および find-api のリファレンスを参照してください。

UI を自動化して確認する

winapp uiは、実行中のアプリをMicrosoft UI オートメーションで制御します。 これを使用して、要素ツリーの検査、コントロールの呼び出し、状態の変更の待機、スクリーンショットの取得を行います。 エージェントは、同じコマンドを使用して自身の変更を確認できます。

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

PART_PaneToggleButton セレクターは、winui-navview テンプレートのメニュー ボタンを対象とします。 独自のコントロールの場合は、 winapp ui inspect または winapp ui searchの出力からセレクターをコピーします。

デスクトップではなく Windows Sandbox でアプリを実行するには、winapp uiと--on sandboxにwinapp runを追加します。 詳細については、「 UI オートメーション と サンドボックスの実行」を参照してください。

パッケージ化して署名する

パッケージをローカルでテストする準備ができたら、発行元がマニフェストと一致する開発証明書を生成し、1 つの手順でプロジェクトをビルドしてパッケージ化します。

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack はプロジェクトをビルドし、署名された .msixを生成します。 複数のアーキテクチャのビルドを 1 つの.msixbundleに結合するには、マルチアーキテクチャ バンドルを参照してください。 プロジェクトはパッケージ化されている必要があるため、WindowsPackageType を None に設定したプロジェクトはパックできません。 WinUI プロジェクトの場合、Windows アプリ SDK ビルドはマニフェスト、エントリ ポイント、およびリソース生成を所有するため、--manifest、--executable、および--skip-priは受け入れられません。

開発証明書はローカル テスト専用であり、既定のパスワードを使用します。 アプリを配布する前に、信頼できる証明書を使用して、たとえば winapp az-sign や Azure の信頼された署名 を使って署名します。 詳細については、「プロジェクトを直接パッケージ化する」と「セキュリティ」を参照してください。

既存の WinUI プロジェクト

winapp CLI は、Visual Studio で作成した WinUI プロジェクトに対応しています。 winapp run をプロジェクト ファイル、ソリューション ファイル、またはそれらのいずれかを含むフォルダーに指定します。 winapp packの場合は、.csprojを指定します。 Visual Studioでビルドとデバッグを続け、スクリプト、CI、エージェントのワークフローに winapp CLI を使用できます。

C++ での WinUI

winapp runまた、Visual Studio の WinUI Blank App (Packaged) テンプレートから作成した C++/WinRT WinUI プロジェクト (.vcxproj) もビルドして起動します。 Visual Studio の MSBuild を使用してプロジェクトをビルドし、アプリにパッケージ ID を付与して登録し、起動します。

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++ プロジェクトには、C++ によるデスクトップ開発 ワークロードと C++ WinUI アプリ開発ツール を備えた Visual Studio または Build Tools for Visual Studio が必要です。 winapp pack は .vcxproj プロジェクトをビルドできないため、Visual Studio で MSIX パッケージを作成します。 前提条件とオプションについては、 C++ プロジェクト (.vcxproj) を参照してください。 WinUI を使用しない C++ アプリについては、「 C++ での winapp CLI の使用」を参照してください。

Samples

  • winui-app: winapp ui オートメーション用に設定されたコントロールを含むパッケージ化された WinUI アプリ
  • winui-unpackaged-app: パッケージ ID なしで実行される WinUI アプリ
  • winui-solution: winapp run がアプリ プロジェクトを選択する方法を示すマルチプロジェクト ソリューション
  • cpp-winui-app: パッケージ化された C++/WinRT WinUI アプリ (XAML で Visual Studio .vcxproj) で、winapp run で実行される

次のステップ

  • 最終更新: