Поделиться через

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

  • Статья

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

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

Примечание.

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

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

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

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

winget install wingetcreate

После установки можно запустить wingetcreate new, чтобы создать новый пакет и заполнить запросы. Последний параметр в WinGetCreate позволяет отправить манифест в репозиторий пакетов. Если вы выберете "Да", ваш pull-request (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

Советы и рекомендации

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

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

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

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

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

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

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

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

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