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 - 僅處理設定檔操作，跳過套件安裝
• --exe <path> - 應用程式執行檔的路徑。 需要 --sparse。 它會為 exe 產生一個只包含身份的稀疏清單，而不是完整的套件或 SDK 設定。
• --sparse - 為現有桌面執行檔產生稀疏身份清單（appxmanifest.xml）。 跳過 SDK 或套件安裝。 與 --exe 搭配使用。
• --name <name> - 覆寫套件名稱（僅限稀疏;預設：由執行檔推斷）
• --publisher <CN> - 覆寫發佈商 CN（僅限稀疏;預設：由執行檔公司名稱推斷）
• --output-dir <path> - 用來寫入 sparse manifest 和 Assets/ 的目錄（僅 sparse;預設為 sparse/ 當前目錄中的資料夾）
• --force - 覆蓋目標目錄中存在 appxmanifest.xml 的（僅稀疏）。 沒有它，init 會失敗，而不是替換現有的清單或資產。
• --add-js-bindings （僅限 npm） - 新增 winapp.jsBindings 至 package.json 並產生 JS/TypeScript 綁定，無需提示（與 --setup-sdks none）

它的用途：

• 建立 winapp.yaml 設定檔（僅在管理 SDK 套件時;跳過時則有 --setup-sdks none）
• 下載 Windows SDK 及 Windows 應用程式 SDK 套件
• 產生 C++/WinRT 標頭與二進位檔
• 建立 Package.appxmanifest
• 建立建置工具並啟用開發者模式
• 更新 .gitignore 以排除產生的檔案
• 將可分享檔案儲存在全域快取目錄中
• 啟用 Windows 應用程式 SDK API 時（僅限 npm）產生 JS 綁定

自動專案偵測：

當 init 執行時沒有目錄參數，會對目前目錄樹進行廣度優先搜尋，以尋找相容的專案（最多 10 個）。 支援的專案類型：

• Tauri — tauri.conf.json 在目錄下一層發現
• 電子 — package.json 具有 electron in 依賴關係或 devDependencies
• 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則先警告
• 在非互動環境（管道標準、CI、重定向輸入）中，會 init 自動使用 --use-defaults 行為並發出警告： Non-interactive environment detected. Using default values.
• 如果目前的目錄是相容的專案， init 則會立即進行
• 如果在其他地方找到一個專案，系統會提示你確認
• 如果發現多個專案，你可以選擇要初始化哪一個——目前的目錄永遠是備用選項
• 如果找不到專案，會被警告並詢問是否繼續進行
• 若搜尋達到 10 個專案的限制，則會提示提供目錄參數

自動 .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 套件）

稀疏恆等模式（--exe + --sparse）：

為現有桌面執行檔產生僅識別身份的稀 疏套件 清單——稀 疏套件工作流程的第一步。 與完整 init 流程不同，這 會跳過所有 SDK/套件安裝 （稀疏身份套件沒有 SDK 依賴），只產生清單和佔位資產。

• 透過（用 --name、 --publisher、 或互動式方式）從執行檔FileVersionInfo推斷套件名稱、發佈者、描述和版本
• appxmanifest.xml 將（將 exe 名稱替換成 Executable）加上一個Assets/資料夾寫入目前目錄中的某sparse/個資料夾（或 --output-dir）
• 用於 --use-defaults/--no-prompt 跳過互動覆寫提示（CI 友善）
• --exe 沒有 --sparse 則為錯誤

資產是外部的。 稀疏 .msix 僅為身份：產生 Assets/ 的檔案是在執行時從應用程式的安裝目錄（外部內容位置）解析， 而非 捆綁在 .msix. 將它們與你的應用程式一起部署。

接下來 winapp init --exe <exe> --sparse的步驟： winapp pack <appxmanifest.xml> 建立恆等式 .msix，然後 winapp embed-identity <exe>。 完整攻略請參閱 稀疏包裝指南 。

範例：

# 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--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 版本。

---

新增

從官方 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如 。 預設值：當沒有包時安裝最新的，否則會提示更新過時的包（as-is --use-defaults在 下）。
• --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 封裝和身份碼（），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

---

pack

