CLI のドキュメントと使用方法

シェルの完了

コマンド、オプション、および値のタブ補完を有効にします。 セットアップ手順については、 シェル補完ガイド を参照してください。

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

初期化

Windows SDK、Windows アプリ SDK、および最新の Windows 開発に必要な資産を使用してディレクトリを初期化します。

winapp init [base-directory] [options]

引数:

• base-directory - アプリ/ワークスペースのベース/ルート ディレクトリ (既定値: 現在のディレクトリ)

オプション:

• --config-dir <path> - 読み取り/保存の構成を格納するディレクトリ (既定: 選択したプロジェクト ディレクトリ、またはプロジェクトが検出されない場合は現在のディレクトリ)
• --setup-sdks - SDK インストール モード: 'stable' (既定値)、'preview'、'experimental'、または 'none' (SDK のインストールをスキップ)
• --ignore-config、 --no-config - バージョン管理に構成ファイルを使用しない
• --no-gitignore - .gitignore ファイルを更新しない
• --use-defaults、 --no-prompt - プロンプトを表示せず、すべてのプロンプトの既定値を使用します
• --config-only - 構成ファイル操作のみを処理し、パッケージのインストールをスキップする
• --exe <path> - アプリケーション実行可能ファイルへのパス。 --sparse が必要です。 完全なパッケージ/SDK セットアップではなく、exe の ID 専用スパース マニフェストを生成します。
• --sparse - 既存のデスクトップ exe のスパース ID マニフェスト (appxmanifest.xml) を生成します。 SDK/パッケージのインストールをスキップします。 --exe で使用します。
• --name <name> - パッケージ名をオーバーライドします (スパースのみ。既定値: exe から推論されます)
• --publisher <CN> - パブリッシャー CN をオーバーライドします (スパースのみ。既定値: exe の会社名から推論されます)
• --output-dir <path> - スパース マニフェストと Assets/ を書き込むディレクトリ (スパースのみ、既定: 現在のディレクトリ内の sparse/ フォルダー)
• --force - ターゲット ディレクトリ内の既存の appxmanifest.xml を上書きします (スパースのみ)。 これを指定しないと、既存のマニフェスト/資産を置き換える代わりに init が失敗します。
• --add-js-bindings (npm のみ) - package.json に winapp.jsBindings を追加し、プロンプトを表示せずに JS/TypeScript バインドを生成します ( --setup-sdks noneと互換性がありません)

実行内容:

• 構成ファイル winapp.yaml 作成します (SDK パッケージが管理されている場合のみ、 --setup-sdks noneでスキップされます)
• Windows SDK とWindows アプリ SDK パッケージをダウンロードする
• C++/WinRT ヘッダーとバイナリを生成します
• Package.appxmanifest を作成します
• ビルド ツールを設定し、開発者モードを有効にする
• 生成されたファイルを除外するように .gitignore を更新します
• 共有可能なファイルをグローバル キャッシュ ディレクトリに格納します
• 有効な場合にWindows アプリ SDK API の JS バインドを生成します (npm のみ)

プロジェクトの自動検出:

initがディレクトリ引数なしで実行されると、現在のディレクトリ ツリーの幅優先検索を実行して、互換性のあるプロジェクト (最大 10 個) を検索します。 サポートされているプロジェクトの種類:

• Tauri — ディレクトリの 1 レベル下に見つかったtauri.conf.json
• Electron — 依存関係または devDependencies のpackage.jsonを持つelectron
• Flutter — プロジェクト ルートでのpubspec.yaml
• .NET — プロジェクト ルートでの.csproj
• Rust — プロジェクト ルートでCargo.toml
• C++ — プロジェクト ルートでのCMakeLists.txt

この検索では、一般的に無視されるディレクトリ (node_modules、bin、obj、.git など) がスキップされます。 互換性のあるプロジェクトが見つかった場合、その下のサブディレクトリは検索されません。

• ディレクトリ引数が指定されている場合 (winapp init .やwinapp init path/to/projectなど)、検索はスキップされ、互換性のあるプロジェクトのディレクトリのみがチェックinit
• --use-defaults (または--no-prompt) がディレクトリ引数なしで設定されている場合、initは検索をスキップし、現在のディレクトリを対話形式で初期化します。既知のプロジェクトの種類が検出されない場合は、最初に警告が表示されます (例: winapp init --use-defaults)
• 非対話型環境 (パイプされた stdin、CI、リダイレクトされた入力) では、init--use-defaults動作が自動的に使用され、警告が出力されます。Non-interactive environment detected. Using default values.
• 現在のディレクトリが互換性のあるプロジェクトの場合、 init はすぐに続行されます
• 1 つのプロジェクトが他の場所で見つかった場合は、確認を求められます
• 複数のプロジェクトが見つかった場合は、初期化するプロジェクトを選択できます。現在のディレクトリは常にフォールバック オプションとして使用できます
• プロジェクトが見つからない場合は、警告が表示され、続行するかどうかを確認するメッセージが表示されます。
• 検索が 10 プロジェクトの制限に達した場合は、ディレクトリ引数を指定するよう警告が表示されます

自動.NET プロジェクト フロー:

ターゲット ディレクトリに .csproj ファイルが見つかった場合、init は合理化された.NET固有のフローを使用します。

• TargetFrameworkを検証し、Windows互換 TFM (例: net10.0-windows10.0.26100.0) に更新します。
• Microsoft.WindowsAppSDKとMicrosoft.Windows.SDK.BuildToolsを NuGet PackageReference エントリとして直接追加します。.csproj
• Package.appxmanifest、資産、開発証明書を生成します
• を作成したり、C++ プロジェクションをダウンロードwinapp.yaml (NuGet パッケージにdotnet restoreを使用)

スパース ID モード (--exe + --sparse):

既存のデスクトップ実行可能ファイルの ID 専用 スパース パッケージ マニフェストを生成します。 スパース パッケージ ワークフローの最初の手順です。 完全な init フローとは異なり、これにより すべての SDK/パッケージのインストールがスキップ され (スパース ID パッケージには SDK の依存関係がありません)、マニフェストとプレースホルダーのアセットのみが生成されます。

• FileVersionInfo (--name、--publisher、または対話形式でオーバーライド) を使用して、exe からパッケージ名、発行元、説明、バージョンを推論します。
• appxmanifest.xml (exe 名が Executable に置き換えられます) に加えて、Assets/ フォルダーを現在のディレクトリ (または--output-dir) のsparse/ フォルダーに書き込みます
• --use-defaults / --no-promptを使用して対話型のオーバーライド プロンプトをスキップする (CI フレンドリ)
• --exe --sparseを使用しない場合はエラーです

アセットは外部です。 スパース .msixは ID 専用です。生成されたAssets/は、実行時にアプリのインストール ディレクトリ (外部コンテンツの場所) から解決され、.msixにバンドルされません。 それらをアプリケーションと共にデプロイします。

winapp init --exe <exe> --sparse後の次の手順: ID .msixをビルドしてからwinapp embed-identity <exe>winapp pack <appxmanifest.xml>。 完全なチュートリアルについては、 スパース パッケージ ガイド を参照してください。

例:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

ヒント: 初期セットアップ後に SDK をインストールする

init (またはスキップされた SDK インストール) で--setup-sdks noneを実行し、後で SDK が必要な場合:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

プレビュー/試験段階の SDK バージョンには、 --setup-sdks preview または --setup-sdks experimental を使用します。

---

新規

公式のWindows アプリ SDK dotnet new テンプレートから新しい WinUI アプリを作成します。 既定では対話型。では、非対話型環境で既定値が自動的に使用されます。

winapp new [options]

オプション:

