使用 WinApp CLI 搭配 WinUI

本指南展示了如何在 WinUI 3 應用程式的完整內圈中使用 Winapp CLI：從官方範本建立專案，以套件識別建置並啟動應用程式，除錯當機，尋找控制項與 API，自動化 UI，並產生簽署的 MSIX 套件。 每個步驟都從命令列執行，因此在任何編輯器、CI 和 AI 編碼代理中都能運作。

WinUI 專案範本已經包含 Package.appxmanifest，所以你不需要為 WinUI 應用程式執行 winapp init 。 如果你要為一個不使用 WinUI 的現有 .NET 應用程式新增套件身份，請參考「使用 Winapp CLI 搭配 .NET」。

Prerequisites

  • Windows 10 版本 1809 或更新版本，或 Windows 11。

  • .NET SDK 版本為 8.0.100 或更新版本。 實驗性的 Reactor 範本需要 .NET 10 SDK。 Winapp CLI 不會安裝工具鏈，所以如果缺少 .NET SDK，winapp new 和 winapp run 會停止並提供指引。

  • winapp CLI：

    winget install Microsoft.winappcli --source winget

  • 開發人員模式，Windows 需要此模式，才能從你的建置輸出註冊應用程式。 在設定 > 系統 > 開發人員選項中開啟。 如需瞭解這會對你的電腦造成哪些變更，請參見 安全性。

建立 WinUI 應用程式

winapp new 使用官方 Microsoft.WindowsAppSDK.WinUI.CSharp.Templates 套件為 WinUI 應用程式產生骨架。 它會按需安裝或更新範本包，然後替你呼叫 dotnet new。

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

執行 winapp new --list 來查看已安裝套件中的範本。 該包包含以下範本：

Template Description
winui 最小空白 XAML 應用程式（預設） 請參見截圖
winui-navview XAML 應用程式搭配 NavigationView 殼層。 請參見截圖
winui-tabview 使用 TabView 殼層的 XAML 應用程式 請參見截圖
winui-mvvm XAML 應用程式使用 MVVM 模式並搭配 CommunityToolkit.Mvvm。 請參見截圖
winui-lib WinUI 類別函式庫
winui-unittest 用於 WinUI 單元測試的 MSTest 封裝專案
reactor、reactor-mvu、reactor-navview、reactor-tabview 實驗性。 WinUI 應用程式只用 C# 撰寫，沒有 XAML

Note

Reactor 範本參考的是預發布 Microsoft.UI.Reactor 套件。 他們的 API 可能會在未來版本中更改或移除。

每個選項請參考new指令參考。

建置並使用身分執行

從專案資料夾中執行 winapp run 以建立專案，安裝符合你架構的 Windows 應用程式 SDK 執行環境（如果缺少的話），用套件身分識別註冊應用程式，然後啟動應用程式。

cd MyApp
winapp run

winapp run 接受專案檔案、解決方案檔案、包含其中之一的資料夾，或是建置輸出資料夾：

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

Winapp CLI 會讀取專案屬性 WindowsPackageType 來決定如何啟動它。 一個打包專案會以套件身份執行。 將 WindowsPackageType 設為 None 的專案會以沒有身分識別的未封裝應用程式執行。 若要以未封裝方式執行已封包的專案，請在命令列傳遞以下屬性：

winapp run -p WindowsPackageType=None

其他有用的選項包括 --clean 移除先前的註冊資料及應用程式儲存的資料（LocalState 與設定），以進行全新首次執行; --no-launch 無需啟動應用程式即可註冊;以及 --detach --json 回傳處理程序 ID 後結束，讓腳本和代理在應用程式執行時仍能繼續運作。 完整清單請參見 Project mode（.NET SDK 專案）。

改用 dotnet run

如果你喜歡 dotnet run，可以用 Microsoft.Windows.SDK.BuildTools.WinApp NuGet 套件。 套件會掛接 dotnet run 鉤，讓它呼叫 winapp run，並以身分識別啟動應用程式。 你用 winapp new 建立的專案已經參考了套件，所以 dotnet run 不需要額外設定就能運作。 其他專案請先加入套件：

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

你可以將 winapp run 選項作為 WinAppRun* MSBuild 屬性傳遞，例如 dotnet run -p:WinAppRunDebugOutput=true。 要關閉整合，請在專案檔案中將 EnableWinAppRunSupport 設為 false。 詳情請參見 dotnet run 支援。

對當機進行除錯