從準備好的應用程式目錄建立 MSIX 套件。 需要目標目錄中、目前目錄中或隨選項傳遞Package.appxmanifest的清單檔案appxmanifest.xml（偏好--manifest且支援）。 （跑步 init 或 manifest generate 製作清單）

傳遞多個輸入資料夾以建立 .msixbundle 多架構發行版（詳見下方多 架構套件 ）。

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

引數：

• input-folder - 一個或多個包含待打包應用程式檔案的目錄。 傳遞多個資料夾（例如 ./publish/x64 ./publish/arm64）來建立 MSIX 套件。 對於 sparse identity 套件，直接傳遞 sparse appxmanifest.xml 檔案而非資料夾（詳見下方 Sparse identity packages ）。

選項：

• --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$解析清單中的標記（見下方 Manifest 佔位符）
• 確保適當的框架相依性
• 清單與登記並列更新
• 如果清單目錄或輸入資料夾中缺少任何非影像檔案（例如應用程式擴充 manifest.json功能、設定檔），會自動發現並打包
• 自動發現第三方 WinRT 元件並註冊其可啟用類別（詳見下方 WinRT 元件發現 ）
• 處理自包含的 WinAppSDK 部署
• 如果有證書，請提供標誌套件

稀疏身份封包

當輸入是稀 疏 appxmanifest.xml 檔案 （在 <uap10:AllowExternalContent>true</uap10:AllowExternalContent><Properties>下宣告的檔案）而非資料夾時， winapp pack 會建立 純.msix 身份檔案——它只打包清單，沒有應用程式二進位檔或資產。 這是 稀疏包裝工作流程的第二步。

# 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的資料夾，則依舊的資料夾打包行為，但winapp pack如果發現資產（）.ico//.png.jpg或二進位檔（.exe.dll//.so）會警告——對於稀疏套件，這些應該放在外部位置，而非內部。.msix

打包完成後，執行winapp embed-identity <exe>並在安裝程式中註冊該套件。Add-AppxPackage -Path <msix> -ExternalLocation <install-dir> 請參閱稀 疏包裝指南。

WinRT 元件發現

在打包時，會winapp pack自動掃描 NOR winapp.yaml 定義的 *.csproj 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

多架構套件

當傳遞多個輸入資料夾時，會 winapp pack 建立 .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 標頭偵測每個資料夾的架構，驗證各切片（身份、能力、相依）的一致性，並產生一個 <Name>_<Version>_<arch1>_<arch2>.msixbundle.

組合包的明確解決：

組合包中的每個切片都需要一個清單。 指令解析的顯現順序如下：

1. --manifest <path> — 若另有指定，該單一清單用於所有切片。 ProcessorArchitecture每個切片都會自動更新，以符合偵測到的架構。

2. 每個資料夾清單 — 如果每個輸入資料夾包含一個 Package.appxmanifest （或 appxmanifest.xml），該資料夾的清單會被用於其切片。

3. 目前目錄的備援 — 如果某資料夾沒有清單，指令會在目前的工作目錄中尋找 並 Package.appxmanifest 使用該目錄（架構自動蓋章）。

在所有情況下，清單都會自動更新：佔位符被解析，相依性注入，並將 ProcessorArchitecture 強制設定為偵測到的架構。 解決後，跨切片驗證確保身份（名稱、版本、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

---

建立除錯識別

建立應用程式身份以使用 稀疏封包來除錯。 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

---

嵌入同一性

將桌面應用程式與其稀 疏身份套件 連接，方法是將該元素嵌入 <msix> 應用程式的並排（融合）清單中。 這是稀疏封包工作流程的第三步——它告訴 Windows 執行執行檔屬於哪個身份套件。

winapp embed-identity <target> [options]

引數：

• target - 要更新的檔案。 自動偵測延伸：
  • .exe （EXE 模式）— 直接將元素嵌入 <msix> exe 的並排清單中，使用 mt.exe。
  • .xml / .manifest （XML 模式）— 插入或替換外部 SxS 清單檔案中的元素 <msix> （若不存在則建立）。 之後再重建你的應用程式，讓更新的清單嵌入二進位檔中。