• -t, --template <short-name> - テンプレートの短い名前 (例: winui、 winui-navview、 winui-mvvm、 winui-lib、 winui-unittest、または reactor や reactor-mvuなどの実験用リアクタ テンプレート)。 実行時にインストールされたパックに対して検証されます。 winapp new --list を実行してすべてを表示します。 既定値: winui (空の XAML アプリ)。
• -n, --name <name> - 新しいアプリ/プロジェクトの名前 (既定値: --outputから派生し、それ以外の WinUIApp)
• -o, --output <path> - アプリを作成するディレクトリ (既定値: ./<name>)
• --use-defaults、 --no-prompt - プロンプトを表示しません。既定値 (空白のテンプレート、 --output/--nameからの名前、および更新ではなく、インストールされているテンプレート パックを保持する) を使用します。
• --force - 出力ディレクトリに既にファイルが含まれている場合でもスキャフォールディング
• --template-version <latest|installed|version> - WinUI テンプレート パックのバージョン: latest は、最新の公開済みパックをインストール installed 、既にダウンロードされているもの (ネットワークなし) を保持するか、 1.2.3などの明示的なバージョンをピン留めします。 既定値: 最新のパックが存在しない場合はインストールします。それ以外の場合は、古いパックを更新するように求められます ( --use-defaultsの下に as-is。
• --list - 使用可能な WinUI テンプレートを一覧表示して終了します (インストールされていない場合は、最初に最新のパックをインストールします)
• --json - 出力を JSON として書式設定する

テンプレート：

このパックには、WinUI アプリの 2 つのスタイルが付属しています。 XAML テンプレートは、C# コード ビハインドを使用してマークアップ内の UI を定義します。 リアクター テンプレートは、MVU (Model-View-Update) パターンを使用して XAML を使用しない純粋な C# です。 テンプレート リストはインストールされているパックからライブで読み取られるので、常に使用しているバージョンが反映されます。 winapp new --list 実行して現在のセットを表示します。 一般的なテンプレート:

短い名前	説明
winui	最小限の空の XAML アプリ (MSIX パッケージ)
winui-navview	XAML NavigationView スターター アプリ
winui-tabview	XAML TabView スターター アプリ
winui-mvvm	XAML MVVM アプリ (CommunityToolkit.Mvvm)
winui-lib	WinUI 3 クラス ライブラリ
winui-unittest	パッケージ化された MSTest アプリ。テストは起動時に実行されます
reactor	実験的。 空の Reactor アプリ - 純粋な C#、XAML なし
reactor-mvu	実験的。 MVU パターンを示すリアクタ アプリ
reactor-navview	実験的。 Reactor NavigationView スターター アプリ
reactor-tabview	実験的。 Reactor TabView スターター アプリ

リアクタ テンプレートは試験段階です。 これらはプレリリース Microsoft.UI.Reactor パッケージを参照します。このパッケージの API は、将来のリリースで変更または削除される可能性があります。 winapp new --listと対話型ピッカーで (試験段階) マークを付け、--jsonに"Experimental": trueを設定し、スキャフォールディング後に警告を出力します。 既定のテンプレートとして選択されることはありません。 また、Reactor には .NET 10 SDK 以降が必要です。古い SDK winapp newでは、ビルドできないプロジェクトをスキャフォールディングするのではなく、必要なバージョンで前もって失敗します。

各テンプレートの正規の短い名前は、そのテンプレートの最初のエイリアス dotnet new リストです。一覧表示されているエイリアス ( winui3、 wasdk-single、 winui-reactor など) も受け入れられます。 既存の WinUI プロジェクト内で実行すると、dotnet new項目テンプレート (空白のページなど) も表示され、新しいテンプレートを作成するのではなく、現在のプロジェクトに追加winapp new。

テンプレート パックのバージョン管理:

winapp new は、特定のテンプレート パックバージョンをピン留めしなくなりました。 パックがインストールされていない場合は、 最新のパックがインストールされます。 古いパックが既にインストールされている場合、フィードがチェックされ、新しいパックが存在する場合は、非対話型/--use-defaults実行を除き、更新するかどうかを確認するプロンプトが表示され、インストールされているパックは保持されます。 --template-version latestを使用して常にプロンプトを表示せずに最新の状態にするか、ネットワーク チェックなしでダウンロードしたパックを常に使用--template-version installed。 明示的なバージョン (--template-version 1.2.3 など) を渡すと、常にそのバージョンが正確にインストールされるため、新しいパックが既に存在する場合でも再インストールされるため、スキャフォールディングはマシン間で再現できます。

最初の実行には時間がかかる場合があります。テンプレート パックをインストールまたは更新したり、選択したテンプレートで使用されている NuGet パッケージWindows アプリ SDK不足しているパッケージを復元したりするには、追加のダウンロードが必要な場合があります。 これは、新しいWindows アプリ SDKバージョンが公開された後にも発生する可能性があります。 スキャフォールディングが 10 秒後も実行されている場合、 winapp new は、パッケージがダウンロードまたは復元中であることを示すようにステータス メッセージを更新します。

実行内容:

• .NET SDK がインストールされていることを確認します (不足している場合はガイダンスで高速に失敗します—ツールチェーンをインストールしないwinapp)
• 必要に応じて、公式の WinUI テンプレート パック (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) をインストールまたは更新します
• インストールされているパックから使用可能なテンプレートを列挙し、スキャフォールディングの対象となるデリゲートを列挙します。 dotnet new <short-name>

WinUI アプリ テンプレートにはWindowsパッケージ化と ID (Package.appxmanifest) が既に含まれているため、個別のwinapp init手順は必要ありません。 アプリ テンプレートの場合は、 winapp run を使用してアプリをビルドして起動します。 winui-lib テンプレートは、アプリ プロジェクトから参照するクラス ライブラリを生成します (アプリ マニフェストはありません)。 winui-unittest テンプレートはパッケージ化された MSTest アプリであり、アプリの起動時にテストが実行されます (winapp run) dotnet test経由ではありません。 winapp newスキャフォールディングをインストール済みの.NET SDK のターゲット フレームワークに対して実行し、選択したテンプレートの適切な次の手順を出力します。

グローバル --verbose (-v) フラグを渡して、基になるすべての dotnet 呼び出し (パック クエリ、更新チェック、インストール、 dotnet new list、スキャフォールディング) とその完全な出力をエコーします。これは、テンプレート パックまたはスキャフォールディングの問題の診断に役立ちます。

例:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

---

復元

パッケージを復元し、既存の winapp.yaml 構成に基づいてファイルを再生成します。

winapp restore [base-directory] [options]

引数:

• base-directory - 復元するディレクトリ (既定値: 現在のディレクトリ)。 また、 winapp.yaml と nuget.config をオーバーライドしない限り、読み取る場所 --config-dir 選択します。

オプション:

• --config-dir <path> - winapp.yaml を含むディレクトリ (既定値: base-directory)

実行内容:

• 既存の winapp.yaml 構成を読み取ります
• SDK パッケージを指定されたバージョンにダウンロード/更新する
• C++/WinRT ヘッダーとバイナリを再生成します
• 共有可能なファイルをグローバル キャッシュ ディレクトリに格納します

注

.NETプロジェクトの場合、 (SDK バージョンはの エントリとして存在します) がないため、は実行されます。

例:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

カスタムおよびプライベート NuGet フィード:

winapp initをrestoreupdate、標準のnuget.config階層を受け入れ、NuGet を通じて Windows SDK とWindows アプリ SDK パッケージをダウンロードします。 プライベート フィードとミラー、フィード資格情報 (資格情報プロバイダーを含む)、カスタム globalPackagesFolder はすべて、 dotnet restoreの場合と同様に機能します。 独自のミラーから排他的に復元するには、継承されたソースを <clear /> し、自分のソースのみを追加します。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

注

ネイティブ プロジェクトの場合、winapp は動作するディレクトリから nuget.config を解決します。 init/restore ディレクトリ引数、指定した場合は --config-dir 、それ以外の場合は現在のディレクトリです。 .NETプロジェクトの場合、ソースはプロジェクトの独自のnuget.config階層から取得されます。これは、dotnet add packageとdotnet restore使用するため、プライベート フィードの構成をプロジェクト ディレクトリまたは先祖に配置するためです。 その階層外の --config-dir は、プロジェクトが復元できないバージョンをサイレント モードで選択するのではなく、報告および無視されます。 これらのコマンドは、信頼できるディレクトリに対してのみ実行します。 dotnet restoreに適用されるのと同じ注意が必要です。 複数のソースが構成されている場合は、 パッケージ ソース マッピング を使用して各パッケージをフィードにピン留めします。

---

アップデート

パッケージを最新バージョンに更新し、構成ファイルを更新します。

winapp update [options]

オプション:

• --setup-sdks <stable|preview|experimental|none> - SDK インストール モード: stable (既定)、 preview、 experimental、または none (SDK のインストールをスキップ)

実行内容:

• 現在のディレクトリ内の既存の winapp.yaml 構成を読み取ります
• すべてのパッケージを利用可能な最新バージョンに更新します
• winapp.yaml ファイルを新しいバージョン番号で更新します
• C++/WinRT ヘッダーとバイナリを再生成します

例:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

---

パック

プロジェクトまたは準備されたアプリケーション ディレクトリから MSIX パッケージを作成します。 ターゲット ディレクトリ、現在のディレクトリ、または Package.appxmanifest オプションと共に渡すマニフェスト ファイル (appxmanifest.xml推奨、--manifestもサポートされています) が必要です。 ( init または manifest generate を実行してマニフェストを作成します)

1 つの .csproj を渡してプロジェクトをビルドし、その出力を 1 つのステップでパッケージ化します (プロジェクト モードについては、下の プロジェクトのパッケージ化を 参照してください)。 複数の入力フォルダーを渡して、マルチアーキテクチャ配布用の .msixbundle を作成します (以下 のマルチアーキテクチャ バンドルを 参照)。

winapp pack <input-folder> [input-folder...] [options]

引数:

• input-folder - ビルドしてパッケージ化する 1 つの .csproj (プロジェクト モード)、またはパッケージ化するアプリケーション ファイルを含む 1 つ以上のディレクトリ。 複数のフォルダー ( ./publish/x64 ./publish/arm64 など) を渡して、MSIX バンドルを作成します。 スパース ID パッケージの場合は、フォルダーの代わりにスパース appxmanifest.xml ファイルを直接渡します (以下のスパース ID パッケージを参照)。

オプション:

• --output <filename> - 出力ファイル名。 単一パッケージの場合: <name>_<version>_<arch>.msix ( <name>_<version>.msix、 <name>_<arch>.msix、または <name>.msixにフォールバック)。 バンドルの場合: <name>_<version>_<arch1>_<arch2>.msixbundle。
• --name <name> - パッケージ名 (既定値: マニフェストから)
• --manifest <path> - マニフェスト ファイルへのパス (推奨Package.appxmanifest 、 appxmanifest.xml もサポートされています。既定: 自動検出)
• --cert <path> - 署名証明書へのパス (自動署名を有効にする)
• --cert-password <password> - 証明書パスワード (既定値: "password")
• --generate-cert - 新しい開発証明書を生成する
• --no-sign - パッケージを署名なしで配信し、プロジェクト署名の構成をオーバーライドします (ストアの申請や外部署名パイプラインなど)。 --certまたは--generate-certと組み合わせることはできません。
• --install-cert - コンピューターに証明書をインストールする
• --publisher <name>- 証明書の生成にPublisherします。 完全な X.500 識別名またはベア名を受け入れます ( CN=<name>として自動的にラップされます)
• --self-contained - バンドル Windows アプリ SDK ランタイム
• --skip-pri - PRI ファイルの生成をスキップする
• --executable <path> - 入力フォルダーを基準とする実行可能ファイルへのパス ( --exeも指定します)。 マニフェスト内 $targetnametoken$ プレースホルダーを解決するために使用されます。

Projectモード オプション (.csproj入力が必要です。フォルダー/バンドル/マニフェストの入力では拒否されます)。

• --configuration <name> (-c) - ビルド構成 (既定値: Release)
• --arch <arch> - ターゲット アーキテクチャ: x64、 arm64、または x86 (既定: 現在のプロセス アーキテクチャ)
• --framework <tfm> (-f) - マルチターゲット プロジェクトのターゲット フレームワーク モニカー
• --no-build - 再構築せずに既存のビルド出力をパッケージ化する
• --no-restore - ビルド前にプロジェクトの復元をスキップする
• --property <name=value> (-p) - ビルドと評価に転送される MSBuild プロパティ (反復可能)

注:WinUI/EnableMsixTooling.csproj (MSIX ツール プロジェクト モード) の場合、Windows アプリ SDKはマニフェスト、エントリ ポイント、PRI 生成を所有するため、--manifest、--executable、および--skip-priは拒否されます。<AppxManifest>、プロジェクトのエントリ ポイント、およびプロジェクト自体のリソース ビルドを構成します。 これらの 3 つのオプションは、フォルダー入力と、汎用 (MSIX 以外のツール) .csproj プロジェクト モードにも適用されます。

実行内容:

• Package.appxmanifest ファイルの検証と処理
• マニフェスト内 $placeholder$ トークンを解決します (下記の マニフェスト プレースホルダーを 参照)
• 適切なフレームワークの依存関係を確保する
• 登録を使用してサイド バイ サイド マニフェストを更新する
• マニフェスト ディレクトリまたは入力フォルダーからマニフェストで参照されているイメージ以外のファイル (AppExtension manifest.json、構成ファイルなど) がステージングから見つからない場合は、自動的に検出してバンドルします
• サードパーティの WinRT コンポーネントを自動的に検出し、そのアクティブ化可能なクラスを登録します (以下の WinRT コンポーネント検出 を参照)
• 自己完結型の WinAppSDK デプロイを処理する
• 証明書が指定された場合にパッケージに署名する

プロジェクトを直接パッケージ化する

入力が 1 つの .csprojの場合は、 winapp pack (上記のオプションを使用して) プロジェクトをビルドし、結果の出力をパッケージ化します。個別にビルドしたり、最初に出力フォルダーを見つけたりする必要はありません。 これにより、 winapp runのプロジェクト モードが反映されます。

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

ターゲット アーキテクチャは、--archから、または--archを渡さない場合の一方の-p RuntimeIdentifier=<rid>から取得されます (正確な RID は保持され、ビルドが駆動されます)。 --archと-p RuntimeIdentifierの両方を渡すことは競合であり、拒否されます。

プロジェクトはパッケージ化されたアプリ (Package.appxmanifestを使用してEnableMsixTooling=true) としてビルドする必要があります。パッケージ化されていないアプリ (WindowsPackageType=None) としてビルドするプロジェクトには、パッケージ化する MSIX マニフェストがなく、アクション可能なエラーwinapp pack報告されます。 フォルダー、バンドル、スパース マニフェストの入力は変更されません。

Project モードでは、1 つの.msixまたはアーキテクチャのみの.msixbundleが生成されます (マルチアーキテクチャ バンドルを参照)。 ストア アップロード アーカイブやリソース分割 (言語/スケール) バンドルは生成されません。明示的な -p UapAppxPackageBuildMode=StoreUpload または -p AppxBundleAutoResourcePackageQualifiers=... は、これらのフローに対してネイティブ SDK パッケージ 化コマンドを直接実行するメモで拒否されます。

スパース ID パッケージ

入力がフォルダーではなくスパース appxmanifest.xml ファイル (<Properties>の下で<uap10:AllowExternalContent>true</uap10:AllowExternalContent>宣言されているファイル) である場合、winapp packは ID 専用.msixをビルドします。これはマニフェストのみをパッケージ化し、アプリケーション バイナリやアセットはありません。 これは、 スパース パッケージ化ワークフローの手順 2 です。

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

• 出力は既定で現在のディレクトリに <PackageName>.identity.msix されます ( --output でオーバーライドします)。
• 署名は、 --cert (または --generate-cert) が指定されている場合にのみ行われます。
• マニフェストがAllowExternalContent宣言されているフォルダーを渡す場合は、既存のフォルダー パッケージの動作が適用されますが、スパース パッケージのアセット (.png/.jpg/.ico) またはバイナリ (.exe/.dll/.so) が見つかると、winapp pack警告が表示されます。スパース パッケージの場合、これらは.msix内ではなく外部の場所に属します。

パッキング後、 winapp embed-identity <exe> を実行し、 Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>を使用してインストーラーにパッケージを登録します。 スパース パッケージ ガイドを参照してください。

WinRT コンポーネントの検出

パッケージ化する場合、 winapp pack は、 winapp.yaml または *.csproj で定義されている NuGet パッケージを、サードパーティの WinRT コンポーネント (Win2D など) について自動的にスキャンします。 ファイル .winmd 解析してアクティブ化可能なクラス名を抽出し、その実装 DLL を検索します。 検出されたエントリは次のように登録されます。

• フレームワークに依存 する (既定値): アクティブ化可能なクラス <InProcessServer> は、 Package.appxmanifest
• 自己完結 型 (--self-contained): アクティブ化可能なクラスは、実行可能ファイル内のサイド バイ サイド (SxS) マニフェストに埋め込まれます

パッケージ化中のプレースホルダーの解決:

マニフェストに $targetnametoken$ 属性にExecutableが含まれている場合:

1. --executableが指定されている場合 (入力フォルダーに対する相対パス)、プレースホルダーは指定した値に置き換えられます
2. それ以外の場合は、 winapp pack 入力フォルダールートで .exe ファイルが見つかった場合は、自動的に使用されます。
3. 0 個または複数の .exe ファイルが見つかった場合は、指定を求めるエラーが表示されます。 --executable

例:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

マルチアーキテクチャ バンドル

複数の入力フォルダーが渡されると、winapp packはアーキテクチャごとに 1 つの.msixbundleを含む.msixを作成します。

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

このコマンドは、プライマリ実行可能ファイルの PE ヘッダーから各フォルダーのアーキテクチャを自動検出し、スライス間の整合性 (ID、機能、依存関係) を検証し、 <Name>_<Version>_<arch1>_<arch2>.msixbundleを生成します。

バンドルのマニフェスト解決:

バンドル内の各スライスにはマニフェストが必要です。 このコマンドは、マニフェストを次の順序で解決します。

1. --manifest <path> — 指定した場合、この 1 つのマニフェストはすべてのスライスに使用されます。 ProcessorArchitectureは、検出されたアーキテクチャに合わせてスライスごとに自動的に更新されます。

2. フォルダーごとのマニフェスト — 各入力フォルダーに Package.appxmanifest (または appxmanifest.xml) が含まれている場合、そのフォルダーのマニフェストがそのスライスに使用されます。

3. 現在のディレクトリ フォールバック — フォルダーにマニフェストがない場合、コマンドは現在の作業ディレクトリ内の Package.appxmanifest を検索し、それを使用します (アーキテクチャの自動スタンプが付いています)。

いずれの場合も、マニフェストは自動的に更新されます。プレースホルダーが解決され、依存関係が挿入され、 ProcessorArchitecture が検出されたアーキテクチャに強制的に設定されます。 解決後、クロススライス検証により、ID (名前、バージョン、Publisher)、機能、依存関係がすべてのスライスで一貫性を持つようになります。ProcessorArchitectureのみが異なる場合があります。 スライスで定義されているパッケージ バージョンは、MSIX バンドル バージョンに関連付けられます。ただし、 0.0.0.0されている場合は、タイムスタンプベースのバージョンが自動的に生成されます。

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

---

デバッグ・アイデンティティを作成

スパース パッケージを使用してデバッグ用のアプリ ID を作成します。 exe は元の場所に残ります。Windowsは、Add-AppxPackage -ExternalLocation を介して ID を関連付けます。

この場合とwinapp runを使用する場合: exe がcreate-debug-identityがelectron.exe内にある Electron アプリなど) から分離されている場合や、スパース パッケージの動作を具体的にテストする場合は、node_modulesを使用します。 exe がビルド出力フォルダーにあるほとんどのフレームワークでは、代わりに winapp run を使用します。完全なルーズ レイアウト パッケージが登録され、アプリが起動されます。 完全な比較については、 デバッグ ガイド を参照してください。

winapp create-debug-identity [entrypoint] [options]

引数:

• entrypoint - ID を必要とする実行可能ファイル (.exe) またはスクリプトへのパス

オプション:

• --manifest <path> - Package.appxmanifest または appxmanifest.xml (既定: 現在のディレクトリ内の自動検出 Package.appxmanifest または appxmanifest.xml ) のアプリ マニフェスト ファイルへのパス
• --no-install - 作成後にパッケージをインストールしない
• --keep-identity - パッケージ名とアプリケーション ID に .debug を追加せずに、マニフェスト ID を as-isしたままにする

実行内容:

• 実行可能ファイルのサイド バイ サイド マニフェストを変更します
• 識別情報のスパース パッケージを登録します
• ID が必要な API のデバッグを有効にします

例:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

---

embed-identity

<msix>要素をアプリの side-by-side (fusion) マニフェストに埋め込むことで、デスクトップ アプリケーションをスパース ID パッケージに接続します。 これはスパース パッケージ ワークフローの手順 3 です。実行中の exe が属する ID パッケージWindows示します。

winapp embed-identity <target> [options]

引数:

• target - 更新するファイル。 拡張機能によって自動検出:
  • .exe(EXE モード) — mt.exeを使用して、<msix>要素を exe の side-by-side マニフェストに直接埋め込みます。
  • .xml / .manifest (XML モード) — 外部の SxS マニフェスト ファイルに <msix> 要素を挿入または置換します (存在しない場合に作成されます)。 更新されたマニフェストがバイナリに埋め込まれるように、後でアプリをリビルドします。

オプション:

• --manifest <path> - ID (packageName、publisher、applicationId) を読み取るスパース appxmanifest.xml へのパス。 省略すると、コマンドは最初にターゲットの横にある sparse/ フォルダーを検索し、次に現在のディレクトリで、次にターゲットのディレクトリと現在のディレクトリで appxmanifest.xmlを検索します。

例:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

このコマンドはべき等です。再実行すると、既存の <msix> 要素が複製されるのではなく置き換えられます。

---

マニフェスト

Package.appxmanifest ファイルを生成して管理します。

マニフェスト生成

テンプレートから Package.appxmanifest を生成します。

winapp manifest generate [directory] [options]

引数:

• directory - マニフェストを生成するディレクトリ (既定値: 現在のディレクトリ)

オプション:

