Создание манифеста пакета

  • Статья

Если вы хотите отправить пакет программного обеспечения в репозиторий сообщества Диспетчера пакетов Windows, сначала создайте манифест пакета. Манифест — это YAML-файл, описывающий устанавливаемое приложение.

Вы можете использовать средство создания манифестов Диспетчера пакетов Windows, скрипт PowerShell YAMLCreate или создать манифест вручную, следуя приведенным ниже инструкциям.

Примечание.

Дополнительные общие сведения о манифестах, пакетах и версиях см. в разделе Часто задаваемые вопросы о манифесте.

Возможности создания манифеста

Использование служебной программы WinGetCreate

Служебную программу wingetcreate можно установить с помощью указанной ниже команды.

winget install wingetcreate

После установки можно создать новый пакет и указать данные для запросов, выполнив wingetcreate new. Последний параметр в WinGetCreate выполнит запрос, чтобы отправить манифест в репозиторий пакетов. Если выбрать вариант "Да", запрос на вытягивание (PR) будет автоматически отправлен в репозиторий сообщества Диспетчера пакетов Windows.

Использование YAMLCreate.ps1

Чтобы упростить создание файлов манифеста, мы предоставили скрипт PowerShell YAMLCreate.ps1, расположенный в папке Tools в репозитории сообщества Диспетчера пакетов Windows. Вы можете использовать скрипт, клонировав репозиторий на компьютер, и запустить скрипт непосредственно из папки Инструменты. Скрипт отправит вам запрос на ввод URL-адреса установщика, а затем — запрос на указание метаданных. Как и при использовании WinGetCreate, этот скрипт предлагает возможность автоматической отправки манифеста.

Основы YAML

Формат YAML был выбран для манифестов пакетов из-за его относительной простоты чтения для человека и согласованности с другими средствами разработки Майкрософт. Если вы не знакомы с синтаксисом YAML, вы можете быстро ознакомиться с основами в этой статье.

Примечание.

Манифесты для Диспетчера пакетов Windows в настоящее время поддерживают не все функции YAML. Среди неподдерживаемых функций YAML привязки, сложные ключи и наборы.

Соглашения

В этой статье используется следующий подход:

  • Слева от : находится ключевое слово literal, используемое в определениях манифеста.
  • Справа от : расположен тип данных. Тип данных может быть примитивным, например string, или ссылкой на обширную структуру, определенную в других местах этой статьи.
  • Запись [тип данных] указывает на массив данных упомянутого типа. Например, [ string ] — это массив строк.
  • Запись {тип данных:тип данных} указывает на сопоставление данных одного типа с данными другого типа. Например, { 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

Несколько файлов манифеста

Для удобства манифесты должны содержать как можно больше метаданных. Чтобы разделить задачи проверки установщиков и предоставления локализованных метаданных, манифесты следует разбить на несколько файлов. Минимальное число файлов YAML для этого типа манифеста — 3. Также должны быть предоставлены дополнительные языковые стандарты.

В приведенном ниже примере показано множество необязательных полей метаданных и несколько языковых стандартов. Обратите внимание, что языковой стандарт по умолчанию имеет больше требований, чем дополнительные языковые стандарты. В команде 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 Ltd, если папка Contoso уже существует.
  • Все средства должны поддерживать автоматическую установку. Если у вас есть исполняемый файл, который не поддерживает автоматическую установку, в настоящее время мы не можем предоставить этот инструмент.
  • Укажите максимально возможное количество полей. Чем больше метаданных вы предоставляете, тем лучше будет пользовательский опыт. В некоторых случаях поля могут еще не поддерживаться клиентом Диспетчера пакетов Windows (winget.exe). Например, поле AppMoniker является необязательным. Однако если его включить, при выполнении команды search клиенты увидят результаты, связанные со значением Moniker (например, vscode для Visual Studio Code). Если имеется только одно приложение с указанным значением Moniker, клиенты могут установить приложение, указав моникер вместо полного идентификатора пакета.
  • Длина строк в этой спецификации не должна превышать 100 символов до разрыва строки.
  • Компонент PackageName должен соответствовать записи в окне Установка и удаление программ, чтобы обеспечить корреляцию с манифестами для поддержки команд export и upgrade.
  • Компонент Publisher должен соответствовать записи в окне Установка и удаление программ, чтобы обеспечить корреляцию с манифестами для поддержки команд export и upgrade.
  • Установщики пакетов в формате MSI используют коды продуктов для уникальной идентификации приложений. Код продукта для данной версии пакета должен быть добавлен в манифест, чтобы повысить удобство при выполнении команды upgrade.
  • Если для указанной версии пакета существует несколько типов установщика, под каждый раздел Installers можно поместить экземпляр InstallerType.

Часто задаваемые вопросы о манифесте

Что такое манифест?

Манифесты — это файлы YAML, содержащие метаданные, используемые Диспетчером пакетов Windows для установки и обновления программного обеспечения в операционной системе Windows. В репозитории winget-pkgs на сайте GitHub есть тысячи этих файлов, разбитых по разделам в каталоге манифестов. Структура каталогов Диспетчера пакетов Windows должна быть разбита на разделы, чтобы не приходилось долго прокручивать страницу сайта при поиске манифеста.

Что такое пакет?

Думайте о пакете как о приложении или программе. Диспетчер пакетов Windows использует PackageIdentifier для представления уникального пакета. Обычно пакеты находятся в виде Publisher.Package. Иногда могут отображаться дополнительные значения, разделенные второй точкой.

Что такое версия?

Версии пакетов связаны с определенным выпуском. В одних случаях вы увидите идеально сформированные семантические номера версий, а в других случаях вы можете увидеть что-то иное. Они могут основываться на дате или могут иметь другие символы с определенным значением пакета. Ключом YAML для версии пакета является PackageVersion.

Дополнительные сведения о структуре каталогов и создании первого манифеста см. в статье Создание манифестов в репозитории winget-pkgs на сайте GitHub.