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)。 実行時にインストールされたパックに対して検証されます。 winapp new --list を実行してすべてを表示します。 既定値: winui (空のアプリ)。
  • -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 として書式設定する

テンプレート：

テンプレート リストはインストールされているパックからライブで読み取られるので、常に使用しているバージョンが反映されます。 winapp new --list 実行して現在のセットを表示します。 一般的なテンプレート:

短い名前 説明
winui 最小空の WinUI 3 アプリ (MSIX パッケージ)
winui-navview NavigationView スターター アプリ
winui-tabview TabView スターター アプリ
winui-mvvm MVVM アプリ (CommunityToolkit.Mvvm)
winui-lib WinUI 3 クラス ライブラリ
winui-unittest パッケージ化された MSTest アプリ。テストは起動時に実行されます

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

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

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

実行内容:

  • .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

# 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 [options]

オプション:

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

実行内容:

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

注

winapp init で初期化.NETプロジェクトの場合、winapp.yamlはありません。 代わりに、 dotnet restore を使用して NuGet パッケージを復元します。

例:

# Restore from winapp.yaml in current directory
winapp 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 を実行してマニフェストを作成します)

複数の入力フォルダーを渡して、マルチアーキテクチャ配布用の .msixbundle を作成します (以下 のマルチアーキテクチャ バンドルを 参照)。

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

引数:

  • input-folder - パッケージ化するアプリケーション ファイルを含む 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 - 新しい開発証明書を生成する
  • --install-cert - コンピューターに証明書をインストールする
  • --publisher <name>- 証明書の生成にPublisherします。 完全な X.500 識別名またはベア名を受け入れます ( CN=<name>として自動的にラップされます)
  • --self-contained - バンドル Windows アプリ SDK ランタイム
  • --skip-pri - PRI ファイルの生成をスキップする
  • --executable <path> - 入力フォルダーを基準とする実行可能ファイルへのパス ( --exeも指定します)。 マニフェスト内 $targetnametoken$ プレースホルダーを解決するために使用されます。

実行内容:

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

スパース 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 を受け入れます。ベア名は、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)

テンプレート：

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

生成されたマニフェストでは、パッケージ化時に自動的に解決される $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 ファイルは、ソース イメージとして完全にサポートされています。 各ターゲット サイズでベクトルとして直接レンダリングされ、すべての解像度でピクセル完璧な結果が生成されます。

このコマンドは、縦横比を維持しながら画像を比例的に拡大縮小し、必要に応じて透明な背景で中央揃えします。 アセットは、マニフェストの場所を基準にして 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 は、入力から自動的に選択される 2 つのモードのいずれかで動作します。

  • フォルダー モード — 入力はビルド出力フォルダー ( Package.appxmanifest/AppxManifest.xmlを含む) です。
  • Project モード — 入力は、.csproj、.sln/.slnx ソリューション、または 1 つを含むディレクトリです。 winapp run はプロジェクトをビルドして起動し、 パッケージ化された WinUI アプリと パッケージ化されていない WinUI アプリの両方をサポートします。 以下Projectモードを参照してください。

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 - 実行するアプリ: ビルド出力フォルダー (フォルダー モード)、 .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 を使用して現在のターミナルで実行されます。 マニフェストに uap5:ExecutionAlias が必要です ( winapp manifest add-alias を使用して追加します)。 --no-launchと組み合わせることはできません。 --jsonと組み合わせることはできません。
  • --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 を stdout に出力します (または、 --jsonを使用して JSON で出力します)。 --no-launch、--debug-output、--with-alias、または--unregister-on-exitと組み合わせることはできません。
  • --clean - 再デプロイする前に、既存のパッケージのアプリケーション データ (LocalState、設定など) を削除します。 既定では、アプリケーション データは再デプロイ全体で保持されます。
  • --json - プログラムによる使用 (CI/オートメーションなど) 用に出力を JSON として書式設定します。 PID をキャプチャする --detach に便利です。 --with-aliasまたは--debug-outputと組み合わせることはできません。

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

既定では、 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の場合)。

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をオーバーライドします。
  • -f, --framework <tfm> - 複数ターゲット プロジェクトのターゲット フレームワーク モニカー (例: net10.0-windows10.0.26100.0)。
  • --project <name-or-path> - 入力がソリューション (.sln/.slnx) または複数の実行可能なアプリ プロジェクトを含むディレクトリである場合は、起動するプロジェクトを (プロジェクト名またはパスで) 選択します。
  • --no-build - ビルドをスキップし、既存のビルド出力を実行します (出力プロパティは引き続き評価されます)。
  • --no-restore - ビルド前にプロジェクトの復元をスキップします。
  • -p, --property <Name=Value> - MSBuild プロパティ。ビルドとプロパティ評価の両方に転送されます。 反復可能 (例: -p WindowsPackageType=None)。

ビルド出力と詳細: プロジェクトは 2 つの手順でビルドされます。出力ストリームが本体にライブ配信されるdotnet buildで、その後にプロパティ評価のパスが高速になります。 winapp は出力の前に正確な dotnet build … 呼び出しを出力し、ビルドが成功した場合でも警告をストリームします。 詳細:

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