• --package-name <name> - パッケージ名 (既定値: フォルダー名)
• --publisher-name <name>- 識別名Publisherします (既定値: CN=<現在のユーザー>)。 単一値のコンマ区切りコンポーネントを持つ X.500 DN を受け入れます (複数値 + RDN と円記号はサポートされません)。ベア名は CN=<name として自動ラップされます>。
• --version <version> - バージョン (既定値: "1.0.0.0")
• --description <text> - 説明 (既定値: "マイ アプリケーション")
• --entrypoint <path> - エントリ ポイントの実行可能ファイルまたはスクリプト
• --template <type> - テンプレートの種類: packaged (既定) または sparse
• --logo-path <path> - ロゴイメージファイルへのパス
• --if-exists <Error|Overwrite|Skip> - マニフェスト ファイルがターゲット パスに既に存在する場合の動作 (既定値: Error)

テンプレート：

• packaged - 標準パッケージ アプリ マニフェスト
• sparse - 簡易化/外部配置パッケージングを使用したアプリ マニフェスト

マニフェスト プレースホルダー

生成されたマニフェストでは、パッケージ化時に自動的に解決される $placeholder$ トークン (ドル記号で区切られた) が使用されます。

プレースホルダー	解決済み	例
$targetnametoken$	拡張子のない実行可能ファイル名	Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$	Windows.FullTrustApplication	常に自動的に解決される

これは、Visual Studio プロジェクト テンプレートで使用されるのと同じ規則に従うので、マニフェストはツール間で移植可能です。

プレースホルダーの解決方法:

• winapp pack — パッケージ化中、 $targetnametoken$ は --executable オプションを使用するか、入力フォルダー内の単一の .exe を自動検出することによって解決されます。 複数の (またはゼロ) .exe ファイルが見つかり、 --executable が指定されていない場合は、エラーが表示されます。
• winapp create-debug-identity — エントリポイント引数が指定されると、 $targetnametoken$ が解決されます。 エントリポイントがない場合、実行可能プレースホルダーはマニフェストで既に解決されている必要があります。
• winapp manifest generate --executable — --executable が指定されると、実行可能ファイルからマニフェスト メタデータ (バージョン、説明) とアイコンが抽出されますが、生成されたマニフェストでは引き続き $targetnametoken$.exeが使用されます。このプレースホルダーは後で解決されます ( winapp pack や winapp create-debug-identityなど)。

PS: チェックイン マニフェストに $targetnametoken$ を保持すると、実行可能ファイル名のハードコーディングが回避され、winapp pack ビルドとVisual Studio ビルドの両方で動作します。

例:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest add-alias

Package.appxmanifest に実行エイリアス (uap5:AppExecutionAlias) を追加します。 これにより、エイリアス名を入力して、コマンド ラインからパッケージ アプリを起動できます。

winapp manifest add-alias [options]

オプション:

• --name <alias> - エイリアス名 (例: myapp.exe)。 既定値: マニフェストの Executable 属性から推論されます。
• --manifest <path> - Package.appxmanifest へのパス (既定値: 現在のディレクトリを検索)
• --app-id <id> - エイリアスを追加するアプリケーション ID (既定値: 最初の Application 要素)

実行内容:

• マニフェストを読み取り、 Executable 属性からエイリアスを推論します ( $targetnametoken$.exe などのプレースホルダーを保持します)。
• まだ存在しない場合は、 uap5 名前空間宣言を追加します
• ターゲットの Application 要素内に<Extensions>を含む<uap5:AppExecutionAlias> ブロックを追加します
• エイリアスが既に存在する場合は、それを報告して正常に終了します

例:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

マニフェストのアセット更新

1 つのソース イメージから必要なすべての MSIX イメージ資産を生成します。

winapp manifest update-assets <image-path> [options]

引数:

• image-path - ソース イメージ ファイルへのパス (PNG、JPG、SVG、ICO、GIF、BMP など)

オプション:

• --manifest <path> - Package.appxmanifest ファイルへのパス (既定値: 現在のディレクトリを検索)
• --light-image <path> - ライト テーマのバリエーションの別のソース イメージへのパス

説明：

単一のソース イメージを取得し、マニフェストの資産参照に基づいて MSIX イメージ資産の包括的なセットを生成します。

マニフェストで参照される各資産に対して、次の手順を実行します。

• 5 スケール バリアント — ベース (サフィックスなし)、 .scale-125、 .scale-150、 .scale-200、 .scale-400

アプリ アイコン (Square44x44Logo/AppList、44×44 ベース):

• 14メッキターゲットサイズバリアント — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14 個の未めっきターゲット サイズバリアント — .targetsize-{size}_altform-unplated

Additionally:

• app.ico — シェル統合用のマルチ解像度 ICO ファイル (16、24、32、48、256)。 既存の .ico ファイルがアセット ディレクトリ (プロジェクト テンプレートから AppIcon.ico など) にある場合は、複製を作成するのではなく、インプレースで置き換えられます

--light-image を使用する場合:

• ライト テーマのターゲット サイズのバリエーション — .targetsize-{size}_altform-lightunplated (アプリ アイコン)
• ライト テーマ スケールのバリエーション — .scale-{factor}_altform-colorful_theme-light (タイル、ストア ロゴ)

SVG のサポート: SVG ファイルは、ソース イメージとして完全にサポートされています。 各ターゲット サイズでベクトルとして直接レンダリングされ、すべての解像度でピクセル完璧な結果が生成されます。 ファイルは、 viewBox 属性または絶対 width 属性と height 属性を使用して独自のサイズを宣言する必要があります。 viewBox のないパーセント幅では、特定のサイズは記述されません。 どちらも宣言するソースは、空白の資産を生成する代わりに、 SVG image has no usable dimensions で拒否されます。

このコマンドは、縦横比を維持しながら画像を比例的に拡大縮小し、必要に応じて透明な背景で中央揃えします。 アセットは、マニフェストの場所を基準にして Assets ディレクトリに保存されます。

例:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

---

実行

ビルド出力フォルダーからルーズ レイアウト パッケージを作成し、Windows.Management.Deployment.PackageManager API を使用してWindowsに登録し、アプリケーションを起動して、デバッグ用に MSIX の完全インストールをシミュレートします。 デバッガーの添付ファイルのプロセス ID を返します。

winapp run は、入力から自動的に選択される 3 つのモードのいずれかで動作します。

• フォルダー モード — 入力はビルド出力フォルダー ( Package.appxmanifest/AppxManifest.xmlを含む) です。
• Project モード — 入力は、.csproj、.sln/.slnx ソリューション、または 1 つを含むディレクトリです。 winapp run はプロジェクトをビルドして起動し、 パッケージ化された WinUI アプリと パッケージ化されていない WinUI アプリの両方をサポートします。 以下Projectモードを参照してください。
• 単一ファイル モード — 入力は.cs.NETファイル ベースのアプリです。 winapp run は、それをビルドし、その #:property ディレクティブからマニフェストを生成し、パッケージ ID を使用して起動します。

Tip

モードの選択は、既定ではサイレントです。 ディレクトリがプロジェクトとしてビルドされることが予想されたときにビルド出力フォルダーとして扱われた場合は、 --verbose を使用して再実行します。フォルダー モードでは、それが選択された理由が報告されます (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.)。 ディレクトリは、実行可能なアプリを持つ .csproj/.sln/.slnx が 最上位レベルにある場合にのみプロジェクトとしてビルドされます。再帰的に検索されるわけではありません。

これは、ほとんどのフレームワーク (.NET、C++、Rust、Flutter、Tauri) のパッケージ ID を使用したデバッグに推奨されるコマンドです。 1 つの exe にスパース パッケージを登録する create-debug-identity とは異なり、 winapp run は、実際の MSIX インストールと同様に、フォルダー全体をルーズ レイアウト パッケージとして登録します。 一般的なデバッグ ワークフローについては、 デバッグ ガイド を参照してください。

winapp run [<input>] [options]

引数:

• input- 実行するアプリ: ビルド出力フォルダー (フォルダー モード)、.cs .NET ファイル ベースのアプリ (単一ファイル モード)、.csproj プロジェクト、.sln/.slnx ソリューション、またはその最上位レベル (プロジェクト モード、ディレクトリは再帰的に検索されません) のいずれかを含むディレクトリ。 .を使用して、現在のディレクトリでプロジェクトをビルド/実行します。 省略可能 — 省略すると、既定で現在のディレクトリ に設定されます ( dotnet runに一致します)。

オプション:

• --manifest <path> - Package.appxmanifest へのパス (既定値: 入力フォルダーまたは現在のディレクトリからの自動検出)
• --output-appx-directory <path> - ルーズ レイアウトの出力ディレクトリ (既定値: 入力フォルダー内の AppX )。 既定のレイアウトでは、ビルド内のファイルが削除されなくなります。カスタム ディレクトリは追加のファイルを保持します。 クリーンなレイアウトが必要な場合は、新しいカスタム ディレクトリを使用します。
• --args <string> - アプリケーションに渡すコマンド ライン引数。 または、エスケープ (-- など) を回避するために、winapp run . -- --flag valueの後に引数を使用します。
• --no-launch - デバッグ ID のみを作成し、アプリケーションを起動せずにパッケージを登録する
• --with-alias - AUMID アクティブ化の代わりに、実行エイリアスを使用してアプリを起動します。 アプリは、継承された stdin/stdout/stderr を使用して現在のターミナルで実行されます。 ほとんど必要ありません: OutputType=Exe を持つアプリは、既定で既にこのように起動しています。 winapp は、AppX レイアウトでステージするマニフェストに必要な uap5:ExecutionAlias を追加するため、チェックインしたマニフェストに変更は必要ありません。アプリが宣言するエイリアスが as-is使用されます。 --no-launch、--detach、--without-alias、または--jsonと組み合わせることはできません。
• --without-alias - 実行エイリアスを使用して起動するアプリの AUMID アクティブ化を強制します。 コンソール アプリはコンソールなしで実行され、このターミナルには何も出力されません。 --with-aliasと組み合わせることはできません。
• --debug-output - 起動されたアプリケーションから OutputDebugString メッセージと初回例外をキャプチャします。 フレームワーク ノイズ (WinUI、COM、DirectX) はコンソール出力からフィルター処理されます。完全なログ ファイルでは、すべてをキャプチャします。 アプリがクラッシュした場合は、ミニダンプを自動的にキャプチャし、それを分析して、ソース ファイル:行番号 (ビルド出力フォルダー内の PDB から解決) を使用して例外の種類、メッセージ、スタック トレースを表示します。 マネージド (.NET) クラッシュは、外部ツールなしで即座に分析されます。 ネイティブ (C++/WinRT) クラッシュでは、モジュール名とオフセットが表示されます。 クラッシュしたアプリが WinUI 3 アプリである場合 (Microsoft.UI.Xaml.dllが読み込まれます)、余分な格納例外トリアージ パスが自動的に実行され、元の HRESULT、ErrorContext チェーン、および完全なネイティブ XAML ディスパッチ スタックが表示されます。必要なデバッガー コンポーネントは最初の使用時にダウンロードされます (環境変数を介してオーバーライド可能WINAPP_DBGTOOLS_DIRを参照)。 一度に 1 つのプロセスにアタッチできるデバッガーは 1 つだけであるため、他のデバッガー (Visual Studio、VS Code) を同時に使用することはできません。 別のデバッガーをアタッチする必要がある場合は、代わりに --no-launch を使用します。 --no-launchと組み合わせることはできません。 --jsonと組み合わせることはできません。
• --symbols - Microsoft シンボル サーバーから PDB シンボルをダウンロードして、解決された関数名を使用してネイティブ クラッシュ分析を充実させます。 --debug-output でのみ使用されます。 省略してネイティブ クラッシュが発生した場合、出力ではこのフラグの追加が推奨されます。 このフラグにより、WinUI 3 アプリの WinUI に格納された例外トリアージ スタックも改善されます。 最初の実行では、シンボルがダウンロードされ、ローカルにキャッシュされます。それ以降の実行ではキャッシュが使用されます。
• --unregister-on-exit - アプリケーションの終了後に開発パッケージの登録を解除します。 開発モードで登録されているパッケージのみを削除します。 --no-launchと組み合わせることはできません。
• --detach - アプリケーションを起動し、終了するのを待たずにすぐに戻ります。 起動後にアプリを操作する必要がある CI/オートメーションに便利です。 ローカル実行では PID が出力されます。ターゲットの実行では、スコープ付き UI ターゲットが出力されます。 JSON には、PID とターゲット スコープが含まれます。 --no-launch、--debug-output、--with-alias、または--unregister-on-exitと組み合わせることはできません。
• --clean - 再デプロイする前に、既存のパッケージのアプリケーション データ (LocalState、設定など) を削除します。 既定では、アプリケーション データは再デプロイ全体で保持されます。
• --json - プログラムによる使用 (CI/オートメーションなど) 用に出力を JSON として書式設定します。 PID をキャプチャする --detach に便利です。 --with-aliasまたは--debug-outputと組み合わせることはできません。
• --on <target> - ホスト上にビルドし、ターゲットで登録して実行します。 現在、 sandboxがサポートされています。ローカル実行へのフォールバックはありません。 フォローアップ UI コマンドの前に --detach を使用します。 サンドボックス --debug-output には、パッケージ 化されたアプリが必要です。 セットアップ、ランタイムのサポート、デタッチされたアプリの有効期間については、「Windowsサンドボックスの実行」を参照してください。

アプリケーション データの永続化:

既定では、 winapp run は再デプロイ時にアプリケーションのデータ (LocalState、 RoamingState、 Settingsなど) を保持します。 アプリがパッケージ コンテキスト内の ApplicationData.Current.LocalFolder または Environment.GetFolderPath(SpecialFolder.LocalApplicationData) にデータを書き込む場合、そのデータは winapp run 呼び出し全体で存続します。

新しい開始が必要な場合 (破損した状態をリセットしたり、初回実行時の動作をテストしたりする場合など) には、 --clean を使用します。

実行内容:

• Package.appxmanifest を検索または生成します。
• ルーズ レイアウト パッケージを使用してデバッグ ID を作成および登録します。
• アプリケーション ユーザー モデル ID (AUMID) を計算します
• 登録済み ID を使用してアプリケーションを起動します ( --no-launch が指定されていない場合)
• デバッガーの添付ファイルのプロセス ID (PID) を出力します

例:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Project モード (.NET SDK プロジェクト)

入力が.csproj、.sln/.slnx ソリューション、または 1 つ (.を含む) を含むディレクトリである場合、winapp rundotnet buildを使用してプロジェクトをビルドし、それを起動します。 パッケージ化された WinUI アプリとパッケージ化されていない WinUI アプリの両方をサポートし、起動前にアプリに必要な一致アーキテクチャWindows アプリランタイムをインストールします。

ソリューション入力:winapp run.sln/.slnx (または 1 つを含むディレクトリを含むディレクトリ) をポイントすると、.csproj 実行可能なアプリ プロジェクトが解決され、$(SolutionDir)と兄弟Solution*プロパティが定義された状態でビルドされるため、それらに依存するプロジェクトはVisual Studioでビルドされます。 解決規則:

• テスト プロジェクトは 自動選択時にスキップされるため、アプリとそのテストを含むソリューションは、 --project 不要でアプリに解決されます。 (WinUI テスト プロジェクト自体はパッケージ アプリであるため、出力の種類だけでは区別できません)。
• 実行可能なプロジェクトがテスト プロジェクトのみの場合は、実行されます。
• 複数の実行可能なアプリ プロジェクトが存在する場合、 winapp run はスタートアップ プロジェクトを推測しません。候補の一覧がエラーになります。 --project <name>を使用して選択します。テスト プロジェクトの選択を含め、常に優先されます。