在應用程式運行時，還能加入 --debug-output 捕捉 OutputDebugString 訊息和第一次機會例外。 當 WinUI 應用程式因 stowed 例外失敗時，winapp CLI 會分析崩潰傾印，並列印原始錯誤與呼叫堆疊，而非一般的失敗程式碼。

winapp run --debug-output

加入 --symbols 以下載符號，取得完整的原生函式名稱。 因為 --debug-output 會將 winapp CLI 附加為除錯器，你無法把 Visual Studio 或其他除錯器附加到同一個程序上。 若想用你的 IDE 除錯，請參考 Debugging with winapp CLI。 關於 stowed-exception 分析的詳細資訊，請參見 WinUI stowed-exception 分類。

尋找控制項與 API

winapp find-ui依意圖搜尋 WinUI Gallery 和 Windows Community Toolkit 中的 XAML 和 C# 範例，並回傳你選擇的情境程式碼。 winapp find-api搜尋你專案所參考的 Windows 與 WinRT API 介面範圍，例如 Windows 應用程式 SDK 及 Windows SDK 類型、成員與枚舉。

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

這兩個指令都支援 --json，因此 AI 編碼代理可以使用它們來選擇控制項並驗證 API 名稱。 欲了解更多資訊，請參閱 find-ui 與 find-api 參考資料。

自動化並驗證使用者介面

winapp ui透過 Microsoft 使用者介面自動化 驅動正在執行的應用程式。 用它檢查元素樹、呼叫控制項、等待狀態變化，以及截圖。 客服人員也可以用相同的指令來檢查自己的變更。

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

PART_PaneToggleButton選取器會指定範本中的winui-navview選單按鈕。 對於你自己的控制，可以從 winapp ui search 或 winapp ui inspect 的輸出中複製一個選擇器。

若要在 Windows 沙盒中執行應用程式，而不是在桌面上執行，請將 --on sandbox 新增至 winapp run 和 winapp ui。 欲了解更多資訊，請參閱 UI 自動化 與 沙盒執行。

封裝並簽署

當你準備好在本地測試套件時，產生與你的清單相符的開發憑證，然後一步完成建置與打包專案：

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack 建構專案並產生一個已簽署的 .msix。 若要將多個架構的建置合併成單一 .msixbundle，請參見 多架構套件。 專案必須被打包，所以將 WindowsPackageType 設為 None 的專案無法被打包。 對於 WinUI 專案，Windows 應用程式 SDK 建置會管理資訊清單、進入點和資源產生，因此 --manifest、--executable 和 --skip-pri 不被接受。

開發憑證僅用於本地測試，且使用預設密碼。 在你發佈應用程式之前，請用受信任的憑證簽署，例如使用 winapp az-sign 和 Azure 信任簽署。 欲了解更多資訊，請參閱《直接打包專案》及《安全性》。

現有的 WinUI 專案

Winapp CLI 可搭配你在 Visual Studio 建立的 WinUI 專案使用。 指向 winapp run 專案檔案、解決方案檔案，或包含其中一個檔案的資料夾。 針對 winapp pack，傳入 .csproj。 你可以繼續在 Visual Studio 中建置和除錯，並使用 winapp CLI 來處理腳本、CI 和代理程式工作流程。

WinUI 搭配 C++

winapp run同時也能建立並啟動你從 Visual Studio .vcxproj 範本建立的 C++/WinRT WinUI 專案。 它會用 Visual Studio 的 MSBuild 建置專案，註冊應用程式的套件身份，然後啟動：

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++ 專案需要使用 Visual Studio 或 Visual Studio 建置工具，搭配 使用 C++ 的桌面開發 工作負載及 C++ WinUI 應用程式開發工具。 winapp pack不會建構.vcxproj專案，所以請在 Visual Studio 中建立 MSIX 套件。 關於先修條件與選項，請參見 C++ 專案 (.vcxproj)。 對於不使用 WinUI 的 C++ 應用程式，請參見「 使用 Winapp CLI 搭配 C++」。

Samples

  • winui-app：已封裝的 WinUI 應用程式，且已設定好可供 winapp ui 自動化使用的控制項
  • winui-unpackaged-app：一個沒有套件識別的 WinUI 應用程式
  • winui-solution：一個多專案解決方案，展示應用程式專案如何選取 winapp run
  • cpp-winui-app：一個封裝的 C++/WinRT WinUI 應用程式（Visual Studio .vcxproj 搭配 XAML），可搭配 winapp run 執行

下一步

  • 上次更新時間：