CLI 文件與使用

殼體完備

啟用指令、選項和數值的分頁補全功能。 請參閱 Shell Completion 指南 以獲得設定說明。

# 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 安裝模式：「穩定」（預設）、 「預覽」、「實驗性」或「無」（跳過 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直接添加為PackageReference中的NuGet.csproj條目
  • 產生Package.appxmanifest、資產和開發證書
  • 不會建立winapp.yaml或下載 C++ 投影（用於 dotnet restore NuGet 套件）

範例：

# 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

如果你已經使用 init--setup-sdks none （或跳過 SDK 安裝）但之後需要 SDK：

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

使用 --setup-sdks preview 或 --setup-sdks experimental 用於預覽/實驗性的 SDK 版本。

回復

還原套件並根據現有 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

pack

從準備好的應用程式目錄建立 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 - Bundle Windows 應用程式 SDK runtime
  • --skip-pri - 跳過 PRI 檔案產生
  • --executable <path> - 相對於輸入資料夾的可執行檔路徑（亦為 --exe）。 用來解析 $targetnametoken$ 清單中的佔位符。

它的用途：

  • 驗證並處理 Package.appxmanifest 檔案
  • $placeholder$解析清單中的標記（見下方 Manifest 佔位符）
  • 確保適當的框架相依性
  • 清單與登記並列更新
  • 自動發現第三方 WinRT 元件並註冊其可啟用類別（詳見下方 WinRT 元件發現 ）
  • 處理自包含的 WinAppSDK 部署
  • 如果有證書，請提供標誌套件

WinRT 元件發現

在打包時，會winapp pack自動掃描 NOR *.csproj 定義的 winapp.yaml NuGet 套件，針對第三方 WinRT 元件（例如 Win2D）。 它解析 .winmd 檔案以擷取可啟用的類別名稱，並定位其實作 DLL。 發現的條目登記如下：

  • 依賴框架 （預設）：可啟用的類別會作為 <InProcessServer> 項目加入 Package.appxmanifest
  • 自包含--self-contained（）：可啟用類別嵌入於可執行檔中的並列（SxS）manifest 中

包裝時的占位符解決：

若清單屬性包含$targetnametoken$Executable：

  1. 若 --executable 提供（相對於輸入資料夾的路徑），則佔位符會被替換為指定的值
  2. 否則，會 winapp pack 掃描輸入資料夾根目錄中的 .exe 檔案——如果剛好找到一個檔案，會自動使用
  3. 如果找到零個或多個 .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

建立除錯識別

建立應用程式身份以使用 稀疏封包來除錯。 exe 會留在原本的位置——Windows 透過 Add-AppxPackage -ExternalLocation 來與它關聯身份。

何時使用此方法與winapp run：當 exe 與你的應用程式程式碼分開時使用create-debug-identity（例如 Electron 應用程式，其中 electron.exe 是 ），node_modules或專門測試稀疏套件行為時使用。 對於大多數 exe 放在建置輸出資料夾的框架，請改用 winapp run — 它會註冊一個完整的鬆散版面套件並啟動應用程式。 完整比較請參閱 除錯指南 。

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

引數：

  • entrypoint - 前往執行檔（.exe）或需要識別碼的腳本的路徑

選項：

  • --manifest <path> - 應用程式清單檔案的路徑，或 Package.appxmanifestappxmanifest.xml 為（預設：自動偵測 Package.appxmanifest 或 appxmanifest.xml 目前目錄中）
  • --no-install - 建立套件後不要安裝
  • --keep-identity - 保持清單身份 as-is，且不附加 .debug 套件名稱與應用程式 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 檔案。

manifest 生成

從範本產生 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）

範本：

顯現佔位符

生成清單使用以美元符號分隔的 $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 提供時，從執行檔中擷取了 manifest metadata（版本、描述）和圖示，但產生的 manifest 仍使用 $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 附加別名

在 Package.appxmanifest 中加入執行別名uap5:AppExecutionAlias（）。 這讓使用者能透過輸入別名名稱，從命令列啟動已封裝的應用程式。

winapp manifest add-alias [options]

選項：

  • --name <alias> - 別名（例如 myapp.exe）。 預設：從 Executable 清單中的屬性推斷。
  • --manifest <path> - Package.appxmanifest 路徑（預設：搜尋目前目錄）
  • --app-id <id> - Application ID 以加入別名（預設：第一個應用程式元素）

它的用途：

  • 讀取清單並從 Executable 屬性推斷別名（保留像 $targetnametoken$.exe）
  • 如果還沒有命名空間宣告，會 uap5 新增
  • 新增一個<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

清單更新資產

從單一來源映像產生所有必要的 MSIX 映像資產。

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

引數：

  • image-path - 來源影像檔（PNG、JPG、SVG、ICO、GIF、BMP 等）的路徑

