建立封裝資訊清單

  • 發行項

如果要將軟體封裝提交到​​ Windows 封裝管理員社群存放庫，請首先建立封裝資訊清單。 資訊清單是 YAML 檔案，用於描述要安裝的應用程式。

您可以使用Windows 封裝管理員資訊清單建立程式: YAMLCreate PowerShell 指令碼，或者您可以按照以下說明手動建立資訊清單。

注意

如需說明資訊清單、封裝和版本的一般性高層級資訊，請參閱下列 資訊清單常見問題 。

資訊清單建立的選項

使用 WinGetCreate 公用程式

您可以使用下列命令來安裝 wingetcreate 公用程式。

winget install wingetcreate

安裝之後，您可以執行 wingetcreate new 來建立新的封裝，並填入提示。 WinGetCreate 提示的最後一個選項是將資訊清單提交至封裝存放庫。 如果您選擇 [是]，則會自動將提取要求 (PR) 提交至 Windows 封裝管理員社群存放庫。

使用 YAMLCreate.ps1

為了協助撰寫資訊清單檔案，我們在 Windows 封裝管理員社群存放庫上的 [工具] 資料夾中提供了 YAMLCreate.ps1 Powershell 指令碼。 要使用指令碼，您可以複製電腦上的存放庫，然後直接從 [工具] 資料夾執行指令碼。 指令碼將會提示您輸入安裝程式的 URL，然後會提示您填入中繼資料。 如同使用 WinGetCreate 一樣，這個指令碼會提供自動提交資訊清單的選項。

YAML 基本概念

YAML 是專為封裝資訊清單所選擇的格式，因為相對於其他 Microsoft 開發工具，此格式較容易閱讀且一致性高。 如果您不熟悉 YAML 語法，您可以在 Y 分鐘速成 YAML (Learn YAML in Y Minutes) 中了解基本概念。

注意

Windows 封裝管理員的資訊清單目前未支援所有 YAML 功能。 不支援的 YAML 功能包括錨點、複雜索引鍵和集合。

慣例

本文會使用以下慣例：

  • : 的左邊是用於資訊清單定義的常值關鍵字。
  • : 的右邊是資料類型。 資料類型可以是基本類型 (例如 字串) 或本文中其他位置所定義的豐富結構參考。
  • [datatype] 標記法表示所述資料類型的陣列。 例如，[ string ] 是字串陣列。
  • {datatype:datatype} 標記法表示一種資料類型對應到另一種資料類型。 例如，{ string: string } 是字串與字串的對應。

資訊清單內容

封裝資訊清單包含必要項目和選擇性項目，可協助改善客戶安裝軟體的體驗。 本章節將提供必要資訊清單結構描述和完整資訊清單結構描述的簡短摘要，以及每個結構描述的範例。

資訊清單檔案中的每個欄位都必須依照 Pascal 命名法的大小寫慣例，而且不能重複。

如需資訊清單中項目的完整清單和描述，請參閱 Windows 封裝管理員社群存放庫 中的 [資訊清單規格]。

最基本的必要結構描述

如 單一 JSON 架構描述 中所指出，只有指定的欄位為必填。 最低支援的 YAML 檔案看起來會像下列範例。 單一格式僅適用於包含單一安裝程式和單一地區設定的封裝。 如果提供多個安裝程式或地區設定，則必須使用多個 YAML 檔案格式和架構描述。

已新增磁碟分割架構描述以協助 GitHub 的 UX。 具有數千個子項目的資料夾在瀏覽器中轉譯不會良好。

PackageIdentifier:  # Publisher.package format.
PackageVersion:     # Version numbering format.
PackageLocale:      # BCP 47 format (e.g. en-US)
Publisher:          # The name of the publisher.
PackageName:        # The name of the application.
License:            # The license of the application.
ShortDescription:   # The description of the application.
Installers: 
 - Architecture:    # Enumeration of supported architectures.
   InstallerType:   # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx).
   InstallerUrl:    # Path to download installation file.
   InstallerSha256: # SHA256 calculated from installer.
ManifestType:       # The manifest file type
ManifestVersion: 1.6.0

多個資訊清單檔案

為了提供最佳的使用者體驗，資訊清單應該包含盡可能多的中繼資料。 為了區分驗證安裝程式並提供當地語系化中繼資料的考慮，資訊清單應該分割成多個檔案。 這種資訊清單的 YAML 檔案數目下限為三個。 也應該提供其他地區設定。