選項：

• --manifest <path> - 可讀取稀疏 appxmanifest.xml 識別碼（packageName、publisher、applicationId）的路徑。 若省略，指令先 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 檔案。

manifest 生成

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

範本：

• packaged - 標準打包應用程式清單
• sparse- 使用稀疏/外部位置封裝的應用程式清單

顯現佔位符

生成清單使用以美元符號分隔的 $placeholder$ 標記，在打包時會自動解析：

預留位置	決心	範例
$targetnametoken$	無副檔名的可執行檔名稱	Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$	Windows.FullTrustApplication	總是自動解決

這遵循 Visual Studio 專案範本的慣例，因此清單能跨工具可攜式。

占位符的解決方式：

• winapp pack — 在打包過程中， $targetnametoken$ 透過選項 --executable 或自動偵測輸入資料夾中的單曲 .exe 來解決。 若發現多個（或零） .exe 檔案且 --executable 未指定，則會顯示錯誤。
• winapp create-debug-identity — 當提供一個入點論元時， $targetnametoken$ 會從中解決。 若沒有入口點，可執行的佔位符必須已在清單中被解析。
• winapp manifest generate --executable — 當 --executable 提供時，從執行檔中擷取了 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-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

此外：

• 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 運作模式為兩種，從輸入中自動選擇：

• 資料夾模式 — 輸入為建置輸出資料夾（包含一個 Package.appxmanifest/AppxManifest.xml）。
• Project 模式 — 輸入是一個 .csproj、一個.sln/.slnx解決方案，或是一個包含 的目錄。 winapp run 建立專案並啟動，支援 已打包 與 未打包的 WinUI 應用程式。 請參考下方的 Project 模式。

Tip

模式選擇預設是靜音的。 如果你預期某個目錄會被當作專案，卻被當作建置-輸出資料夾，請重新執行—— --verbose 資料夾模式會回報為什麼選擇它（No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.）。 只有當 a .csproj/.slnx/.sln有可執行的應用程式位於頂層時，目錄才會被建立為專案;它不會被遞迴搜尋。

這是大多數框架（.NET、C++、Rust、Flutter、Tauri）用於套件身份碼除錯的首選指令。 不像 create-debug-identity MSIX 會註冊一個稀疏套件，而是 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 - 僅建立除錯身份並註冊套件，而不必啟動應用程式
• --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）當機時會顯示模組名稱和偏移量。 當當機的應用程式是 WinUI 3 應用程式（Microsoft.UI.Xaml.dll 已載入）時，會自動執行額外的 stowed-exception 分流通道，以顯示原始 HRESULT、其 ErrorContext 鏈及完整的原生 XAML 派遣堆疊;所需的除錯器元件會在首次使用時下載（參見 除錯，可透過 WINAPP_DBGTOOLS_DIR 環境變數覆寫）。 同一時間只能連接一個除錯器，因此無法同時使用其他除錯器（如 Visual Studio、VS Code）。 如果需要附加不同的除錯器，請使用 --no-launch 。 不能與 --no-launch結合使用。 不能與 --json結合使用。
• --symbols - 從 Microsoft Symbol Server 下載 PDB 符號，提供更豐富的原生當機分析及已解析的函式名稱。 僅搭配 --debug-output使用。 若省略且發生原生當機，輸出會建議新增此旗標。 此旗標也改善了 WinUI 3 應用程式的收納例外分流堆疊。 首先執行時下載符號並快取到本地;後續執行會使用快取。
• --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

Project 模式（.NET SDK 專案）

當輸入為 .csproj、 、/.slnx.sln解決方案或包含 .的winapp run目錄時，會以dotnet build 建置專案並啟動。 它支援已打包與未封裝的 WinUI 應用程式，並在啟動前安裝符合架構的 Windows 應用程式 執行環境。

解決方案輸入：指向winapp run一個.sln/.slnx（或包含該方案的目錄——解決方案比散落.csproj檔案更受青睞），它會解析可執行的應用程式專案，然後用定義的兄弟Solution*屬性來建置，$(SolutionDir)讓依賴這些物件的專案能像 Visual Studio 一樣建置。 解決規則：