選項：

  • --manifest <path> - Package.appxmanifest 檔案路徑（預設：搜尋目前目錄）
  • --light-image <path> - 光源主題變體的路徑導向獨立來源影像

Description:

根據清單的資產參考，取得單一來源影像，產生完整的 MSIX 影像資產集合：

對於清單中提及的每項資產：

  • 5 種音階變體 — 基數（無後綴）、.scale-125、、 .scale-200.scale-150.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

此外：

  • 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）用於套件身份碼除錯的首選指令。 不像 create-debug-identity MSIX 會註冊一個稀疏套件，而是 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 - 僅建立除錯身份並註冊套件，而不必啟動應用程式
  • --with-alias - 啟動應用程式時，使用執行別名而非 AUMID 啟用。 應用程式在目前的終端機中運行，繼承了 stdin/stdout/stderr。 需要在清單中填寫 a uap5:ExecutionAlias （用來 winapp manifest add-alias 新增一個）。 不能與 --no-launch結合使用。 不能與 --json結合使用。
  • --debug-output - 從啟動應用程式中擷取 OutputDebugString 訊息及首次例外。 框架雜訊（WinUI、COM、DirectX）會從主控台輸出中被過濾;完整的日誌檔案會記錄所有內容。 如果應用程式當機，會自動擷取一個迷你傾印並分析，顯示例外類型、訊息和堆疊追蹤，並附帶原始檔案：行號（從建置輸出資料夾中的 PDB 解析）。 管理型（.NET）當機可即時分析，無需外部工具。 原生（C++/WinRT）當機時會顯示模組名稱和偏移量。 同一時間只能連接一個除錯器，因此無法同時使用其他除錯器（如 Visual Studio、VS Code）。 如果需要附加不同的除錯器，請使用 --no-launch 。 不能與 --no-launch結合使用。 不能與 --json結合使用。
  • --symbols - 從 Microsoft Symbol Server 下載 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 - 輸出格式為 JSON 供程式化使用（例如 CI/自動化）。 --detach用來捕捉 PID。 無法與 --with-alias 或 --debug-output結合。

應用程式資料持續性：

預設情況下，winapp run重新部署時會保留應用程式的資料（LocalState、RoamingStateSettings等）。 如果你的應用程式在套件上下文中寫入資料ApplicationData.Current.LocalFolderEnvironment.GetFolderPath(SpecialFolder.LocalApplicationData)，這些資料會在呼叫間winapp run存活。

當你需要重新開始時使用 --clean （例如重置損壞狀態或測試首次執行行為）。

它的用途：

  • 定位或產生 Package.appxmanifest
  • 使用鬆散的版面套件建立並註冊除錯身份
  • 計算應用程式使用者模型識別碼（AUMID）
  • 以註冊身份啟動應用程式（除非 --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。 以下 MSBuild 屬性可在你的 .csproj 控制行為中設定：

房產 預設 說明
EnableWinAppRunSupport true 啟用或停用跑步支援功能
WinAppLaunchArgs (空白) 應用程式上市時應提出的論點
WinAppRunUseExecutionAlias false 透過執行別名發射，而非 AUMID 啟動
WinAppRunNoLaunch false 只註冊身份，且不啟動
WinAppRunDebugOutput false 捕捉 OutputDebugString 訊息與首次例外。 一次只能連接一個除錯器（防止 VS/VS 程式碼使用）。 用 WinAppRunNoLaunch 來接一個不同的除錯器。 
<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

取消註冊

取消註冊一個側載開發套件。 僅移除已註冊於開發模式的套件（例如 via 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

建立外部目錄

產生 CodeIntegrityExternal.cat 一個目錄檔案，包含指定目錄中可執行檔雜湊值。 此目錄與 MSIX 稀疏套件清單（AllowExternalContent）中的 TrustedLaunch 旗標一起使用，以允許執行套件本身未包含的外部檔案。

這類似 signtool.exe 於簽署 MSIX 套件時的建立 AppxMetadata\CodeIntegrity.cat 方式，但會產生一個外部目錄，用於稀 疏/外部位置封包。

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

引數：

  • input-folder - 一個或多個包含可執行檔案的目錄以進行處理。 用分號分隔多個目錄（例如， "dir1;dir2"）

選項：

  • --recursive， -r - 包含子目錄的檔案
  • --use-page-hashes - 在產生目錄時包含頁面雜湊值（產生更大的目錄，並以每頁雜湊資料計算）
  • --compute-flat-hashes - 在產生目錄時包含扁平檔案雜湊值
  • --if-exists <Error|Overwrite|Skip> - 輸出檔已存在時的行為（預設： Error）
  • --output， - -o 輸出目錄檔案路徑。 若未指定，則 CodeIntegrityExternal.cat 會在目前目錄中建立。 若指定目錄，則會附加預設檔名。

