將 CLI 執行檔打包成 MSIX

本指南將引導你了解如何將現有的命令列執行檔打包成 MSIX 套件，透過 Windows 封裝管理員（winget）、Microsoft Store 或直接發行。

先決條件

  • 一個你想要打包的現有 CLI 執行檔 （.exe）
  • Windows 10 版本 1809 或更新版本

Steps

1. 組織您的 CLI 應用程式

把你的 CLI 執行檔和所有相依資料夾放在專用資料夾裡。 這個資料夾會包含所有應該包含在 MSIX 套件中的檔案。

mkdir MyCliPackage
cd MyCliPackage
# Copy your CLI executable and dependencies here

2. 安裝 winapp CLI

請透過 Windows 封裝管理員 安裝 winapp CLI，或如果你已經有最新版本，請更新到最新版本：

# Install (or update if already installed)
winget install microsoft.winappcli --source winget

3. 產生 Package.appxmanifest

產生基本的 Package.appxmanifest 以及你的 CLI 執行檔所需的資產：

winapp manifest generate --executable .\yourcli.exe

這個指令會在目前目錄中建立 Package.appxmanifest 一個檔案，預設值是從你的執行檔填入的。

4. 設定清單

編輯已產生的Package.appxmanifest以自訂你的套件。 以下每個子步驟都會說明該更改什麼以及為什麼要改。

4.1 新增所需命名空間

如果 Package 元素尚未有 uap5 命名空間，請將其加入。 這是步驟 4.3 執行別名所需要的：

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  ...
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap uap5 rescap">

4.2 配置應用程式元素

在元素中 <uap:VisualElements> ，新增 AppListEntry="none" 以隱藏應用程式，從開始選單中隱藏該應用程式。 CLI 工具是從終端機呼叫的，因此不需要開始選單的項目：

<uap:VisualElements
    DisplayName="YourApp"
    Description="My Application"
    BackgroundColor="transparent"
    Square150x150Logo="Assets\Square150x150Logo.png"
    Square44x44Logo="Assets\Square44x44Logo.png"
    AppListEntry="none">
</uap:VisualElements>

4.3 新增執行別名擴充

新增執行別名，讓使用者能在任何終端機視窗以名稱執行你的 CLI。 在<Application>元素內部（在<uap:VisualElements>後面）加入此項內容：

<Extensions>
  <uap5:Extension Category="windows.appExecutionAlias">
    <uap5:AppExecutionAlias>
      <uap5:ExecutionAlias Alias="yourcli.exe" />
    </uap5:AppExecutionAlias>
  </uap5:Extension>
</Extensions>

請替換 yourcli.exe 成你 CLI 所需的指令名稱。 一旦使用者安裝了 MSIX，就能用這個指令呼叫你的 CLI。

4.4 更新應用程式元資料

請更新以下欄位以符合您的 CLI 應用程式。

這很重要

你的清單中Publisher的值必須與簽章憑證中的發行者相符。 如果你之後產生憑證（步驟5），它會使用你的清單上的出版商。 如果你在產生憑證後更改出版商，就需要重新生成憑證以匹配。

  • Identity：更新 Name、Publisher，以及 Version

    <Identity
  Name="YourCompany.YourCLI"
  Publisher="CN=Your Company"
  Version="1.0.0.0" />

  • 屬性：更新顯示名稱、出版者顯示名稱及描述

    <Properties>
  <DisplayName>Your CLI Tool</DisplayName>
  <PublisherDisplayName>Your Company</PublisherDisplayName>
  <Description>Description of your CLI tool</Description>
  <Logo>Assets\StoreLogo.png</Logo>
</Properties>

  • VisualElements：更新顯示名稱和資產引用

    <uap:VisualElements
  DisplayName="Your CLI Tool"
  Description="Description of your CLI tool"
  BackgroundColor="transparent"
  Square150x150Logo="Assets\Square150x150Logo.png"
  Square44x44Logo="Assets\Square44x44Logo.png">
  <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" />
  <uap:SplashScreen Image="Assets\SplashScreen.png" />
</uap:VisualElements>

注意：你也應該在套件目錄的資料夾 Assets 中新增適當的圖示資產。 雖然應用程式不會出現在開始選單，但提交商店時仍需圖示，且可能出現在其他情境中。

5. （可選）產生開發證書

若要在 Microsoft Store 以外的本地測試和發佈，你需要用憑證簽署你的 MSIX 套件。

產生開發證書。 請將它放在 CLI 資料夾之外，以避免不小心包含在套件中：

# Navigate to a location outside your CLI folder (e.g., your home directory)
cd ~
winapp cert generate

這會在你的家庭目錄中建立一個 devcert.pfx 檔案（例如， C:\Users\yourname\devcert.pfx）。

要在你的開發機器上信任此憑證，請安裝它（需要管理員權限）：

# Run PowerShell as Administrator
winapp cert install ~\devcert.pfx

6. 封裝您的 CLI

現在你準備好建立 MSIX 套件了：

# Navigate back outside of your project folder
# Package with dev certificate (for local testing/distribution)
winapp pack .\path\to\MyCliPackage --cert .\path\to\devcert.pfx

這會在目前目錄中建立一個 .msix 檔案。

7. 安裝與驗證

安裝 MSIX 套件以確認一切正常運作：

Add-AppxPackage .\MyCliPackage.msix

如果你在第 4.3 步新增了執行別名，現在你可以從任何終端機執行你的 CLI：

yourcli --help

要在之後卸載：

Get-AppxPackage *YourCLI* | Remove-AppxPackage

Tips

  1. 一旦準備好分發，你可以用憑證授權中心的程式碼簽署憑證來簽署 MSIX，這樣使用者就不必安裝自簽憑證
  2. Microsoft Store 會幫你簽署 MSIX，提交前不需要簽名。
  3. 你可能需要建立多個 MSIX 套件，分別針對你支援的每種架構（x64、Arm64）

後續步驟

  • Last updated on