下列範例顯示許多選擇性中繼資料欄位和多個地區設定。 請注意，預設地區設定的需求超過其他地區設定。 在 [顯示命令]中，未針對其他地區設定提供的任何必要欄位都會顯示預設地區設定的欄位。

路徑: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml

PackageIdentifier: "Microsoft.WindowsTerminal"
PackageVersion: "1.6.10571.0"
DefaultLocale: "en-US"
ManifestType: "version"
ManifestVersion: "1.6.0"

注意

如果您的安裝程式是 .exe，且其為使用 Nullsoft 或 Inno 所建立，則可以改為指定這些值。 當指定 Nullsoft 或 Inno 時，用戶端會自動為安裝程式設定「無訊息」和「無訊息處理程序」的安裝行為。

安裝程式參數

您通常可藉由從命令列將 -? 傳遞至安裝程式，找出安裝程式可使用的無訊息 Switches。 以下是一些可用於不同安裝程式類型的常見無訊息 Switches。

安裝程式 Command 文件
MSI /q MSI 錄製進行
InstallShield /s InstallShield 命令列參數
Inno 設定 /SILENT or /VERYSILENT Inno 安裝文件
Nullsoft /S Nullsoft 無訊息安裝程式/解除安裝程式

訣竅和最佳做法

  • 封裝識別碼必須是唯一的。 您不能以相同封裝識別碼進行多次提交。 每個封裝版本只允許一個提取要求。
  • 請避免建立多個發行者資料夾。 例如，如果已經有 "Contoso" 資料夾，請勿再建立 "Contoso Ltd"。
  • 所有工具都必須支援無訊息安裝。 如果您的可執行檔不支援無訊息安裝，則目前無法提供此工具。
  • 提供盡可能多的欄位。 您提供的中繼資料越多，使用者體驗就越好。 在某些情況下，Windows 封裝管理員用戶端 (winget.exe) 可能尚未支援欄位。 例如，AppMoniker 欄位是選擇性的。 不過，如果您包含此欄位，在執行 search 命令時，客戶會看到與 Moniker 值相關聯的結果 (例如，vscode 代表 Visual Studio Code)。 如果只有一個應用程式具有指定的 Moniker 值，則客戶可以藉由指定別名，而不是指定完整封裝識別碼，來安裝應用程式。
  • 此規格中的字串長度應該限制在分行符號之前 100 個字元。
  • PackageName 應符合 [新增/移除程式] 中的專案，以協助與資訊清單相互關聯，以支援 匯出，以及 升級。
  • Publisher 應符合 [新增/移除程式] 中的專案，以協助與資訊清單相互關聯，以支援 匯出，以及 升級。
  • MSI 格式的封裝安裝程式會使用 產品代碼 來唯一識別應用程式。 指定版本的封裝的產品代碼應包含在資訊清單中，以協助確保最佳 升級 體驗。
  • 如果指定版本的封裝有一個以上的安裝程式類型，則 InstallerType 的執行個體可以放在每個 Installers 底下。

資訊清單常見問題

什麼是資訊清單?

資訊清單是 YAML 檔案，其中包含 Windows 封裝管理員用來在 Windows 作業系統上安裝和升級軟體的中繼資料。 GitHub 上 winget-pkgs 存放庫中的資訊清單目錄下，有數千個這種分割的檔案。 Windows 封裝管理員目錄結構必須進行分割，這樣在尋找資訊清單時，才不需要在網站中捲動太久。

何謂套件？

封裝就好像是應用程式或軟體程式。 Windows 封裝管理員會使用 「PackageIdentifier」 來代表唯一的封裝。 它們通常是 Publisher.Package 的形式。 有時候您可能會看到以第二個期間分隔的其他值。

什麼是版本?

封裝版本與特定版本相關聯。 在某些情況下，您會看到完全形成的語意版本號碼，在其他情況下，您可能會看到不同的內容。 這些可能是日期驅動，或它們可能有其他字元與某些封裝特定的意義。 封裝版本的 YAML 金鑰是「PackageVersion」。

如需了解目錄結構和建立第一個資訊清單的詳細資訊，請參閱在 GitHub 上的 winget-pkgs 存放庫中 撰寫資訊清單。