--jsonまたは--quietの呼び出しとビルド出力は stderr に送られ、stdout は純粋な JSON/クリーンなままです。

オプションの適用可能性: 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

# 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

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

Microsoft.Windows.SDK.BuildTools.WinApp NuGet パッケージを使用すると、dotnet run は自動的に winapp run を呼び出します。 .csprojでは、次の MSBuild プロパティを設定して動作を制御できます。

財産 Default 説明
EnableWinAppRunSupport true 実行サポート機能を有効または無効にする
WinAppLaunchArgs (空) 起動時にアプリに渡す引数
WinAppRunUseExecutionAlias false AUMID アクティブ化の代わりに実行エイリアスを使用して起動する
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、WinAppRunUseExecutionAlias、WinAppRunDebugOutput、WinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch、WinAppRunUseExecutionAlias、WinAppRunDebugOutput、WinAppRunUnregisterOnExit

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 [options]

オプション:

  • --manifest <path> - Package.appxmanifest へのパス (既定値: 現在のディレクトリからの自動検出)
  • --force - パッケージが別のプロジェクト ツリーから登録されている場合でも、インストール場所ディレクトリのチェックと登録解除をスキップする
  • --json - 出力を JSON として書式設定する

実行内容:

  • マニフェストからパッケージ名を読み取ります
  • {name}パッケージと{name}.debug パッケージの両方を検索します (デバッグバリアントはcreate-debug-identityによって作成されます)
  • 各パッケージが開発モードで登録されたことを確認します (IsDevelopmentMode == true)
  • パッケージのインストール場所が現在のディレクトリ ツリーの下にあることを確認します ( --forceを除く)
  • 一致するパッケージの登録を解除します

例:

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

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

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

# JSON output for scripting
winapp unregister --json

cert

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

証明書の生成

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

winapp cert generate [options]

オプション:

  • --manifest <Package.appxmanifest> - Package.appxmanifest から発行元情報を抽出する
  • --publisher <name>- 証明書のPublisher。 X.500 の完全な識別名 (例: CN=Contoso, O=Contoso Ltd, C=US) またはベア名を受け入れます。この名前は、次のように自動的にラップされます。 CN=<name>
  • --output <path> - 出力証明書ファイルのパス (絶対パスと相対パスをサポート)
  • --password <password> - 証明書パスワード (既定値: "password")
  • --valid-days <valid-days> - 証明書が有効な日数 (既定値: 365)
  • --install - 生成後にローカル コンピューター ストアに証明書をインストールする
  • --if-exists <Error|Overwrite|Skip> - 証明書ファイルが既に存在する場合の動作を設定する (既定値: エラー)
  • --export-cer - .cer ファイル (公開キーのみ) を .pfxと共にエクスポートします。 信頼インストール用にパブリック証明書を個別に配布する場合に便利です。
  • --json - プログラムで使用するために出力を JSON として書式設定します。 エラーは JSON ({"error": "..."}) としても返されます。

証明書情報

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

winapp cert info <cert-path> [options]

引数:

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

オプション:

  • --password <password> - PFX ファイルのパスワード (既定値: "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> [options]

引数:

  • file-path - 署名する MSIX パッケージまたは実行可能ファイルへのパス

オプション:

  • --cert <path> - 署名証明書へのパス
  • --cert-password <password> - 証明書パスワード (既定値: "password")

例:

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-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]

使用可能なツール:

例:

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

保存する

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
  • パッケージ インストール ディレクトリ
  • 生成されたヘッダーの場所

find-ui

動作するコード例については、 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]

コーパスは初回使用時にGitHubからフェッチされ、ユーザーごとに<global .winapp>/cache/find-uiキャッシュされるため、最初の実行にはネットワーク アクセスが必要です。 後続の実行はローカル キャッシュから実行されます (最大 7 日ごと、または --refresh を使用してオンデマンドで更新されます)。

オプション:

  • --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

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

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

winapp ui [command] [options]

コマンド：

  • status - アプリに接続して情報を表示する
  • inspect - 要素ツリーの表示
  • search - セレクターで要素を検索する
  • get-property - 要素のプロパティの読み取り
  • get-text / get-value - 要素から値/テキストを読み取ります (TextPattern、ValuePattern、または Name)
  • screenshot - ウィンドウ/要素を 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 - 現在フォーカスされている要素を報告する

オプション:

  • -a, --app <app> - ターゲット アプリ (名前、タイトル、または PID)
  • -w, --window <hwnd> - HWND によるターゲット ウィンドウ (安定)

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 demo.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)。
  • --frames - タイムスタンプ付き JPAG、 frames.ndjson、および manifest.json を <output-name>.framesに書き込みます。 1 から 30 fps、 --max-edge 64 から 4096 (既定では 1280) をサポートし、1 GiB のフレーム データ上限を備えます。

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

既知の制限事項: 独自の最上位ウィンドウ (WinUI/XAML ポップアップ、教育ヒント、ヒント) でレンダリングされるポップアップ内の 特定の要素 を記録すると、代わりに基になるメイン ウィンドウがキャプチャされる場合があります。 ウィンドウ全体を記録するか、ポップアップスチルに ui screenshot --capture-screen を使用します。 #646 で追跡されます。

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

  • Last updated on