• 自動選擇時會跳過測試專案，因此包含應用程式及其測試的解決方案會自動解析成應用程式，無需--project額外需求。 （WinUI 測試專案本身就是一個打包的應用程式，因此僅靠輸出型別無法區分它。）
• 如果唯一可執行的專案是測試專案，它就會執行。
• 如果存在多個可執行的應用程式專案， winapp run 則不會猜測新創專案——而是在列出候選項目時出錯。 使用 --project <name> 選擇功能，這點總是被遵守，包括選擇測試專案。

封裝與未封裝會自動從專案的有效 WindowsPackageType MSBuild 屬性中偵測（絕非從顯現狀態中偵測）：

• Packaged （WindowsPackageType=MSIXWinUI 封裝預設）— 建置後將建置輸出註冊為鬆散版面套件，並透過 AUMID（與資料夾模式相同的流程）啟動。
• Unpackaged （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）。

建構輸出與冗長度： 專案分為兩個階段—— dotnet build 輸出 即時串流 到你的主機，接著快速進行屬性評估。 Winapp 會在輸出前直接列印精確 dotnet build … 的呼叫，並在成功建置時串流警告。 冗長度：

Flag	dotnet 冗長度	補充
(預設)	minimal	—
--verbose	minimal	Winapp 的建置決策追蹤
--quiet	quiet	—

在 or --quiet 下--json，調用和建置輸出都放到 stderr，這樣標準出就能保持純 JSON / 乾淨。

選項適用性：身份/鬆散排版選項（--manifest， ， --output-appx-directory--no-launch， --unregister-on-exit--with-alias--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。 以下 MSBuild 屬性可在你的 .csproj 控制行為中設定：

房產	預設	說明
EnableWinAppRunSupport	true	啟用或停用跑步支援功能
WinAppLaunchArgs	(空白)	應用程式上市時應提出的論點
WinAppRunUseExecutionAlias	false	透過執行別名發射，而非 AUMID 啟動
WinAppRunNoLaunch	false	只註冊身份，且不啟動
WinAppRunDebugOutput	false	捕捉 OutputDebugString 訊息與首次例外。 一次只能連接一個除錯器（防止 VS/VS 程式碼使用）。 用 WinAppRunNoLaunch 來接一個不同的除錯器。
WinAppRunDetach	false	啟動後立即返回，不要等應用程式退出。 列印PID。
WinAppRunUnregisterOnExit	false	應用程式退出後，開發套件會取消註冊
WinAppRunClean	false	在重新部署前，先移除現有套件的應用程式資料（LocalState、設定）
WinAppRunSymbols	false	從 Microsoft Symbol Server 下載符號，以獲得更豐富的原生崩潰分析。 只有在 時 WinAppRunDebugOutput才有影響。
WinAppRunExecutable	(空白)	相對於 build-output 資料夾的執行檔路徑。 當清單包含 $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>

---

取消註冊

取消註冊一個側載開發套件。 僅移除已註冊於開發模式的套件（例如 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 提供證書。 接受完整的 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

---

方位符號

使用 Azure 信任簽署 — 一個雲端管理的簽章身份——來對檔案（exe、MSIX 或 MSIX bundle）進行程式碼簽章，因此沒有任何私鑰（PFX）會存在於本地機器上。

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

引數：

• file-path - 簽署檔案的路徑（exe、msix 或 msixbundle）

選項：

• --subscription， - -s 使用 Azure 訂閱 ID。 如果沒有提供且有多個訂閱，系統會提示你
• --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 （或使用 GitHub Actions OIDC / 管理身份）。 現有的 Azure CLI 會話（az login包括 azure/login GitHub Action）在任何環境中也會被尊重。 只有當找不到任何憑證 且 會話是互動式時，會自動 az-sign 啟動 az login 。

先決條件：