它的用途：

  • 掃描指定的可執行檔案目錄（帶有程式碼區段的 PE 二進位檔）
  • 產生目錄定義檔案（CDF），包含所有已找到執行檔的雜湊值
  • 使用 Windows CryptoCAT API 來產生 .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 工具。 使用Microsoft.Windows中可用的工具。SDK。BuildTools

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

可用工具：

範例：

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

儲存

執行 Microsoft Store 開發者 CLI 指令。 如果尚未下載，此指令將下載Microsoft Store開發者CLI。 了解更多關於 Microsoft Store 開發者 CLI。

winapp store [args...]

引數：

  • args... – 直接提交給 msstore CLI的論點。 請參閱 MSStore CLI 文件 以了解可用的指令與選項。

它的用途：

  • 確保Microsoft Store開發者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 應用程式路徑）

取得已安裝的 Windows SDK 元件的路徑。

winapp get-winapp-path [options]

回報內容：

  • 工作 .winapp 區目錄的路徑
  • 套件安裝目錄
  • 產生的標頭位置

節點創建外掛

（僅限 NPM 套件提供） 透過 SDK 與 Windows 應用程式 SDK 整合產生原生 C++ 或 C# 外掛範本Windows。

npx winapp node create-addon [options]

選項：

  • --name <name> - 附加元件名稱（預設：「nativeWindowsAddon」）
  • --template - 選擇外掛類型。 選項為 cs 或 cpp （預設： cpp）
  • --verbose - 啟用冗長輸出

它的用途：

  • 建立帶有範本檔案的附加目錄
  • 產生 binding.gyp 和 addon.cc，並附有 SDK 範例Windows
  • 安裝需要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

節點添加electorn調試標識

（僅提供 NPM 套件） 透過使用稀疏封裝，將應用程式身份加入 Electron 的開發流程。 需要 Package.appxmanifest（如果沒有就建立一個winapp initwinapp manifest generate）。

這很重要

Electron 應用程式封裝稀疏時已知存在問題，會導致應用程式啟動時當機或無法渲染網頁內容。 這個問題在 Windows 上已經修正，但還沒擴散到外部 Windows 裝置。 如果你在呼叫 add-electron-debug-identity後遇到這個問題，可以在 Electron 應用程式中用旗標停用沙箱 功能，方便除錯 --no-sandbox 。 此問題不影響完整的 MSIX 封裝。

要解除 Electron 偵錯身份，請使用 winapp node clear-electron-debug-identity。

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

選項：

Option 說明
--manifest <path> 自訂 Package.appxmanifest 路徑（預設：目前目錄中的 Package.appxmanifest）
--no-install 請勿安裝或修改相依性;僅設定 Electron 除錯身份
--keep-identity 保持 manifest 的原樣身份，但不要在套件名稱和應用程式 ID 上附加 .debug
--verbose 啟用冗長輸出

它的用途：

  • 暫存器除錯程序 electron.exe 身份
  • 使 Electron 開發中能測試需要身份的 API
  • 使用現有的 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

節點 清除 Electron 偵錯身份情報

（僅提供 NPM 套件） 透過從備份還原原始 electron.exe，從 Electron 除錯程序中移除套件身份。

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

選項：

Option 說明
--verbose 啟用冗長輸出

它的用途：

  • 從由electron.exe add-electron-debug-identity
  • 還原後會移除備份檔案
  • 將 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 變數。

在 指令長中：

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

當你執行像 init 是 or restore的指令時，Winapp 會自動建立這個目錄。

ui

使用 使用者介面自動化（UIA）檢查並互動正在執行的 Windows 應用程式介面。

winapp ui [command] [options]

指令：

  • status - 連接應用程式與節目資訊
  • inspect - 檢視元素樹
  • search - 透過選擇器尋找元素
  • get-property - 讀取元素屬性
  • get-text / get-value - 從元素（TextPattern、ValuePattern 或 Name）讀取值/文字
  • screenshot - 以 PNG 格式擷取視窗/元素（自動單獨擷取對話）
  • invoke - 啟動元素（點擊、切換、展開）
  • click - 透過滑鼠模擬點擊元素（用於不支援 invoke 的控制項）
  • set-value - 設定可編輯元素（文字、數字）的值
  • focus - 移動鍵盤焦點
  • scroll-into-view - 捲軸元素可見
  • wait-for - 等待元素狀態
  • list-windows - 列出應用程式的所有視窗
  • get-focused - 報告當前聚焦的元素

選項：

  • -a, --app <app> - Target 應用程式（名稱、標題或 PID）
  • -w, --window <hwnd> - HWND（穩定版）的目標視窗

完整文件請參見 docs/ui-automation.md。

  • Last updated on