パッケージ化されたプロパティとパッケージ化されていないプロパティは、プロジェクトの有効な WindowsPackageType MSBuild プロパティから自動的に検出されます (マニフェストの存在からは検出されません)。

• パッケージ化 (WindowsPackageType=MSIX、WinUI パッケージの既定値) - ビルドし、ビルド出力をルース レイアウト パッケージとして登録し、AUMID (フォルダー モードと同じパイプライン) を介して起動します。
• パッケージ化されていない (WindowsPackageType=None) — ビルドにより、フレームワークに依存するWindows アプリランタイムがインストールされ、ビルドされた.exeが直接起動されます。 -p WindowsPackageType=Noneを使用してパッケージ化されたプロジェクトに対してこれを強制します。

Project モードでは、.NET SDK 8.0.100 以降が必要です (MSBuild --getPropertyの場合)。

ネイティブ AOT: project ファイルの<Project>要素内にこのプロパティ グループを追加し、--aot追加します。

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aotは x64 および ARM64 プロジェクトをサポートしており、.NET SDK 8.0.300 以降が必要です。 プロジェクトの AOT 構成 dotnet publish 実行し、その出力を起動します。1 回限りのオーバーライドには -p PublishAot=true を使用します。 個別のランタイム認定は実行されず、 --no-build または --manifestと組み合わせることはできません。

MSIX レイアウトが生成されていないパッケージ ID を使用するアプリの場合は、プロジェクトの発行出力に Package.appxmanifest または appxmanifest.xml を含めます。 Winapp は、そのマニフェストを使用して発行されたファイルをステージングします。 両方の名前が存在する場合、winapp は 1 つを選択する代わりに停止します。古いマニフェストを削除し、目的のマニフェストのみを発行するようにプロジェクトを構成します。

Project モード オプション (特に明記されていない限り、フォルダー モードでは無視されます):

