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 - 構成ファイル操作のみを処理し、パッケージのインストールをスキップする

実行内容:

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

自動.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を使用)

例:

# 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

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

--setup-sdks none (またはスキップされた SDK インストール) でinitを実行し、後で 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 を使用します。

復元

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

winapp restore [options]

オプション:

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

実行内容:

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

例:

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

winapp pack <input-folder> [options]

引数:

• input-folder - パッケージ化するアプリケーション ファイルを含むディレクトリ

オプション:

• --output <filename> - 出力 MSIX ファイル名 (既定: <name>_<version>_<arch>.msix、 <name>_<version>.msix、 <name>_<arch>.msix、またはバージョン/アーチを特定できない場合は <name>.msix にフォールバック)
• --name <name> - パッケージ名 (既定値: マニフェストから)
• --manifest <path> - マニフェスト ファイルへのパス (推奨Package.appxmanifest 、 appxmanifest.xml もサポートされています。既定: 自動検出)
• --cert <path> - 署名証明書へのパス (自動署名を有効にする)
• --cert-password <password> - 証明書パスワード (既定値: "password")
• --generate-cert - 新しい開発証明書を生成する
• --install-cert - コンピューターに証明書をインストールする
• --publisher <name> - 証明書生成のPublisher名
• --self-contained - バンドル Windows アプリ SDK ランタイム
• --skip-pri - PRI ファイルの生成をスキップする
• --executable <path> - 入力フォルダーを基準とする実行可能ファイルへのパス ( --exeも指定します)。 マニフェスト内 $targetnametoken$ プレースホルダーを解決するために使用されます。

実行内容:

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

WinRT コンポーネントの検出

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

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

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

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

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

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

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

この場合とwinapp runを使用する場合: exe がアプリ コード (electron.exeがnode_modules内にある Electron アプリなど) から分離されている場合や、スパース パッケージの動作を具体的にテストする場合は、create-debug-identityを使用します。 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

マニフェスト

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

マニフェスト生成

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

winapp manifest generate [directory] [options]

引数:

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

オプション:

• --package-name <name> - パッケージ名 (既定値: フォルダー名)
• --publisher-name <name> - PUBLISHER CN (既定値: CN=<現在のユーザー>)
• --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$ トークン (ドル記号で区切られた) が使用されます。

これは、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 要素内に<uap5:AppExecutionAlias>を含む<Extensions> ブロックを追加します
• エイリアスが既に存在する場合は、それを報告して正常に終了します

例:

# 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 を返します。

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

winapp run <input-folder> [options]

引数:

• input-folder - 実行するアプリを含むディレクトリ (必須)

オプション:

• --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) クラッシュでは、モジュール名とオフセットが表示されます。 一度に 1 つのプロセスにアタッチできるデバッガーは 1 つだけであるため、他のデバッガー (Visual Studio、VS Code) を同時に使用することはできません。 別のデバッガーをアタッチする必要がある場合は、代わりに --no-launch を使用します。 --no-launchと組み合わせることはできません。 --jsonと組み合わせることはできません。
• --symbols - Microsoft シンボル サーバーから PDB シンボルをダウンロードして、解決された関数名を使用してネイティブ クラッシュ分析を充実させます。 --debug-output でのみ使用されます。 省略してネイティブ クラッシュが発生した場合、出力ではこのフラグの追加が推奨されます。 最初の実行では、シンボルがダウンロードされ、ローカルにキャッシュされます。それ以降の実行ではキャッシュが使用されます。
• --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

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

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

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

create-external-catalog

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

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

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

保存する

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

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 します)。

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

オプション:

実行内容:

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

オプション:

実行内容:

• によって作成されたバックアップから 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などのコマンドを実行すると、このディレクトリを自動的に作成します。

ui

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

winapp ui [command] [options]

コマンド：

• status - アプリに接続して情報を表示する
• inspect - 要素ツリーの表示
• search - セレクターで要素を検索する
• get-property - 要素のプロパティの読み取り
• get-text / get-value - 要素から値/テキストを読み取ります (TextPattern、ValuePattern、または Name)
• screenshot - ウィンドウ/要素を PNG としてキャプチャする (ダイアログを個別に自動キャプチャ)
• invoke - 要素のアクティブ化 (クリック、切り替え、展開)
• click - マウス シミュレーションを使用して要素をクリックする (呼び出しをサポートしていないコントロールの場合)
• set-value - 編集可能な要素 (テキスト、数値) に値を設定する
• focus - キーボード フォーカスを移動する
• scroll-into-view - Scroll 要素が表示される
• wait-for - 要素の状態を待機する
• list-windows - アプリのすべてのウィンドウを一覧表示する
• get-focused - 現在フォーカスされている要素を報告する

オプション:

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

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