• 一個 Azure 代碼簽署帳號和一個憑證設定檔（在 Azure 入口網站驗證後建立），再加上指派給你身份的代碼簽署憑證設定檔簽署者角色。 欲獲得更多指引，請造訪 Azure Artifact Signing 快速入門文件。
• 安裝了全機 x64 .NET 8（或更新版本）執行環境。 Azure 簽署客戶端函式庫是一個受管理的組件，會在signtool.exe獨立程序中載入;Winapp 自有的執行環境無法滿足這個需求。 如果簽約失敗且執行時載入錯誤，請從 安裝 https://dotnet.microsoft.com/download 。
• Microsoft Visual C++ Redistributable（x64）。 Azure 簽署用戶端函式庫依賴 VC++ 執行環境，且因為 WinApp 下載的是原始的 NuGet 套件，而非官方的客戶端工具安裝程式，因此此依賴不會自動安裝。 一台乾淨的機器即使有 .NET 和 SignTool，也可能發生載入失敗。 如果簽署失敗，安裝最新的 x64 redistributable， https://aka.ms/vs/17/release/vc_redist.x64.exe 並出現 0xc000007b「應用程式無法正確啟動」或 dlib 的 missing-dll 錯誤。

最低權限CI： 自動發現（列出訂閱、資源群組、帳號和個人檔案）需要在父範圍有讀取權限。 為避免 每次 集合列示呼叫，先傳遞 --subscription、 --resource-group、 --account、 --profile三個 ： az-sign 然後以直接資源讀取（對每個命名資源執行 GET）驗證帳號與設定檔，而非列舉父集合，因此只對該帳戶與設定檔設限的主體即可。 省略任何一項會重新觸發登錄通知——例如，省略 --subscription 這些會列出 az-sign 你的身份可存取的訂閱——而範圍較窄的委託人可能無法這麼做。 僅針對單一憑證設定檔的主體，可以透過傳遞預先產生 --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

---

建立外部目錄

產生 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]

可用工具：

• makeappx - 建立與操作應用程式套件
• signtool - 簽署檔案並驗證簽名
• mt - 並排組裝組態工具
• 以及Windows其他來自 Microsoft.Windows 的 SDK 工具。SDK。BuildTools

範例：

# 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 區目錄的路徑
• 套件安裝目錄
• 產生的標頭位置

---

尋找介面