• -c, --configuration <name> - ビルド構成。 既定値: Debug。 (単一ファイル モードでも使用できます)。
• --arch <x64|arm64|x86> - ターゲット アーキテクチャ。 既定値: 現在のプロセス アーキテクチャ。 ビルド RID と Windows アプリ ランタイム アーキテクチャを決定し、有効なビルドで必要な場合は、一致するプラットフォーム依存の発行プロファイルを選択します。 (単一ファイル モードでも使用できます)。
• -r, --runtime <rid>- ターゲット .NETランタイム識別子 (例: win-x64)。 Project モードでは、RID のアーキテクチャのみを使用し、常に正規のwin-<arch>を構築し、Windows以外の RID (linux-x64 など) を拒否します。 そのアーキテクチャは --arch オーバーライドされ、必要な発行プロファイルを選択できます。 (単一ファイル モードでも使用され、ファイルによって宣言された #:property RuntimeIdentifier がオーバーライドされます)。
• -f, --framework <tfm> - 複数ターゲット プロジェクトのターゲット フレームワーク モニカー (例: net10.0-windows10.0.26100.0)。 (単一ファイル モードでは拒否されます。 #:property TargetFramework=...を使用します)。
• --project <name-or-path> - 入力がソリューション (.sln/.slnx) または複数の実行可能なアプリ プロジェクトを含むディレクトリである場合は、起動するプロジェクトを (プロジェクト名またはパスで) 選択します。 (単一ファイル モードでは拒否されます。 .cs ファイル ベースのアプリ自体がプロジェクトです)。
• --no-build - ビルドをスキップし、既存のビルド出力を実行します (出力プロパティは引き続き評価されます)。 (単一ファイル モードでも使用できます)。
• --no-restore - ビルドまたはネイティブ AOT 発行の前に復元をスキップします。 (単一ファイル モードでも使用できます)。
• --aot- ネイティブ AOT 発行.NETプロジェクトの構成済みを実行します。 効果的な PublishAot=trueが必要です。 フォルダー モードと単一ファイル モードで拒否されました。
• -p, --property <Name=Value> - MSBuild プロパティ。ビルドとプロパティ評価の両方に転送されます。 複数のプロパティに対して -p を繰り返します。値のリテラルセミコロンまたはコンマには %3B または %2C を使用します。 (単一ファイル モードでも受け入れ、 TargetFrameworkを設定する唯一の方法です)。

ビルド出力と詳細度: 通常のプロジェクト実行では dotnet buildを使用し、ビルドされた出力を評価します。 認証されたフィード URL からの資格情報が編集された状態で、出力ストリームをライブで復元してビルドします。 --aotでは、winapp はdotnet publishを使用します。--verbose発行コマンドと解決されたパスが表示されます。 表示される内容を制御するには、次の詳細オプションを使用します。

フラグ	dotnet verbosity	追加
(既定)	minimal	—
--verbose	minimal	winapp のビルド決定トレース
--quiet	quiet	—

ネイティブ AOT は、到着すると出力ストリームを発行します。 --jsonでは、復元/ビルド呼び出しと子出力は stderr に送られ、stdout は純粋な JSON のままです。 --quietでは、呼び出しは抑制され、dotnet の静かな復元/ビルド出力は stderr にルーティングされるため、stdout はクリーンなままです。 ネイティブ AOT 発行の出力も、いずれかのオプションで stderr に送信されます。

オプションの適用可能性: ID/ルーズ レイアウト オプション (--manifest、 --output-appx-directory、 --no-launch、 --with-alias、 --unregister-on-exit、 --clean、 --executable) はパッケージ アプリにのみ適用されます。 パッケージ化されていないアプリ (MSIX パッケージがないアプリ) では、明確なエラーで拒否されます。 起動/デバッグ オプション (--args/--、 --detach、 --debug-output、 --symbols、 --json) は両方で機能します。

Projectモードの例:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

単一ファイル モード (.NET ファイル ベースのアプリ)

.NET 10 では、プロジェクト ファイルなしで 1 つの.cs ファイルを実行し、上部に#: ディレクティブを使用して構成できます。 そのファイル winapp run ポイントすると、アプリがビルドされ、appxmanifest が生成され、 パッケージ ID で起動されます。そのため、 Windows.ApplicationModel.Package.Current 機能すると、アプリは実際の AUMID とスタート メニュー エントリを取得し、ID (アプリ通知、 ApplicationData、デバイス上の AI) を必要とする API が機能します。

プロトコル ハンドラー、ファイルの関連付け、共有ターゲット、スタートアップ タスクなどのシェル統合には、生成されたマニフェストに含まれていない宣言された <Extensions> エントリが必要です。 追加するには、独自のマニフェストを作成します。以下の「独自の マニフェストを作成する」を 参照してください。

winapp run counter.cs

または、プレーンなdotnet runで実行します。以下の「dotnet runで実行する」を参照してください。

マニフェストは作成しません。 代わりに、 #:property ディレクティブを使用してパッケージについて説明します。

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

マニフェストのプロパティ。 すべて省略可能です。それぞれが適切な既定値にフォールバックします。

財産	設定	Default
WinAppPackageName	Identity/@Name (パッケージ ID)	[-.A-Za-z0-9]にサニタイズされたファイル名と、ファイルのパスの短いハッシュ (counter.cs → counter-a1b2c3d4)
WinAppDisplayName	[スタート] と [設定] に表示される名前	拡張子のないファイル名
WinAppPublisher	Identity/@Publisher	CN=<your Windows user name>。 ベア名は CN=<name>としてラップされます。
WinAppVersion	Identity/@Version	$(Version)、正規化 (下記参照)
WinAppDescription	インストール時と [設定] に表示される説明	表示名
WinAppCapabilities	;または で区切って宣言する機能,	none

Version. パッケージ のバージョンは、0 ~ 65535 の 4 つの数値である必要があります。 WinAppVersion (または、設定しない場合は、標準の Version プロパティ) に合わせて正規化されます。任意の -preview/-rc サフィックスは削除され、不足しているコンポーネントはゼロでいっぱいになるため、 #:property Version=1.2.3-preview.4 は 1.2.3.0 になり、アセンブリのバージョンとパッケージのバージョンが一緒に設定されます。 65535 を超えるコンポーネント、または 4 つ以上のコンポーネントに合わせて設定できない値は、警告なしに変更されるのではなく 、エラーで拒否されます 。

Capabilities

アプリは、パッケージ化されたアプリのみを必要とする API を満たす ID を使用して完全信頼を実行します。 ただし、一部の API は、宣言された機能に関係なくゲートされます。Windows AI API が一般的なケースです。 (プロトコル ハンドラーやファイルの関連付けなどのシェル統合は、3 番目のケースです。機能ではなく、作成された <Extensions> エントリが必要であるため、 独自のマニフェストを 使用してください)。

#:property WinAppCapabilities=systemAIModels

これは、Phi Silica と、マニフェストに必要なその他のオンデバイス モデル API です。 それらを区切っていくつかの宣言を行います。

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp は、実際に必要な要素と XML 名前空間に各名前空間を書き込み、その名前空間を宣言し、機能に新しい名前空間が必要な場合に MaxVersionTested を発生させます。 これは、複数の異なる要素に機能が分散され、上記の同じリストが3 つの異なる 形になります。

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

winapp が知っている名前は、ユーザーのために書かれています。 制限付きセットが時間の経過と共に拡張されるその他の場合は、名前空間プレフィックスを使用して自分で修飾します。

接頭辞	出力
rescap:	<rescap:Capability> — 制限付き機能
uap:、uap6:、uap7:、uap11:	<uap*:Capability>
systemai:	<systemai:Capability>
device:	<DeviceCapability>
app:	<Capability> 既定の名前空間

#:property WinAppCapabilities=rescap:broadFileSystemAccess

認識できないベアネームは、推測されるのではなく、これらのプレフィックスに名前を付けるエラーで拒否されます。間違った名前空間で出力された機能により、マニフェストが生成Windows、警告なしに許可せずに登録または受け入れることを拒否します。

独自のマニフェストを持ち込む

プロパティに含まれないもの (プロトコル ハンドラー、ファイルの関連付け、実行エイリアス) が必要な場合は、マニフェストを作成し、 winapp run はマニフェストを生成する代わりに逐語的に使用します。 次の順序で取得されます。

1. --manifest <path> をクリックします。
2. #:property WinAppManifestPath=<path> を .cs ファイルに保存します。
3. <filename>.appxmanifestという名前の.cs ファイルの横にあるマニフェスト (たとえば、counter.csの横counter.appxmanifest)。

ファイルごとの名前のみが自動的に取得されます。 同じフォルダー内の Package.appxmanifest または appxmanifest.xml は意図的に無視されます。複数の .cs ファイルがフォルダーを共有でき、共有名を採用すると、あるアプリが別のユーザーの ID で自動的に実行されます。 複数のファイルに対して 1 つのマニフェストを使用するには、 --manifest または WinAppManifestPathで明示的に名前を付けます。

それ以外の場合、 Package.appxmanifest は既定のイメージアセットと共にビルド出力に生成され、実行するたびに更新されます。

Options. すべてのフォルダー モード オプションは、 --no-launch、 --with-alias、 --without-alias、 --detach、 --clean、 --debug-output、 --symbols、 --unregister-on-exit、 --args/--、 --json、 --executable、 --manifest、 --output-appx-directory、および -c/--configuration、 --no-build、 --no-restore、および -p/--propertyです。

Tip

コンソール アプリは、既定でターミナルに出力されます。 AUMID を介して起動されたパッケージ アプリにはコンソールがないため、コンソールのみのアプリは正しく実行され、何も出力されません。 winappは、 OutputType=Exe を持つアプリが代わりに実行エイリアスを介して起動され、このターミナルのstdin/stdout/stderrを継承することを回避します。 パッケージ ID は引き続き取得され、要求する必要はありません。

winapp run counter.cs

--without-aliasを渡して AUMID のアクティブ化を強制します。その後、アプリはコンソールなしで実行され、ここには何も出力されません。 ウィンドウ化されたアプリ (WinExe) にはウィンドウが表示されるため、AUMID のアクティブ化が維持されます。このターミナルで必要な場合は --with-alias 渡します。 すべてのコマンド ラインではなく、ファイル内の選択を修正するには、 .csproj で使用するのと同じプロパティを設定します。

#:property WinAppRunUseExecutionAlias=false

winapp が宣言するエイリアスは、パッケージ ファミリ名の名前にwinapp-プレフィックスが付いているため、CN=Youによって公開com.contoso.counterwinapp-com.contoso.counter_gspb8g6x97k2t.exe。 その末尾の部分は、Windows派生した発行元ハッシュであるため、異なる発行元の下で名前を共有する 2 つのアプリは、引き続き異なるエイリアスを取得します。 プレフィックスは、実際のコマンドの名前を明確に保ちます。python.cs内のアプリは、python.exeしないwinapp-…エイリアスを取得します。 独自のマニフェストを作成した場合、宣言したエイリアスは as-is 使用され、winapp では何も追加されません。

これはエイリアスにのみ適用されます。 登録自体はパッケージ 名に基づいてキー設定されるため、別の発行元で同じ WinAppPackageName を宣言する 2 つ目のアプリを実行すると、一緒に配置されるのではなく、最初の登録が置き換えられます。 両方を一度に登録する場合は、各アプリに独自の名前を付けます。

winapp run は登録したエイリアスを出力するため、ハッシュを計算して検索する必要はありません。

エイリアスは、パッケージが登録されている限り、PATH 上のコマンドです。 他のパッケージが既に名前を所有している場合、winapp はそう言います。 エイリアスを推測すると、間違ったアプリを起動するのではなく、代わりに AUMID 経由で起動します。 --with-alias または #:property WinAppRunUseExecutionAlias=true で明示的に要求した場合、他の操作を静かに行う代わりに失敗します。

ファイル ベースのアプリがそれ自体を構成するため、2 つのプロジェクト モード オプションは適用 されません 。 これらは、代わりに使用するディレクティブに名前を付けるメッセージで拒否されます。

Option	代わりに使用する
-f/--framework	#:property TargetFramework=net10.0-windows10.0.22621.0
--project	nothing — .cs ファイルはプロジェクトです

--arch と -r/--runtime プロジェクト モードで行うのと同じように動作します。 どちらの方法も渡さない場合は、マシンのアーキテクチャ用の winapp ビルドが必要です。これは自己完結型のWindows アプリ SDK アプリが必要とするものです。この場合、SDK はAnyCPUビルドされ、WindowsAppSDKSelfContained requires a supported Windows architectureで失敗するためです。 ファイル内の #:property RuntimeIdentifier=win-arm64 が尊重されます。明示的な --arch/--runtime によってオーバーライドされます。

パッケージ化された作業とパッケージ化されていない両方の作業は、プロジェクト モードとまったく同じように、有効なWindowsPackageTypeから検出されます。既定では、緩いレイアウトが登録され、ID で起動されます。一方、#:property WindowsPackageType=Noneはアプリをビルドし、一致するWindows アプリランタイムをインストールし、.exeを直接起動します。 (パッケージ 化されたアプリは、実行エイリアスまたは AUMID のアクティブ化を通じて起動されます。上記のコンソール の注を参照してください。パッケージ化されているかどうかとは別の選択です)。ID オプション (--no-launch、 --with-alias、 --without-alias、 --clean、 --unregister-on-exit、 --manifest、 --output-appx-directory) は、パッケージ アプリにのみ適用されます。

を使用して実行する dotnet run

winappをまったく入力する必要はありません。 ファイルから Microsoft.Windows.SDK.BuildTools.WinApp パッケージを参照し、プレーン dotnet run でパッケージ化された同じ起動を提供します。

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

パッケージの MSBuild ターゲットにより、実行が winapp にリダイレクトされ、ビルドしたアプリ dotnet run パッケージ化、登録、起動されます。これは再構築されません。 マニフェストの処理は変更されません。winapp はwinapp runの場合とまったく同じように解決するため、#:property WinAppManifestPath=…と.csの横の<filename>.appxmanifestはどちらも優先されます (「独自のマニフェストを持ち込む」を参照)、ディレクトリ全体のPackage.appxmanifestは無視され、それ以外の場合は#:property ディレクティブから生成され、実行ごとに更新されます。

リダイレクトが発生するには、次の 2 つの条件を保持する必要があります。

ディレクティブ	なぜでしょうか
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*	このパッケージでリダイレクト出荷を行うターゲット
#:property TargetFramework=net10.0-windows…	プレーンな net10.0 ファイルは単独のままであるため、パッケージ化されていない状態で実行されます

#:property WindowsPackageType=Noneを追加しても、ファイルは単独で残ります。dotnet run ID なしで.exeを直接実行します。 一致する Windows アプリ ランタイムを最初にインストールする場合は、パッケージ化されていないパスにwinapp runを使用します。

リダイレクトを完全にオプトアウトするように#:property EnableWinAppRunSupport=falseを設定し、「構成」で説明されているWinAppRun*プロパティを設定して起動を整形します。次に例を示します。

#:property WinAppRunUnregisterOnExit=true

ID が必要なときにパッケージ化されていないアプリを実行 dotnet run 場合は、MSBuild に理由を尋ねます。 dotnet msbuildではなく、dotnet buildを使用します。ファイル ベースのアプリがコンパイルdotnet build仮想プロジェクトのみを合成します。

dotnet build counter.cs -t:WinAppRunSupportInfo

単一ファイル モードでは、.NET SDK 10.0.300 以降が必要です。

登録は実行時間を上回ります。 winapp run counter.cs アプリが終了した後、フォルダーとプロジェクト モードとまったく同じようにパッケージが登録されたままになります。そのため、 LocalState は存続し、同じファイルを再実行すると、登録を重ねるのではなく、同じ ID が再利用されます。 winapp は、アプリを初めて登録し、 winapp unregister が .cs 自体を受け取ると言います。

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs マニフェスト パスは必要ありません。ファイルの #:property 値 run と同じように評価され、 その ファイルのビルド出力から登録されているパッケージのみが削除されます。 別のフォルダーから登録された同じ名前のアプリは、 --force渡さない限り拒否されます。 実行で ID またはレイアウトを構成するオプションを使用した場合は、同じオプションを unregisterに渡します。

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-pはファイル独自のディレクティブをオーバーライドし、.csの横にあるDirectory.Build.propsは$(Configuration)または$(RuntimeIdentifier)をオフにWinAppPackageNameキーを設定できるため、これらの各パッケージが登録されるパッケージを変更できます。

SDK の一時出力が消去されると、 winapp unregister counter.cs は登録がそのファイルから取得されたことを確認できなくなり、スキップされます。 winapp unregister --prune を使用してファイルが削除された登録をクリアするか、 --force して特定のファイルを削除します。 --output-appx-directory使用された実行の場合は、レイアウトを認識できるように、同じディレクトリをunregisterに渡します。

カスタム出力パスにも同じことが当てはまります。SDK の標準 <root>\bin\<configuration> レイアウトから所有権が確認されるため、 -p OutputPath=<somewhere-else> でビルドされた実行をソース ファイルと照合することはできません。 unregister は、より広いディレクトリで推測するのではなく、 --output-appx-directoryでレイアウトに名前を付けたり、 --forceを使用したりするのではなく、スキップします。

単一ファイルの例:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

注

既定の ID には、ファイルのパスの短いハッシュが含まれています。counter.cscounter-a1b2c3d4のようになります。そのため、異なるフォルダー内の 2 つのcounter.cs ファイルは異なるアプリであり、独自の設定とLocalStateを保持します。 ハッシュはパスから派生するため、編集と再実行は存続し、ファイルを移動した場合にのみ変更されます。 #:property WinAppPackageName=<name>を設定して、安定した ID を自分で選択します。Identity/@Name可能に正規化されます。[-.A-Za-z0-9]外の文字は削除され、3 文字未満の名前は1で埋め込まれます。結果は 50 文字に制限されるため、My AppはMyAppとして登録されます。 どちらの場合も、[スタート] メニューと [設定] には、ID ではなく WinAppDisplayName (既定: ファイル名) が表示されます。 ID は常にユーザー アカウントにスコープ設定されるため、同じコンピューター上の別のユーザーと競合することはありません。

MSBuild プロパティ (NuGet パッケージ):

Microsoft.Windows.SDK.BuildTools.WinApp NuGet パッケージを使用すると、dotnet run は自動的に winapp run を呼び出します。

dotnet run後に書き込まれたものはすべて、パッケージがない場合とまったく同じように、アプリケーションに渡されます。 以下の MSBuild プロパティを使用してランチャーを構成します。

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

.csprojでは、次の MSBuild プロパティを設定して動作を制御できます。

財産	Default	説明
EnableWinAppRunSupport	true	実行サポート機能を有効または無効にする
WinAppLaunchArgs	(空)	起動時にアプリに渡す引数
WinAppRunUseExecutionAlias	アプリから推論される	AUMID アクティブ化ではなく、実行エイリアスを使用して起動します。 設定を解除したまま、winapp はそれを推測します。コンソール アプリはエイリアスを使用して出力がターミナルに到達し、ウィンドウ化されたアプリは AUMID を使用します。 trueまたはfalseを設定して、自分で決定します。
WinAppRunNoLaunch	false	起動せずに ID のみを登録する
WinAppRunDebugOutput	false	OutputDebugStringメッセージと初回例外をキャプチャします。 一度にアタッチできるデバッガーは 1 つだけです (VS/VS Code を禁止します)。 代わりに WinAppRunNoLaunch を使用して、別のデバッガーをアタッチします。
WinAppRunDetach	false	アプリが終了するのを待たずに、起動直後に戻ります。 PID を出力します。
WinAppRunUnregisterOnExit	false	アプリの終了後に開発パッケージの登録を解除する
WinAppRunClean	false	再デプロイする前に、既存のパッケージのアプリケーション データ (LocalState、設定) を削除する
WinAppRunSymbols	false	Microsoft シンボル サーバーからシンボルをダウンロードして、より豊富なネイティブ クラッシュ分析を行います。 WinAppRunDebugOutputでのみ効果があります。
WinAppRunExecutable	(空)	ビルド出力フォルダーを基準とした実行可能パス。 マニフェストに $targetnametoken$ が含まれており、出力フォルダーに複数の .exeがある場合に使用します。
WinAppRunArgs	(空)	winapp run コマンド ラインに追加される生の引数 (専用プロパティのないオプションの場合) (--verboseなど)。 上記のすべてのプロパティの後に追加されます。

相互に排他的な設定。 WinAppRunNoLaunch と WinAppRunDetach それぞれ異なる起動動作が記述されているため、他の起動プロパティと競合します。 競合するペアを設定すると、 --X and --Y cannot be used togetherで実行が失敗します。

財産	と組み合わせることはできません
WinAppRunNoLaunch	WinAppRunDetach、WinAppRunDebugOutput、WinAppRunUnregisterOnExit
WinAppRunDetach	WinAppRunNoLaunch、WinAppRunDebugOutput、WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias は意図的にどちらの方向でもそのリスト に含まれていません 。 false 起動とデタッチが既に使用されている AUMID ライセンス認証を要求します。実行エイリアスには追跡された実行中のプロセスが必要であるため、 true は、どちらかが設定されている場合は適用されません。 そのため、 <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> をチェックインするプロジェクトは、 dotnet run -p:WinAppRunDetach=trueの下で正常に実行され、失敗するのではなく、AUMID 経由で起動されます。

WinAppRunUseExecutionAlias、 WinAppRunDebugOutput、および WinAppRunUnregisterOnExit を相互に組み合わせることができます。 WinAppRunClean、 WinAppRunSymbols、 WinAppRunExecutable、および WinAppLaunchArgs には制限はありません。 WinAppRunArgs はそれ自体の制限を追加しませんが、それを通過したスイッチは他と同様にチェックされるため、 WinAppRunArgs="--detach" は WinAppRunNoLaunchと競合します。

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

---

解除

サイドロードされた開発パッケージの登録を解除します。 開発モードで登録されたパッケージのみを削除します (たとえば、 winapp run または create-debug-identity経由)。 ストアインストール済みパッケージまたは MSIX インストール済みパッケージは削除されません。

winapp unregister [input] [options]

引数:

• input- パッケージの登録を解除する必要がある.NETファイル ベースのアプリ (単一の.cs) へのパス。 その ID は、 winapp run アプリに作成されたマニフェストがある場合は作成されたマニフェストから、それ以外の場合は #:property 値から解決されるのと同じ方法で解決されるため、マニフェスト パスは必要ありません。 --manifestを使用するか、現在のディレクトリ内のマニフェストを自動検出する場合は省略します。 パッケージに別の方法で名前を付け、別の方法で解決できる --manifestと組み合わせることはできません。

オプション:

• --manifest <path> - Package.appxmanifest へのパス (既定値: 現在のディレクトリからの自動検出)
• --force - ローカル登録解除のみの場合は、パッケージが別のプロジェクト ツリーから登録されている場合でも、インストール場所ディレクトリのチェックをスキップして登録を解除します。 --onで拒否されます。ターゲットの所有権チェックをバイパスすることはできません。
• --on <target> - このマシンではなく、一致する winapp 所有の開発登録を sandboxから削除します。 マニフェストが必要であり、 --forceをサポートしていません。 サンドボックス アプリのクリーンアップを参照してください。
• --prune - ファイルがなくなったすべての開発モード登録を削除します。 入力、 --manifest、 --property、 --configuration、 --arch、 --runtime、または --output-appx-directoryと組み合わせることはできません。
• -p, --property <Name=Value> - .cs ファイル ベースのアプリの ID を解決するときに使用される MSBuild プロパティ。 再現。 コマンド ライン プロパティはファイルの独自の#:property ディレクティブをオーバーライドするため、実行で使用される同じ ID に影響するプロパティ (例: -p WinAppPackageName=...) を渡します。 .cs入力にのみ適用されます。
• -c, --configuration <name> - .cs ファイル ベースのアプリの ID を解決するときに使用されるビルド構成。 既定値: Debug。 実行に使用されるのと同じ構成を渡します。.csの横にあるDirectory.Build.propsは、$(Configuration)でWinAppPackageNameまたは条件付きでWinAppManifestPathできます。 .cs入力にのみ適用されます。
• --arch <x64|arm64|x86> - .cs ファイル ベースのアプリの ID を解決するときに使用されるターゲット アーキテクチャ。 既定値: 現在のプロセス アーキテクチャ。 ID は $(RuntimeIdentifier)からキーを設定することもできるため、実行に使用したのと同じアーキテクチャを渡します。 .cs入力にのみ適用されます。
• -r, --runtime <rid>- .csファイル ベースのアプリの ID を解決するときに使用するターゲット .NETランタイム識別子 (win-x64 など)。 そのアーキテクチャのみが使用され、 --archオーバーライドされます。 .cs入力にのみ適用されます。
• --output-appx-directory <path> - パッケージが登録された AppX レイアウト ディレクトリ。 実行オプションがレイアウトを生成したパッケージ レコードに何もないため、実行が --output-appx-directory使用されている場合にのみ必要です。
• --json - 出力を JSON として書式設定する

実行内容:

• .cs ファイルの解決された ID から、またはマニフェストを読み取って、パッケージ名を決定します
• {name}パッケージと{name}.debug パッケージの両方を検索します (デバッグバリアントはcreate-debug-identityによって作成されます)
• 各パッケージが開発モードで登録されたことを確認します (IsDevelopmentMode == true)
• パッケージが ( --forceを除く) 名前を付けたアプリに属することを確認します。インストール場所は、指定したディレクトリ ( .cs ファイルの独自のビルド出力、マニフェストのディレクトリ、現在のディレクトリ、または明示的な --output-appx-directory) の下に配置する必要があります。 インストール場所を解決できない (ファイルが削除された) パッケージは スキップされます。これは、ID だけでは所有権の証明ではないためです。両方が設定した 2 つのアプリ #:property WinAppPackageName=counter 異なるフォルダーから同じ ID を登録します。 --pruneを使用して、ファイルがなくなった登録をクリアします。
• 一致するパッケージの登録を解除します

配信不能登録のクリーンアップ (--prune):

登録は、そのファイルの有効期限を上回ります。 ビルド出力、プロジェクト ツリー、または (ファイル ベースのアプリの場合) を削除すると、Windows%LOCALAPPDATA%\Tempが消去され、パッケージは登録されたままになります。Windows ID とその [スタート] メニュー エントリは保持されますが、アクティブ化では何も行われません。 これらは目に見えないほど蓄積されます。

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

開発モードの登録のみが考慮され、それぞれが完全なパッケージ名で削除されるため、同じ名前のパッケージが引き続きライブの場所からインストールされます。 インストール場所が見つからないのは 、通常 は削除されたフォルダーですが、切断されたネットワーク共有またはリムーバブル ドライブから登録されたパッケージについても説明しているため、プロンプトが表示されます。確認する前に一覧を確認してください。

例:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

---

cert

開発用証明書を生成、検査、インストールします。

証明書の生成

パッケージ署名用の開発証明書を生成します。

winapp cert generate [options]

オプション:

• --manifest <Package.appxmanifest>- マニフェストのIdentity/@Publisherから証明書publisherを抽出します。 発行元のみが必要であるため、部分的に完全なマニフェストは引き続き機能します。 マニフェストに使用可能な発行元がない場合、コマンドは既定値を置き換える代わりに失敗するため、証明書でマニフェストが暗黙的に一致しなくなります。
• --publisher <name>- 証明書のPublisher。 証明書を生成する場合、このオプションは --manifestよりも優先されます。マニフェスト発行元を使用する代わりに、明示的に空の値が失敗します。 完全な X.500 識別名 (例: CN=Contoso, O=Contoso Ltd, C=US) またはベア名を受け取り、 CN=<name>として自動的にラップされます。 コンポーネントは、単一値とコンマ区切りである必要があります。MSIX マニフェストパブリッシャーはそれらを表すことができないため、複数値の RDN (CN=Foo+OU=Bar) と円記号はサポートされていません。 形式が正しくない識別名 ( CN= や CN=A,,O=Bなど) は、マニフェストの発行元と一致しない証明書を生成するのではなく、ゼロ以外の終了と問題の名前付けのエラーで拒否されます。
• --output <path> - 出力証明書ファイルのパス (絶対パスと相対パスをサポート)
• --password <password> - 証明書パスワード (既定値: password。これは一般に知られています。 JSON 出力 と セキュリティに関するページを参照)
• --valid-days <valid-days> - 証明書が有効な日数 (既定値: 365)
• --install - 生成後にローカル コンピューター ストアに証明書をインストールする
• --if-exists <Error|Overwrite|Skip> - 証明書ファイルが既に存在する場合の動作を設定する (既定値: エラー)
• --export-cer - .cer ファイル (公開キーのみ) を .pfxと共にエクスポートします。 信頼インストール用にパブリック証明書を個別に配布する場合に便利です。
• --json - プログラムで使用するために出力を JSON として書式設定します。 エラーは JSON ({"error": "..."}) としても返されます。

JSON 出力:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher は表示名で、証明書が発行された完全な識別名を subjectName します。 defaultPasswordIsPublic は常に存在します。 trueされると、.pfxは誰でも推測できるパスワードによって保護されるため、証明書は自分のマシン上に留まるビルドにのみ署名する必要があります。スクリプトが証明書を他の何かに手付ける前に確認してください。 warnings は、テキストと同じ開示を行い、報告するものがない場合は省略されます。 publicCertificatePath は、 --export-cerでのみ表示されます。

証明書情報

PFX または CER ファイルからの証明書の詳細を表示します。 署名する前に、証明書がマニフェストと一致することを確認するのに役立ちます。

winapp cert info <cert-path> [options]

引数:

• cert-path - 証明書ファイルへのパス (PFX または CER)

オプション:

• --password <password> - PFX ファイルのパスワード。パブリック CER の場合は無視されます (既定値: "password")
• --json - 出力を JSON として書式設定する

証明書のインストール

コンピューター証明書ストアに証明書をインストールします。

winapp cert install <cert-path> [options]

引数:

• cert-path - インストールする証明書ファイルへのパス

例:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

---

標識

証明書を使用して MSIX パッケージと実行可能ファイルに署名します。

winapp sign <file-path> <cert-path> [options]

引数:

• file-path - 署名する MSIX パッケージまたは実行可能ファイルへのパス
• cert-path - 署名証明書へのパス (.pfx)

オプション:

• --password <password> - 証明書パスワード (既定値: "password")
• --timestamp <url> - RFC 3161 タイムスタンプ サーバー URL

例:

# Sign MSIX package
winapp sign MyApp.msix ./mycert.pfx

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

---

az-sign

Azure の信頼された署名を使用してファイル (exe、MSIX、または MSIX バンドル) をコード署名します。これはクラウドで管理される署名 ID であるため、ローカル コンピューターに秘密キー (PFX) は存在しません。

winapp az-sign <file-path> [options]

引数:

• file-path - 署名するファイルへのパス (exe、msix、または msixbundle)

オプション:

• --subscription、-s - 使用するサブスクリプション ID をAzureします。 指定されておらず、複数のサブスクリプションが存在する場合は、メッセージが表示されます
• --resource-group、 -r - 署名アカウントを絞り込むリソース グループ
• --account - 署名アカウント名。 で使用する必要があります。 --resource-group
• --profile、 -p - 証明書プロファイル名。 で使用する必要があります。 --account
• --metadata-file、 -m - 既存の metadata.jsonへのパス。 リソースの検出とアカウント/プロファイルの選択プロンプトをスキップし、直接署名します。 非対話型のAzure資格情報は既に使用できる必要があります。CLI は対話型のテナント プロンプトまたはaz loginにフォールバックできますが、npm プログラム API は常に非対話型であり、プロンプトを表示する代わりに失敗します

認証:

az-signは、Azureの標準資格情報チェーン (DefaultAzureCredential) を使用します。 CI/CD の場合は、AZURE_TENANT_ID、AZURE_CLIENT_ID、およびAZURE_CLIENT_SECRETを設定します (または、OIDC/マネージド ID GitHub Actions使用します)。 既存のAzure CLI セッション (az login、azure/login GitHub アクションを含む) も任意の環境で受け入れられます。 資格情報が見つかり、セッションが対話型の場合にのみ、az loginaz-sign起動します。

前提条件:

• Azureコード署名アカウントと証明書プロファイル (ID 検証後にAzure ポータルで作成)、および ID に割り当てられたコード署名証明書プロファイル署名者ロール。 詳細なガイダンスについては、アーティファクト署名のクイックスタート ドキュメントAzure参照してください。
• マシン全体の x64 .NET 8 (またはそれ以降) のランタイムがインストールされています。 Azure署名クライアント ライブラリは、別のプロセスで読み込まれるsigntool.exeマネージド アセンブリです。winapp 独自の自己完結型ランタイムは、それを満たしていません。 ランタイム読み込みエラーで署名が失敗した場合は、 https://dotnet.microsoft.com/download からインストールします。
• Microsoft Visual C++ 再頒布可能パッケージ (x64) です。 Azure署名クライアント ライブラリは VC++ ランタイムに依存し、winapp は公式のクライアント ツール インストーラーではなく生の NuGet パッケージをダウンロードするため、この依存関係は自動的にはインストールされません。 クリーンなマシンは、.NETと SignTool が存在する場合でも読み込み失敗する可能性があります。 https://aka.ms/vs/17/release/vc_redist.x64.exeから最新の x64 再頒布可能パッケージをインストールします。0xc000007b、"アプリケーションが正しく起動できませんでした"、または dlib の DLL エラーが発生して署名に失敗した場合。

最小特権 CI: 自動検出 (サブスクリプション、リソース グループ、アカウント、プロファイルの一覧表示) には、親スコープでの読み取りアクセスが必要です。 すべてのコレクション一覧の呼び出しを回避するには、親コレクションを列挙するのではなく、--subscription、--resource-group、--account、--profileの 4 つすべてを渡します。az-signは、親コレクションを列挙するのではなく、直接リソース読み取り (各名前付きリソースの GET) を使用してアカウントとプロファイルを検証するため、プリンシパルスコープはそのアカウントとプロファイルだけで十分です。 いずれか 1 つを省略すると、リスト呼び出しが再び導入されます。たとえば、 --subscription を省略すると、ID がアクセスできるサブスクリプション az-sign 一覧表示されます。これは、狭いスコープのプリンシパルでは許可されない可能性があります。 1 つの証明書プロファイルのみをスコープとするプリンシパルは、事前に生成された --metadata-file (アカウント エンドポイントとプロファイルを直接指定) を渡すことによって、検証を完全にスキップできます。

例:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

---

create-external-catalog

指定したディレクトリから実行可能ファイルのハッシュを含む CodeIntegrityExternal.cat カタログ ファイルを生成します。 このカタログは、パッケージ自体に含まれていない外部ファイルの実行を許可するために、MSIX スパース パッケージ マニフェスト (AllowExternalContent) の TrustedLaunch フラグと共に使用されます。

これは、MSIX パッケージに署名するときにsigntool.exeAppxMetadata\CodeIntegrity.catを作成する方法と似ていますが、スパース/外部の場所パッケージで使用する外部カタログを生成します。

winapp create-external-catalog <input-folder> [options]

引数:

• input-folder - 処理する実行可能ファイルを含む 1 つ以上のディレクトリ。 複数のディレクトリをセミコロンで区切ります (例: "dir1;dir2")

オプション:

• --recursive、 -r - サブディレクトリからファイルを含める
• --use-page-hashes - カタログの生成時にページ ハッシュを含める (ページごとのハッシュ データを含むより大きなカタログが生成されます)
• --compute-flat-hashes - カタログの生成時にフラット ファイル ハッシュを含める
• --if-exists <Error|Overwrite|Skip> - 出力ファイルが既に存在する場合の動作 (既定値: Error)
• --output、 -o - 出力カタログ ファイルのパス。 指定しない場合、 CodeIntegrityExternal.cat は現在のディレクトリに作成されます。 ディレクトリを指定すると、既定のファイル名が追加されます。

実行内容:

• 指定されたディレクトリで実行可能ファイルをスキャンします (コード セクションを含む PE バイナリ)
• 見つかったすべての実行可能ファイルのハッシュを含むカタログ定義ファイル (CDF) を生成します
• CryptoCAT API Windows使用して、.cat カタログ ファイルを生成します
• 実行可能でないファイル (コード セクションのない .txt、 .dll など) は自動的にスキップされます

例:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

使用するタイミング:

このコマンドは、TrustedLaunch を使用して外部実行可能ファイルを検証するスパース MSIX パッケージをビルドするときに使用します。 一般的なワークフローは次のとおりです。

1. winapp manifest generate --template sparse — スパース マニフェストを作成する AllowExternalContent
2. winapp create-external-catalog ./bin — アプリの実行可能ファイルのコード整合性カタログを生成する
3. winapp pack — マニフェスト、資産、カタログを MSIX にパッケージ化する

---

ツール

Windows SDK ツールを直接Accessします。 Microsoft.Windows で使用できるツールを使用します。Sdk。BuildTools

winapp tool <tool-name> [tool-arguments]

使用可能なツール:

• makeappx - アプリ パッケージの作成と操作
• signtool - ファイルに署名して署名を確認する
• mt - サイド バイ サイド アセンブリのマニフェスト ツール
• Microsoft.Windowsの他のWindows SDK ツール。Sdk。BuildTools

例:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

署名の検証

ビルド ツールは NuGet からダウンロードされてから実行されるため、winapp は実行する直前に有効な Microsoft Authenticode 署名を確認します。 証明書には、署名組織として Microsoft Corporation という名前を付けなければなりません。 これは、 tool、 package、 signなど、SDK ツールにシェルで出力されるすべてのコマンドに適用されます。 チェックに失敗したツールは実行されません。

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

ここでエラーが発生した場合、ディスク上のファイルは公開Microsoftものではありません。ほとんどの場合、破損または部分的なダウンロードです。 NuGet キャッシュからパッケージを削除し、コマンドをもう一度実行して、winapp で再ダウンロードします。

winapp はその後、ツールを実行している間は開いたままにするため、チェックしたファイルは読み込まれるファイルWindows。 ツールを所定の位置に保持できない場合は、次のいずれも実行されません。

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

ウイルス対策スキャンや開いているエディターなど、ファイルを使用しているものを閉じてから、コマンドをもう一度実行します。 ツールが使用されなくなった場合は、NuGet キャッシュからパッケージを削除して、winapp で再ダウンロードします。

---

保存する

Microsoft Store Developer CLI コマンドを実行します。 このコマンドを実行すると、Microsoft Store Developer CLI がまだダウンロードされていない場合はダウンロードされます。 Microsoft Store Developer CLI の詳細を確認します。

winapp store [args...]

引数:

• args... – msstore CLI に直接渡す引数。 使用可能なコマンドとオプションについては、 MSStore CLI のドキュメント を参照してください。

実行内容:

• Microsoft Store Developer CLI (msstore) がダウンロードされ、システムで使用できることを確認します。
• すべての引数を msstore CLI に転送します。
• ターミナルで出力を示すコマンドを直接実行します。

例:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

---

get-winapp-path

インストールされている Windows SDK コンポーネントへのパスを取得します。

winapp get-winapp-path [options]

返される内容:

• ワークスペース ディレクトリへのパス.winapp
• パッケージ インストール ディレクトリ
• 生成されたヘッダーの場所

---

ターゲット

コマンドの実行、ファイルのコピー、状態の検査、またはゲスト デスクトップ全体のキャプチャ。

すべての動詞は、最初の引数として sandbox を受け取ります。 snapshotを除き、これらのコマンドはサンドボックスを準備または開始できます。 前提条件、アクセス許可、ライフサイクル、回復については、「Windowsサンドボックスの実行」を参照してください。

target exec

ゲスト ユーザーとしてコマンドを実行します。

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

--後の引数は、その境界を保持します。 標準ストリームとゲスト プロセスの終了コードが転送されます。これは完全なターミナルではありません。 --json は、子コマンドの stdout を変更せずに stderr で winapp エラーをフォーマットします。 構造化 error.code を使用して、ターゲット障害とアプリケーション独自の終了状態を区別します。

明示的な WINAPP_UI_WORKFLOW_ID では、コマンドによって行われたゲスト UI 呼び出しもグループ化されます。 サンドボックス UI の調整を参照してください。

ターゲット プッシュとターゲット プル

動詞で指定された方向にファイルまたはディレクトリをコピーします。

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

ターゲット パスは、ターゲットのマネージド作業領域に対する相対パスです。絶対パス、ルートパス、UNC ターゲット パスは拒否されます。 ファイル変換先には、そのファイル名が含まれます。 ディレクトリー・レイアウト、リンク処理、およびコピーされたスクリプトの実行については、コマンドの実行と ファイル のコピーを参照してください。

ターゲット スナップショット

サンドボックスを起動せずに、準備状況、デプロイ、およびゲスト ウィンドウをレポートします。

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

クライアントの再接続やエージェントの修復は行われません。 実行中のサンドボックスは正常な結果ではなく、エラーではありません。 準備とプロセス ID の解釈については、 サンドボックスの検査 を参照してください。

ターゲットのスクリーンショット

アプリ セレクターまたはホスト ウィンドウの境界線を使用せずに、ネイティブ ピクセル サイズでゲスト デスクトップをホスト PNG としてキャプチャします。 --json は、ゲスト座標の原点を報告します。

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

代わりに、アプリ ウィンドウに ui screenshot --on sandbox -a <app> を使用します。 クライアント要件、フォーカスの制限事項、出力処理については、 スクリーンショットと記録 を参照してください。

ターゲット レコード

ゲスト デスクトップを H.264 MP4 に記録します。 ホストビデオとフレームファイルは、記録が完了した後に到着します。JSON とフレーム マニフェストは、スケーリングまたはパディングを記述します。

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

ui recordの期間、フレーム、上書き、結果のオプションを使用しますが、1 つのアプリではなくデスクトップをキャプチャします。 無人 CLI を使用するには肯定的な --duration-sec を使用します。npm ヘルパーには durationSecが必要です。 部分的な証拠とキャプチャの準備エラーについては、「 サンドボックス キャプチャ」を参照してください。

---

find-ui

エージェント優先。 find-ui は主に AI コーディング エージェント用に構築されています。これにより、エージェントは実際にプルし、それを発明する代わりに出荷ギャラリーから WinUI マークアップをコンパイルし、 --json すべての結果 (およびすべての失敗) のマシンを読み取り可能にします。 それは手で入力されたのと同じように機能します。

動作するコード例については、 WinUI コントロールとサンプルを検索します。 WinUI のみ: コーパスは WinUI 3 ギャラリーと Windows Community Toolkit (さらにいくつかのキュレーションされたコア パターン) であり、WPF、WinForms、またはその他の UI フレームワークについては説明しません。 3 番目のソースである microsoft-ui-reactor ReactorGallery は オプトインです。これは通常の検索から除外され、 --source reactor を渡したときにのみ検索されます (C#のみの宣言型サンプルは標準の XAML アプリに貼り付けないため、Reactor/MVU プロジェクトをビルドするときにのみアクセスします)。

winapp find-ui "<query>" [options]

ギャラリー、ツールキット、および Reactor コーパスは CLI 内に付属しているため、 find-ui は、エージェント サンドボックスでの最初の実行や、 raw.githubusercontent.comをブロックする企業プロキシの背後など、ネットワーク アクセスなしで動作します。 GitHubに到達すると、CLI はそこから更新し、ユーザーごとの結果を <global .winapp>/cache/find-ui の下にキャッシュします。組み込みのコーパスは床のみで、上限は決してありません。 キャッシュされたデータは、最大で 24 時間ごと、または --refreshを使用してオンデマンドで更新されます。

組み込みのコーパスは、安定したリリースがビルドされるたびにGitHubから再フェッチされ、失敗した更新は古いデータを静かに出荷するのではなく、リリース ビルドを停止します。ベイカーは--refresh同じコード パスを介してフェッチするため、障害が発生するとライブ更新も壊れ、出荷前に調査する価値があります。 以前にコミットされたコーパスに対してリリースを切り取ることができますが、明示的なオーバーライドとしてのみ可能です。 結果が Gallery/Toolkit/Reactor コーパスの組み込みコピーから提供されると、stderr と--json出力にfind-uiが"corpus": "embedded" (その他の値: 新しいフェッチの"network"、ローカル キャッシュの"cache") が実行されます。 コアのみの要求 ( --source core、またはすべてのコア パターンである --id セット) は、キュレーションされたコア パターンが CLI にコンパイルされ、フェッチされないため、 "embedded" も報告されます。 --refresh 変更できないため、制約の通知は出力されません。 corpus フィールドは、結果が提供されるたびに報告されます。コーパスをまったく読み込めなかった場合にのみ存在しません。

オプション:

• --id <id> - コードをフェッチします (Gallery/Toolkit は XAML または C# を返します。Reactor は C#専用です。また、以前の検索 (例: gallery-tabview-1) の 1 つ以上のシナリオ ID の前提条件に関する注意事項です。 再現。 ID では大文字と小文字が区別されません。GALLERY-TABVIEW-1gallery-tabview-1と同じように解決されます。
• --list - 検索ではなく、検出可能なすべてのコントロール/サンプル ID を一覧表示します (ギャラリー + ツールキット + コア。オプトイン Reactor ソースは除外されます)。
• --source <gallery|toolkit|reactor|core> - 検索結果を 1 つのソースに制限します。 (検索のみ — --list/--idでは無効です。 リアクタはオプトイン であり、通常の検索から除外されるため、 --source reactor を検索する唯一の方法です。
• --max <N> - 返される一致するコントロールの最大数 (既定値: 3)。 検索にのみ適用されます。は --list/--idで無視されます。
• --refresh- ローカル キャッシュをバイパスし、GitHubから WinUI コーパスを再フェッチします。
• --json - 構造化された JSON を出力します (エージェントに優しい)。 検索の場合、各一致には、シナリオごとのidとheaderを保持するエントリを含むsource、control、score、description、およびscenarios配列が含--id完全なコードが含まれます。 --jsonエラー (整数以外の--maxなどの引数/パーサー エラーを含む) は stdout のフラット {"error": "..."} オブジェクトとして出力されるため、出力はコンピューターで読み取り可能なままです。

ワークフロー: 適切なコントロールとそのシナリオ ID をコンパクトに検索し、 --idとの最適な一致を得るために完全なコードをフェッチします。

例:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

関連:find-uiWinUI サンプルを検索します。find-apiを使用して、プロジェクト参照の API サーフェス (型、メンバー、列挙型) を検索し、実行中のアプリの UI ツリーを検索するためのwinapp ui searchを使用します。

---

find-api

エージェント優先。 find-api は主に AI コーディング エージェント用に構築されています。API サーフェスで生成されたコードは、プロジェクトがモデルの回想ではなく実際に参照し、 --json と、不足しているシンボルにゼロ以外の終了コードを加えて、エージェントが回答に codegen をゲートできるようにします。 それは手で入力されたのと同じように機能します。

参照されている.winmd/.dllメタデータから解決された、プロジェクトで使用できるWindows/WinRT API サーフェス (型、メンバー、列挙型、名前空間) を検索して調べます。 ベア フォーム検索。サブ動詞は、特定の型、名前空間、またはインデックス自体にドリルダウンします。

winapp find-api "<query>" [options]
winapp find-api [command] [options]

インデックスは、最初の使用時に( project.assets.jsonを介して) プロジェクトの復元された NuGet/SDK パッケージから構築され、プロジェクトが復元されたときに自動的に更新されます。 グローバル .winapp キャッシュ (cache/find-api/) の下に存在し、プロジェクト間で共有されます。 最初にプロジェクトを復元します (winapp restore または dotnet restore)。

各一致は、その名前空間の下に、パッケージに付属するパッケージとそれが行う内容の 1 行の概要と共に一覧表示されるため、2 つ目の members 呼び出しなしで結果を使用できます。

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

--verboseを追加して、各名前空間をバックアップするディスク上のキャッシュ ファイルも出力します。これは、古いインデックスまたは予期しないインデックスを診断するときに便利です。

クエリなしで winapp find-api を実行すると、短い使用状況の概要が出力され、 0 が終了します。これは、何も見つからなかった検索ではなく、ヘルプの要求です。

スコープ。 すべての回答は、--jsonでscopeとして報告され、テキスト出力のメモとして報告される、厳密に 1 つのスコープから取得されます。

• project - 現在のディレクトリ内のプロジェクト (または --project / --project-dir)。 Windows SDK、Windows アプリ SDK、およびプロジェクト独自の NuGet パッケージについて説明します。 Windows アプリ SDKメタデータは、プロジェクトが参照するリリースです。コンピューターに新しいWindows アプリ ランタイムがインストールされている場合は、プロジェクトがコンパイルできない型を確認するのではなく、警告を表示して残find-api。
• sdk- マシン全体の Windows SDK + Windows アプリ SDK メタデータ。現在のディレクトリにプロジェクトがなく、ソリューションがない場合に自動的に使用されます。 これにより、 find-api プロジェクトが存在する前に API を探索でき、ネットワーク アクセスは必要ありません。 サードパーティの NuGet パッケージは意図的に含 まれていない ため、Community Toolkit の型はこのスコープでは見つかりません。

プロジェクトがなく、ソリューションがないディレクトリからのクエリは、sdkスコープによって常に応答されます。つまり、共有キャッシュ内のどのプロジェクトのインデックスが作成されることもありません。そのため、結果は関連のないグローバル状態に依存することはありません。 --project sdk渡してプロジェクト内から明示的に SDK スコープを選択し、新しい Windows SDK をインストールした後に再構築winapp find-api refresh --project sdk。

ソリューション ディレクトリ。 プロジェクト ファイルが横に存在しない .sln/.slnx を保持するディレクトリから、ソリューションによって sdk スコープではなく回答がビルドされます。これらはオンデマンドでインデックスが作成されるため、NuGet パッケージが含まれます。 ソリューションが複数のインデックス付きプロジェクトをビルドすると、クエリはそれらを一覧表示し、1 つ選択するのではなく、 --project <name> を要求します。

コマンド：

• (ベア)find-api "<query>" ["<query>"...] - 名前空間別にグループ化された、ドキュメント化された概要にフォールバックする、検索の種類とメンバー名
• members <type> [<type>...] [--filter <text>] - 型のプロパティ、イベント、およびメソッドを一覧表示します (シグネチャを持つ宣言されたメンバー、型の宣言によって要約された継承されたメンバー)
• check-property <type> <property> [<property>...] - プロパティが型に存在するかどうかを検証します (存在しない場合は 0 以外を終了します)。 読み取り専用プロパティは、プレーンな✅ではなく、⚠️ と "読み取り専用、割り当てることができません" で報告されるため、ActualWidthなどのプロパティは設定できるものと間違われません。 プロパティ名は大文字と小文字が 区別されます。C# と XAML は次のようになります。 check-property Button background は 0 以外を終了し、実際に書き込むことができない名前を報告するのではなく、近い一致として Background を提供します。
• enums <type> [<type>...] [--filter <text>] - 列挙型の値を一覧表示します (型が列挙型でない場合は 0 以外を終了します)
• packages - インデックス付きメタデータ パッケージを、パッケージごとの種類/メンバー数で一覧表示する
• stats - 集計インデックス統計 (パッケージ、名前空間、型、メンバー、 .winmd ファイル) を表示する
• refresh [--scan] - プロジェクトのインデックスを再構築します (--scan ディレクトリの下のすべてのプロジェクトにインデックスを作成します)。 --project <name>では、現在のディレクトリのインデックスを作成する代わりに、インデックスが作成された 1 つのプロジェクトと一致しない名前が失敗します。

Batching.search、members、enums、check-propertyは、1 回の呼び出しで複数のサブジェクトを受け入れます。 AI エージェントの場合、これは 1 つの最大のコスト レバーです。ルックアップの限界コストは、ペイロードのサイズではなく、ラウンド トリップ (各呼び出しが会話全体を再送信) によって支配されるため、10 回の質問に回答する 1 つの呼び出しは 10 回の呼び出しよりもはるかに安くなります。

• 1 つの件名は、テキストと--jsonの両方で、常に持っているペイロードの形状を正確に返します。
• 2 つ以上の件名がエンベロープを返します。各要素が通常の単一サブジェクト ペイロードである--jsonに{ "count": N, "results": [ ... ] }します。check-propertyはmissingCountを追加します。 テキスト出力では、各サブジェクトが 1 つのスコープ ヘッダーの下に順番にレンダリングされます。
• check-property 1 つの型のプロパティをバッチ処理します。最初の引数は型であり、プロパティの後のすべての引数です。 バッチ モードでは、存在するプロパティは 1 つの ✅ 行を出力します。完全なニアミスの詳細は、印刷されないものにのみ出力されます。
• バッチは、すべてのサブジェクトが解決され、検出された場合にのみ0終了します。そのため、バッチは引き続き codegen をゲートできます。

検索ランキング。 型名と完全に一致するクエリは部分一致よりも優先され、短い名前が複数の名前空間によって共有される場合、厳密な名前の競合のみがあいまいとして表示されます。 NavigationView のようなクエリでは、同じ名前のシンボルを含むすべての名前空間ではなく、その厳密な型を定義する少数の名前空間が報告されます。 あいまいさリストは --maxに従い、通常の結果は引き続きその下に出力されます。

names.members、 check-property、および enums は、短い名前 (NavigationView) または完全修飾名 (Microsoft.UI.Xaml.Controls.NavigationView) を受け入れます。 短い名前が最新のMicrosoft.*型とそのレガシ Windows.* UWP ツインによって共有されている場合、Microsoft.*型は、Windows アプリ SDK アプリが使用するプロジェクションと答え、解決された完全修飾名が常に表示されます。 その他の競合は 0 以外で終了し、推測の代わりに候補が一覧表示されます。

メソッド シグネチャ。 シグネチャは、呼び出しを記述する方法で出力されます。インスタンスではなく型に対して呼び出すメソッドは staticと共に表示され、参照渡しパラメーターは実際に必要なキーワード ( out、 in、または ref) と共に表示されます。 そのため、 TryGetValue は Boolean TryGetValue(String key, out String value)を読み取ります。これは、書き込まれたとおりにコンパイルされます。

オプション:

• --max <n> - 名前空間でグループ化された検索結果の最大数 (既定の 5; 検索のみ)。 また、あいまいさの一覧を大文字にするため、多くの名前空間間で競合する短いクエリは読み取り可能なままです。
• --filter <text> - members と enumsの一覧を絞り込む: メンバー/値名に対して 大文字と小文字を区別しない部分文字列 の一致。 数百人のメンバーを持つ型で最もよく使用されます。 ほとんどの列挙型は、全体をダンプするのに十分な小ささ ( Symbol、WinUI では 197 の値で最も大きい) ため、通常、それらをフィルター処理すると、2 番目の推測を考慮すると節約されるよりもコストがかかります。 異なるフィルター テキストで同じコマンドを再実行しないでください。1 回ダンプして読み取る。
• --all - members、完全な画面を一覧表示します。継承されたメンバーの完全なシグネチャに加えて、依存関係プロパティ識別子の静的な説明とメンバーごとの説明が含まれます。フィルター処理されていないリストはすべて省略されます (以下の リスト サイズ を参照)。 --verboseは、それを意味します。--verboseと組み合わせることができない--jsonも必要な場合は、--allを使用します。
• --scan - ディレクトリの下のすべてのプロジェクトを再帰的に検出してインデックスを作成する (refresh のみ)
• --project <name>- クエリを実行するProject (.csproj/.vcxproj名と一致する)、sdkしてマシン全体のWindows SDK スコープに対してクエリを実行する
• --project-dir <path>- クエリするディレクトリProjectします (既定値は現在のディレクトリ)。 存在しないパスはエラーであり、 sdk スコープから暗黙的に応答されることはありません。
• --json - stdout でマシンが読み取り可能なペイロードを出力します (すべての動詞でサポートされます)。 クエリ ペイロードは、 scope (project または sdk)、 projectName、および projectDir (SDK スコープでは存在しません) を介して応答したインデックスを識別します。プロジェクト名はディレクトリ間で一意ではないため、 projectDir は信頼できる ID です。 --jsonエラー (整数以外の--maxなどの引数/パーサー エラーを含む) は stdout のフラット {"error": "..."} オブジェクトとして出力されるため、出力はコンピューターで読み取り可能なままです。

例:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

--filterが適用された場合でも、フィルター処理されていない合計 (totalValues、または--jsonのtotalProperties/totalEvents/totalMethods) が出力に報告されるため、狭いビューが小さな API と誤解されることはありません。 何も一致しないフィルターは引き続き 0 終了し、明示的に言います。つまり、"そのような型はありません" ではなく、"フィルターに一致するものはありません" です。

リスト のサイズ。 フィルター処理されていない members リストは、コストの高い 1 つの図形です。 members Button は 288 個のメンバーをカバーし、そのうち 280 個は 6 つの基本型から継承されます。 フィルター処理されていない呼び出しは 方向 クエリ ("この型は何ですか、大まかに何ができるか?") であるため、それに答え、何も書き込まれなかった部分は省略されます。

• 継承されたメンバーシグネチャ — 継承されたメンバーは型を宣言することによってグループ化され、 名前のみで一覧表示されるため、継承されたサーフェスの形状は 280 個の完全なシグネチャなしで表示されます。
• 依存関係プロパティ識別子 (BackgroundProperty) - 一般的な WinUI コントロールのプロパティの 28%。 これらは、割り当てられず、 GetValue/SetValueに渡される必要があります。
• メンバーごとの説明 — ペイロードの約 16% の XML ドキュメント 散文。
• --json内の周囲に示されるフィールド: kind (properties/events/methods配列を含む)、returnType (signatureの先頭トークン)、および false (declaringType によって暗黙的に示される) inherited。

省略されたものは常に報告され (hiddenDependencyProperties、descriptionsOmitted、--jsonではhint、テキストでは "省略:" 行)、合計では型全体が記述されます。 --filterと--allの両方で完全な署名と説明を含む完全なサーフェスが表示されるため、members Button --filter BackgroundPropertyは引き続き識別子を検索し、members Button --filter Clickは引き続きClick継承された署名を返します。 samples/winui-appで測定すると、これは 91,954 から 10,567 文字 (−88.5%) のmembers Button --jsonを受け取り、--filterとバイト同一--all残します。

クエリの照合方法。 winapp find-api "language model" 上記 LanguageModel ランクは、型のインデックスが作成されるときにプロジェクトの外部を含め、名前空間とメンバーに単語が分散している単語と一致します。 検索は構文的であり、セマンティックではありません。文字の実行ではなく識別子の単語全体と一致するため、 llm は IImageLLMAdapterSession を検索しますが、 ScrollModeは検索しません。 クエリが名前と一致しない場合、型とメンバーの文書化された概要に対してクエリが試行されます。これにより、IRandomAccessStream"random-access stream"検索できます。 説明は一致するすべての名前の下にランク付けされ、パッケージが実際に出荷される要約のみが検索可能です。XML ドキュメントのないパッケージでは説明テキストは提供されません。

MSBuild プロジェクト ファイルのないプロジェクト。 Electron アプリ (またはwinapp.yamlによって駆動されるその他の.NET以外のアプリ) には.csprojがないため、project.assets.jsonはありません。 find-apiは、書き込みwinapp restore.winapp/winmds.lock.jsonからインデックスを作成します。これは、解決された各パッケージ、そのバージョン、およびそれが提供する.winmd ファイルと同じものを記録します。 このようなプロジェクトは、そのディレクトリの名前が付けられ、ロックファイルが書き換えられたときにインデックスが古くなります。 .csprojとwinapp.yamlの両方を保持するディレクトリは、プロジェクトのコンパイル対象をより正確に説明する.csprojからインデックスが作成されます。

負の回答は、インデックスが不完全な場合に修飾されます。 パッケージのメタデータを読み取ることができなかった場合、"そのような型はありません" と "そのパッケージはインデックスが作成されませんでした" は同じに見え、実際に 2 番目のパッケージが存在しないと言われた API に対してコードが生成されたときに最初に動作します。 したがって、0 個の結果を返す search を含め、すべての否定的な回答には、インデックスが部分的であり、 winapp find-api refreshを指していることを示すメモが含まれます。 肯定的な回答は影響を受けません。

ジェネリック型名。 メタデータには、アリティ サフィックス (IAsyncOperation`1) を持つジェネリック型が格納されます。これは、誰もが書き込む方法ではありません。 members、 enums、および check-property は、すべてのフォーム ( IAsyncOperation、 IAsyncOperation<StorageFile>、 IAsyncOperation`1 すべて同じ型に解決) を受け入れます。 ベア名は、すべてのアリティと一致します。指定されたアリティ (どちらの表記でも) が一致する必要があるため、 Holder<A, B> は単一パラメーターの Holder<T>に解決されません。

--json ペイロードは診断を省略します。 キャッシュ ファイルのパスは --verbose の下にのみ表示され (テキスト出力と一致し、既に詳細のみでした)、空の検索候補配列は []としてシリアル化されるのではなく省略されます。

終了コード:search ヒットがない場合は、不足しているプロパティに check-property し、列挙型以外の型で enums すると、すべてゼロ以外の終了コードの生成と CI チェックが行われます。 バッチ呼び出しは、 いずれかの サブジェクトが失敗した場合、0 以外で終了します。 読み取り専用プロパティはエラーではないため、check-propertyは0を終了して出力にフラグを設定します (--jsonのwritable: false)。 initプロパティは、同じ理由でwritable: false報告します。これはオブジェクト初期化子で設定でき、そのシグネチャには{ get; init; }と表示されますが、後で割り当てることはコンパイルされません。

関連:find-api "この API は存在し、そのメンバーは何ですか?"と答えます。 find-ui を使用して、コントロールの動作する WinUI サンプルを見つけます。

---

node generate-bindings

(NPM パッケージでのみ利用可能)Windows アプリ SDK API の JS バインドを生成します。 バインドは、"winapp": { "jsBindings": {...} }のpackage.json名前空間によって宣言され、.winapp/bindings/に書き込まれます。

npx winapp node generate-bindings [options]

オプション:

• --verbose、 -v - ファイルごとの詳細な codegen 出力を有効にする
• --quiet、 -q - 進行状況と情報出力を抑制する

実行内容:

• winapp.jsBindingsからpackage.json ブロックを読み取り、最後のwinmds.lock.jsonによって書き込まれたwinapp restoreを読み取り、型指定された.js + .d.tsバインドを出力します。.winapp/bindings/
• を変更package.json。パッシブ再生成プログラムです。 winapp.jsBindings ブロックと @microsoft/dynwinrt ランタイム依存関係の追加は、JS バインドが有効になっているwinapp init中に発生します。ブロックが存在しない場合、このコマンドは高速で失敗します
• 依存関係に@microsoft/dynwinrtが見つからない場合は警告 (書き込みは行いません) - npm install追加した後init実行します

注

バインドは npm のみ であり、 npx winapp ( @microsoft/winappcli npm パッケージ) を介した呼び出しが必要です。スタンドアロン winget CLI では表示されません。 このコマンドを使用してバインディングを再生成する前に、 winapp init 対話形式で実行し、オプトインするか、 winapp init . --use-defaults --add-js-bindingsを使用します。 winapp.yamlを編集する場合は、npx winapp restoreを実行して、再生成する前Windows依存関係を更新します。

例:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

エンドツーエンドのワークフローと構成オプションについては、winapp.jsBindingsを参照してください。

---

node create-addon（ノード クリエイト・アドオン）

(NPM パッケージでのみ使用可能) WINDOWS SDK とWindows アプリ SDK統合を使用してネイティブ C++ または C# アドオン テンプレートを生成します。

npx winapp node create-addon [options]

オプション:

• --name <name> - アドオン名 (既定値: "nativeWindowsAddon")
• --template - アドオンの種類を選択します。 オプションは cs または cpp です (既定値: cpp)
• --verbose - 詳細出力を有効にする

実行内容:

• テンプレート ファイルを使用してアドオン ディレクトリを作成します
• Windows SDK の例を使用して binding.gyp と addon.cc を生成します
• 必要な npm 依存関係 (nan、node-addon-api、node-gyp) をインストールします
• ビルド スクリプトを package.json に追加します

例:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

---

node add-electron-debug-identity

(NPM パッケージでのみ利用可能) スパース パッケージを使用して、Electron 開発プロセスにアプリ ID を追加します。 Package.appxmanifest が必要です ( winapp init を使用して作成するか、持っていない場合は winapp manifest generate します)。

Important

スパース パッケージの Electron アプリケーションには既知の問題があり、アプリが起動時にクラッシュしたり、Web コンテンツがレンダリングされたりする原因となります。 この問題はWindowsで修正されましたが、外部のWindows デバイスにはまだ反映されていません。 add-electron-debug-identityを呼び出した後にこの問題が発生した場合は、 フラグを使用してデバッグ目的--no-sandbox。 この問題は、MSIX パッケージ全体には影響しません。

Electron デバッグ ID を元に戻すには、 winapp node clear-electron-debug-identityを使用します。

npx winapp node add-electron-debug-identity [options]

オプション:

Option	説明
--manifest <path>	カスタム Package.appxmanifest へのパス (既定値: 現在のディレクトリ内の Package.appxmanifest)
--no-install	依存関係をインストールまたは変更しないでください。Electron デバッグ ID のみを構成する
--keep-identity	パッケージ名とアプリケーション ID に .debug を追加せずに、マニフェスト ID を as-isしたままにする
--verbose	詳細出力を有効にする

実行内容:

• electron.exe プロセスのデバッグ ID を登録します
• Electron 開発で ID が必要な API をテストできるようにします
• ID 構成に既存の Package.appxmanifest を使用します

例:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

---

node clear-electron-debug-identity

(NPM パッケージでのみ利用可能) 元の electron.exe をバックアップから復元して、Electron デバッグ プロセスからパッケージ ID を削除します。

npx winapp node clear-electron-debug-identity [options]

オプション:

Option	説明
--verbose	詳細出力を有効にする

実行内容:

• によって作成されたバックアップから electron.exe を復元します。 add-electron-debug-identity
• 復元後にバックアップ ファイルを削除します
• パッケージ ID なしで Electron を元の状態に戻します

例:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

---

グローバル オプション

すべてのコマンドで、次のグローバル オプションがサポートされます。

• --verbose、 -v - 詳細なログ記録の詳細出力を有効にする
• --quiet、 -q - 進行状況メッセージを抑制する
• --help、 -h - コマンド ヘルプの表示

---

グローバル キャッシュ ディレクトリ

Winapp は、複数のプロジェクト間で共有できるファイルをキャッシュするディレクトリを作成します。

既定では、winapp はグローバル キャッシュ ディレクトリとして $UserProfile/.winapp にディレクトリを作成します。

別の場所を使用するには、 WINAPP_CLI_CACHE_DIRECTORY 環境変数を設定します。

cmd で次の 手順を実行します。

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

PowerShell と pwsh の場合:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

winapp は、 init や restoreなどのコマンドを実行すると、このディレクトリを自動的に作成します。

更新チェック

winapp CLI は、新しいバージョンを定期的にチェックし、更新プログラムが利用可能になったときに 1 行の通知を表示します。 このチェックはバックグラウンドで実行され、コマンドに待機時間は追加されません。

CI 環境 (GitHub Actions、Azure Pipelines など) では、更新チェックが自動的に無効になります。

更新チェックを手動で無効にするには、 WINAPP_CLI_UPDATE_CHECK 環境変数を 0に設定します。

cmd で次の 手順を実行します。

set WINAPP_CLI_UPDATE_CHECK=0

PowerShell と pwsh の場合:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

これを永続的にするには:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

UI ワークフロー ID

winapp ui 物理デスクトップを駆動するコマンドは常に協力的なターンを取るので、一度に実行されている 2 つのワークフローは、互いのフォーカスを盗んだり、互いのメニューを閉じることはできません。 その仲裁はセットアップを必要とせず、オフにすることはできません。

省略可能なのは 、継続性です。 既定では、各コマンドは自己完結型のワンショットであり、完了するとすぐにデスクトップを解放します。 複数のコマンドにわたってデスクトップを保持するには、すべて同じワークフロー ID を指定します。

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

連携するプロセス (記録やキャプチャする必要があるクリックなど) には 同じ 値を使用し、独立したワークフローでは 異なる 値を使用します。 ID のないすべてのコマンドは、1 つのシェルから複数のシェルが起動された場合でも、独自のワンショット ワークフローであるため、コマンドごとに新しいシェルを開始するホストは、それぞれに同じ明示的な値を挿入する必要があります。 値は不透明であり、資格情報として扱われることはなく、SHA-256 ハッシュとしてのみ保持されます。 「UI オートメーション →コンカレント UI ワークフローの調整」を参照してください。

ui

UI オートメーション (UIA) を使用して、実行中Windowsアプリ UI を検査して操作します。

winapp ui [command] [options]

コマンド：

• status - アプリに接続して情報を表示する
• inspect - 要素ツリーの表示
• search - セレクターで要素を検索する
• get-property - 要素のプロパティの読み取り
• get-text / get-value - 要素から値/テキストを読み取ります (TextPattern、ValuePattern、または Name)
• screenshot - ウィンドウ/要素を PNG としてキャプチャする (複数のウィンドウが 1 つの複合 PNG というラベルを付けた形式。 キャプチャ スコープを参照)
• record- ウィンドウ/要素領域を H.264 MP4 ビデオに記録する (Windows グラフィックス キャプチャ + Media Foundation)
• invoke - 要素のアクティブ化 (クリック、切り替え、展開)
• click - マウス シミュレーションを使用して要素をクリックする (呼び出しをサポートしていないコントロールの場合)
• hover - ヒント、ポップアップ、ホバー状態をトリガーする要素にマウスを移動する (既定のドウェル: 800 ミリ秒)
• drag - 要素セレクターまたは画面 x,y 座標 (並べ替え、サイズ変更、スライダー、ドラッグ アンド ドロップ) によって、マウスをあるポイントから別のポイントにドラッグします。
• touch - 要素の中心または画面 x,y 座標に合成タッチ ジェスチャ (タップ、ダブルタップ、長押し、スワイプ、ピンチ、ストレッチ) を挿入する
• pen - 合成ペン/スタイラス入力を挿入する - 構成可能な圧力、傾き、消しゴムモードのタップとインク ストローク
• send-keys - 合成キーボード入力 (名前付きキー、コンボ、生 vk=0xNN、またはリテラル テキスト) をウィンドウに送信する
• set-value - 編集可能な要素 (テキスト、数値) に値を設定します。TextPattern のみのリッチエディット コントロールの LegacyIAccessible put_accValue にフォールバックする
• focus - キーボード フォーカスを移動する
• scroll-into-view - Scroll 要素が表示される
• wait-for - 要素の状態を待機する
• list-windows - アプリのすべてのウィンドウを一覧表示する
• get-focused - 現在フォーカスされている要素を報告する
• yield - 現在のワークフローの UI ターンを解放します。が必要 WINAPP_UI_WORKFLOW_ID

オプション:

• -a, --app <app> - ターゲット アプリ (名前、タイトル、または PID)
• -w, --window <hwnd> - HWND によるターゲット ウィンドウ (安定)
• --on <target>- sandboxでui動詞を実行します。名前、PID、ウィンドウ ハンドルはゲストを参照します。 出力はホストに配信されます。 セットアップ、ワークフローの調整、クライアント要件については、 サンドボックス UI の自動化 に関する記事を参照してください。

ui レコード

ウィンドウまたは要素領域を H.264 MP4 に記録します。

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

レコード オプション:

• --duration-sec <n> - 記録の長さ (秒単位)。 0 レコードを Ctrl + C (既定の 0) まで記録します。
• --fps <n> - キャプチャする 1 秒あたりのフレーム数 (既定の 15)。
• --max-edge <px> - 最も長いエッジが最大でこの数ピクセルになるようにダウンスケールします (0 = ダウンスケールなし)。
• --capture-screen - オーバーレイ/ポップアップが含まれるように画面からキャプチャします (隠れているウィンドウをキャプチャする可能性があります)。
• -o, --output <path> - 出力 .mp4 パス (既定値は recording-<timestamp>-<guid>.mp4)。
• --overwrite - 新しいテイクが完了した後、既存の記録出力を置き換えます。既存の出力は既定で拒否されます。 以前のフレーム バンドルは保持されます。 出力回復の記録を参照してください。
• --frames - タイムスタンプ付き JPAG、 frames.ndjson、および manifest.json を <output-name>.framesに書き込みます。 1 から 30 fps、 --max-edge 64 から 4096 (既定では 1280) をサポートし、1 GiB のフレーム データ上限を備えます。

--jsonの場合、最終的な結果には、出力パス、ディメンション、コーデック、キャプチャ モード、ケイデンス、停止理由、オプションのframeArtifacts、警告が含まれます。

既知の制限事項: 独自の最上位ウィンドウ (WinUI/XAML ポップアップ、教育ヒント、ヒント) でレンダリングされるポップアップ内の 特定の要素 を記録すると、代わりに基になるメイン ウィンドウがキャプチャされる場合があります。 ウィンドウ全体を記録するか、スクリーンショットオーバーレイ ワークフロー に従ってポップアップスチルを表示します。 #646 で追跡されます。

完全なドキュメントについては、 docs/ui-automation.md を参照してください。