创建程序包清单

  • 项目

如果要将软件包提交到 Windows 程序包管理器社区存储库，请首先创建程序包清单。 清单是描述要安装的应用程序的 YAML 文件。

可以使用 Windows 程序包管理器清单创建程序YAMLCreate PowerShell 脚本，也可以按照以下说明手动创建清单。

注意

请参阅下面的清单常见问题解答，了解更多关于清单、包和版本的一般概要信息。

清单创建选项

使用 WinGetCreate 实用工具

可以使用以下命令安装 wingetcreate 实用工具。

winget install wingetcreate

安装后，可以运行 wingetcreate new 以创建新包并填写提示。 WinGetCreate 提示中的最后一个选项是将清单提交到包存储库。 如果选择“是”，则会自动将拉取请求 (PR) 提交到 Windows 程序包管理器社区存储库。

使用 YAMLCreate.ps1

为了帮助创作清单文件，我们提供了位于 Windows 程序包管理器社区存储库上的 Tools 文件夹中的 YAMLCreate.ps1 PowerShell 脚本。 使用脚本的方法是在电脑上克隆存储库，然后直接从 Tools 文件夹运行该脚本。 该脚本将提示你输入安装程序的 URL，然后提示你填写元数据。 与使用 WinGetCreate 类似，此脚本还提供自动提交清单的选项。

YAML 基础知识

之所以选择 YAML 格式作为程序包清单格式，是因为人类可以相当容易地阅读它，并且这样可与其他 Microsoft 开发工具保持一致。 如果不熟悉 YAML 语法，可以通过在 Y 分钟内学会 YAML 来学习基础知识。

注意

Windows 程序包管理器的清单当前并非支持所有 YAML 功能。 不支持的 YAML 功能包括定位点、复杂密钥和集。

约定

本文使用以下约定：

  • : 的左侧是清单定义中使用的文字关键字。
  • : 的右侧为数据类型。 数据类型可以是基元类型（例如字符串），也可以是对本文中其他地方定义的丰富结构的引用。
  • 表示法 [datatype] 表示所提到的数据类型的数组。 例如，[ string ] 是一个字符串数组。
  • 表示法 {datatype:datatype} 表示一种数据类型到另一种数据类型的映射。 例如，{ string: string } 是字符串到字符串的映射。

清单内容

程序包清单包含必需项以及可选项，用于帮助改善客户在安装软件时的体验。 本部分简要汇总了必需的清单架构和完整的清单架构，以及每种架构的示例。

清单文件中的每个字段都必须采用 Pascal 大小写形式，并且不能重复。

有关清单中的项的完整列表和说明，请参阅 Windows 程序包管理器社区存储库中的 清单规范。

必需的最小架构

正如单一实例 JSON 架构中所指定的那样，只有某些字段是必需的。 受支持的 YAML 文件至少应如下例所示。 单一实例格式仅对包含一个安装程序和一个区域设置的包有效。 如果提供了多个安装程序或区域设置，则必须使用多个 YAML 文件格式和架构。

添加分区架构是为了帮助改进 GitHub 的用户体验。 浏览器中无法很好地呈现具有成千上万个子文件的文件夹。

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

多个清单文件

为了提供最佳用户体验，清单应包含尽可能多的元数据。 为了区分验证安装程序和提供本地化元数据的问题，应将清单拆分为多个文件。 此类清单至少需要 3 个 YAML 文件。 还应提供其他区域设置。

以下示例显示了许多可选的元数据字段和若干区域设置。 请注意，默认区域设置的要求高于其他区域设置。 在 show 命令中，如果没有为其他区域设置提供必填字段，则将显示默认区域设置中的字段。

路径：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。

安装程序 命令 文档
MSI /q MSI 命令行选项
InstallShield /s InstallShield 命令行参数
Inno 设置 /SILENT or /VERYSILENT Inno 设置文档
Nullsoft /S Nullsoft 无提示安装程序/卸载程序

技巧与最佳做法

  • 包标识符必须是唯一的。 不能有多个具有相同程序包标识符的提交。 每个包版本只允许一个拉取请求。
  • 请避免创建多个发布者文件夹。 例如，如果已有“Contoso”文件夹，请不要再创建“Contoso Ltd.”文件夹。
  • 所有工具都必须支持静默安装。 如果可执行文件不支持静默安装，这时我们就无法提供该工具。
  • 请提供尽可能多的字段。 提供的元数据越多，用户体验就越好。 在某些情况下，Windows 程序包管理器客户端 (winget.exe) 可能尚不支持这些字段。 例如，AppMoniker 字段是可选的。 但是，如果你包含此字段，则客户在执行搜索命令（例如，用 vscode 来表示 Visual Studio Code）时会看到与 Moniker 值关联的结果。 如果只有一个应用具有指定的 Moniker 值，则客户可以通过指定名字对象（而不是完全限定的包标识符）来安装应用程序。
  • 此规范中字符串的换行长度应限制为 100 个字符。
  • PackageName 应匹配添加/删除程序中产生的条目来帮助关联清单，以支持导出和升级。
  • Publisher 应匹配添加/删除程序中产生的条目来帮助关联清单，以支持导出和升级。
  • MSI 格式的包安装程序使用产品代码来对应用程序进行唯一标识。 给定版本的包的产品代码应包含在清单中，以帮助确保最佳的升级体验。
  • 当程序包的指定版本存在多个安装程序类型时，可以在每个 Installers 下放置 InstallerType 的一个实例。

清单常见问题解答

什么是清单？

清单是包含元数据的 YAML 文件，Windows 程序包管理器使用这些元数据在 Windows 操作系统上安装和升级软件。 GitHub 上 winget-pkgs 存储库中的清单目录下有数千个这样的已分区文件。 必须对 Windows 程序包管理器目录结构进行分区，这样在查找清单时就不必在站点中进行太多滚动。

什么是包？

可以将包视为一个应用程序或软件程序。 Windows 程序包管理器使用“PackageIdentifier”来表示唯一的包。 通常采用 Publisher.Package 的形式。 有时你可能会遇到用第二个句点分隔的其他值。

什么是版本？

包版本与特定版本关联。 在某些情况下，你会看到一个语义完善的版本号，而在其他情况下，可能有所不同。 这些版本号可能是日期，也可能是其他特定于包含义的字符。 包版本的 YAML 键为“PackageVersion”。

有关了解目录结构和创建第一个清单的详细信息，请参阅 GitHub 上 winget-pkgs 存储库中的创作清单。