搜尋 WinUI 控制項和範例，尋找可運作的程式碼範例。 僅限 WinUI 使用：語料庫是 WinUI 3 圖庫和 Windows 社群工具包（加上一些精選的核心範本）——不涵蓋 WPF、WinForms 或其他 UI 框架。 第三個來源 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#;反應爐僅支援 C#），並附上先前搜尋時提供的一個或多個情境 ID 的前置註解（例如 gallery-tabview-1）。 可重複。 ID 不區分大小寫 —— GALLERY-TABVIEW-1 解析與 gallery-tabview-1相同。
• --list - 列出所有可發現的控制/樣本 ID，而非搜尋（Gallery + Toolkit + core;選擇加入的反應器來源不包含）。
• --source <gallery|toolkit|reactor|core> - 將搜尋結果限制於單一來源。 （僅搜尋 — 不適用於 --list/--id。） 反應爐是選擇加入 的——它不包含在正常搜尋中，因此 --source reactor 是唯一的搜尋方式。
• --max <N> - 最多可回傳的配對控制數量（預設：3）。 僅適用於搜尋;忽略於 --list/--id。
• --refresh- 繞過本地快取，從 GitHub 重新取得 WinUI 語料庫。
• --json - Emit 結構化 JSON（代理友善）。 對於搜尋，每個匹配攜帶 、 、 、 ，以及一個scenarios陣列，該陣列的條目包含每個情境id與header;對於 --id，則為完整程式碼。 descriptionscorecontrolsource 在 --json每次 失敗中——包括參數/解析器錯誤如非整 --max 數——都會以平面物件形式在標準輸出中輸出 {"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

---

節點產生綁定

（僅提供 NPM 套件）為 Windows 應用程式 SDK API 產生 JS 綁定。 綁定由 中的"winapp": { "jsBindings": {...} }命名空間宣告package.json並寫入.winapp/bindings/。

npx winapp node generate-bindings [options]

選項：

• --verbose， -v - 啟用每個檔案的冗長碼生成輸出
• --quiet， -q - 抑制進度與資訊輸出

它的用途：

• 讀取 winapp.jsBindings 區塊 和 package.jsonwinmds.lock.json 由最後一個 winapp restore寫入的區塊，然後輸出打 .js + .d.ts 型綁定為 .winapp/bindings/
• 它不會被修改package.json——它是被動再生器。 在啟用 JS 綁定時，新增 winapp.jsBindings 區塊與 @microsoft/dynwinrt 執行時相依性; 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

請參閱 JS 綁定指南 ，了解端對端工作流程與 winapp.jsBindings 設定選項。

---

節點創建外掛

（僅限 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 會自動建立這個目錄。

更新檢查

winapp CLI 會定期檢查是否有新版本，並在有更新時顯示一行通知。 這個檢查是在背景執行，且不會增加指令延遲。

更新檢查會在 CI 環境（例如 GitHub Actions、Azure Pipelines 等）中自動停用。

若要手動停用更新檢查，請將環境變數設 WINAPP_CLI_UPDATE_CHECK 為 0。

在 指令長中：

set WINAPP_CLI_UPDATE_CHECK=0

在 PowerShell 和 pwsh中：

$env:WINAPP_CLI_UPDATE_CHECK = "0"

要讓這件事成為永久：

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

ui

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

winapp ui [command] [options]

指令：

• status - 連接應用程式與節目資訊
• inspect - 檢視元素樹
• search - 透過選擇器尋找元素
• get-property - 讀取元素屬性
• get-text / get-value - 從元素（TextPattern、ValuePattern 或 Name）讀取值/文字
• screenshot - 以 PNG 格式擷取視窗/元素（自動單獨擷取對話）
• record- 將視窗/元素區域錄製到 H.264 MP4 影片（Windows Graphics Capture + Media Foundation）
• invoke - 啟動元素（點擊、切換、展開）
• click - 透過滑鼠模擬點擊元素（用於不支援 invoke 的控制項）
• hover - 將滑鼠移至元素以觸發提示、飛出及懸停狀態（預設停留時間：800毫秒）
• drag - 透過元素選擇器或螢幕 x,y 座標（重新排序、調整大小、滑桿、拖放）將滑鼠從一個點拖到另一個點
• touch - 在元素中心或螢幕 x,y 座標注入合成觸控手勢（點擊、雙擊、長按、滑動、捏合、拉伸）
• pen - 注入合成筆/觸控筆輸入 — 點擊與墨筆筆劃，並可設定壓力、傾斜與橡皮擦模式
• send-keys - 將合成鍵盤輸入（命名鍵、組合鍵、原始 vk=0xNN 或文字文字）傳送到視窗
• set-value - 設定可編輯元素（文字、數字）的值;為了僅 TextPattern 的豐富編輯控制，則會退回到 LegacyIAccessible put_accValue 。
• focus - 移動鍵盤焦點
• scroll-into-view - 捲軸元素可見
• wait-for - 等待元素狀態
• list-windows - 列出應用程式的所有視窗
• get-focused - 報告當前聚焦的元素

選項：

• -a, --app <app> - Target 應用程式（名稱、標題或 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> - 每秒擷取幀數（預設 15）。
• --max-edge <px> - 縮小，使最長邊最多為此像素數（0 = 無下縮尺）。
• --capture-screen - 從螢幕擷取，包含覆蓋層/彈出視窗（可能捕捉遮蔽視窗）。
• -o, --output <path> - 輸出 .mp4 路徑（預設為 recording-<timestamp>-<guid>.mp4）。
• --frames- 寫入帶有時間戳記的 JPEG，frames.ndjson且manifest.json寫入。<output-name>.frames 支援 1-30 fps 及 --max-edge 64-4096（預設 1280），並有 1 GiB 的幀數上限。

其中 --json，最終結果包含輸出路徑、尺寸、編解碼器、擷取模式、節奏、停止理由、可選 frameArtifacts性 和 警告。

已知限制： 在彈出視窗中錄製 特定元素 ，該彈窗會呈現在自己的頂層視窗（WinUI/XAML flyout、教學提示、工具提示）中，可能會擷取底層的主視窗。 錄下整個視窗，或用 ui screenshot --capture-screen 來做彈出靜態畫面。 追蹤於 #646。

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