WinUI での WinApp CLI の使用

このガイドでは、WinUI 3 アプリの開発の一連の内部ループ工程全体で WinApp CLI を使用する方法について説明します。公式テンプレートからプロジェクトを作成し、パッケージ識別情報を使用してビルドおよび起動し、クラッシュをデバッグし、コントロールと 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 実行のサポートを参照してください。

クラッシュをデバッグ

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 run と winapp ui に --on sandbox を追加してください。 詳細については、「 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 が必要です。 .vcxprojを使用してwinapp packをビルド、パッケージ化、署名することもできます。

winapp pack .\MyApp.vcxproj -c Release --arch x64 --cert .\devcert.pfx

パッケージ化オプションについては、「プロジェクトを直接パッケージ化する」を参照してください。 ビルドの前提条件とオプションについては、 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: winapp run で動作する、パッケージ化された C++/WinRT WinUI アプリ (XAML を使用した Visual Studio .vcxproj)

次のステップ

  • 最終更新: