Создание и публикация элемента

  • Статья

Коллекция PowerShell — это место для публикации и совместного использования стабильных модулей PowerShell, скриптов и ресурсов DSC с большим сообществом пользователей PowerShell.

В этой статье рассматриваются механизмы и важные действия по подготовке скрипта или модуля с последующей публикацией в коллекции PowerShell. Мы настоятельно рекомендуем ознакомиться с требованиями для публикации, чтобы понять, как обеспечить более широкое применение опубликованных элементов пользователями коллекции PowerShell.

Ниже приведены минимальные требования для публикации модуля в коллекции PowerShell.

  • Учетная запись коллекции PowerShell и связанный с ней ключ API.
  • Убедитесь, что элемент содержит необходимые метаданные.
  • Убедитесь, что элемент готов к публикации с помощью средств предварительной проверки.
  • Опубликуйте элемент в коллекции PowerShell с помощью команд Publish-Module и Publish-Script.
  • Отвечайте на вопросы или предложения по поводу вашего элемента.

Коллекция PowerShell принимает модули PowerShell и скрипты PowerShell. Под скриптами подразумеваются скрипты PowerShell, которые являются отдельными файлами и не являются частью большего модуля.

Дополнительные сведения о настройке учетной записи коллекции PowerShell см. в статье Creating a PowerShell Gallery Account (Создание учетной записи коллекции PowerShell).

После создания учетной записи можно получить ключ API, необходимый для публикации элемента. После выполнения входа с помощью учетной записи ваше имя пользователя будет отображаться в верхней части страницы коллекции PowerShell вместо регистра. Щелкните свое имя пользователя, чтобы перейти на страницу "Моя учетная запись", где вы найдете ключ API.

Важно!

Надежно храните ключ API, как и имя входа и пароль. С этим ключом вы или другой пользователь может обновить любой элемент, которым вы владеете в коллекции PowerShell. Корпорация Майкрософт рекомендует регулярно обновлять ключ. Это можно сделать с помощью сброса ключа на странице "Моя учетная запись".

Коллекция PowerShell предоставляет пользователям коллекции сведения, полученные из полей метаданных, которые включены в скрипт или манифест модуля. При создании или изменении элементов для публикации в коллекции PowerShell применяются некоторые требования к сведениям, предоставляемым в манифесте элемента. Мы настоятельно рекомендуем ознакомиться с разделом метаданных элемента в требованиях для публикации, чтобы узнать, как предоставить необходимые сведения пользователям с помощью своих элементов.

Командлеты New-ModuleManifest и New-ScriptFileInfo создают шаблоны манифеста с заполнителями для всех элементов манифеста.

Оба манифеста имеют два раздела, которые важны для публикации: данные первичного ключа и область PSData в PrivateData. Данные первичного ключа в манифесте модуля PowerShell — это все, что находится за пределами раздела PrivateData. Набор первичных ключей привязан к используемой версии PowerShell, а неопределенные ключи не поддерживаются. PrivateData поддерживает добавление новых ключей, поэтому элементы, характерные для коллекции PowerShell, находятся в PSData.

Ниже приведены самые важные элементы манифеста, которые следует указать в элементе, который можно опубликовать в коллекции PowerShell.

  • Скрипт или имя модуля, которые получены от имен .PS1 для скрипта или .PSD1 для модуля.
  • Версия. Это обязательный первичный ключ, формат которого должен соответствовать требованиям SemVer. Подробности см. в рекомендациях.
  • Автор. Это обязательный первичный ключ, который содержит имя, связанное с элементом. См. раздел "Авторы и владельцы" ниже.
  • Описание. Это обязательный первичный ключ, который содержит краткое описание того, что делает этот элемент, и все требования для его использования.
  • ProjectURI — это настоятельно рекомендуемое поле URI в PSData, которое предоставляет ссылку на репозиторий GitHub или аналогичное расположение, в котором выполняется разработка элемента.
  • Теги — настоятельно рекомендуется пометить ваш пакет тегами в зависимости от его совместимости с различными PSEditions и платформами. Дополнительные сведения см. в разделе Рекомендации для публикации.

Авторы и владельцы коллекции элементов PowerShell. Это связанные понятия, которые не всегда совпадают. Владельцы элемента — это пользователи с учетными записями коллекции PowerShell, имеющие разрешения для поддержки элемента. Может существовать много владельцев, которые могут изменять любой элемент. Владелец может быть только в коллекции PowerShell и лишается этой роли, если элемент копируется из одной системы в другую. Автор. Это строка, встроенная в манифест данных, которая всегда является частью элемента. Ниже приведены рекомендации для элементов продуктов Майкрософт.

  • Вам нужно несколько владельцев. Имя хотя бы одного из них должно совпадать с именем группы, разрабатывающей элемент.
  • Автором должна быть хорошо известная группа (например, команда Azure SDK) или корпорация Майкрософт.

Предварительная проверка элемента

Существует несколько средств, необходимых для выполнения кода перед публикацией элемента в коллекции PowerShell:

  • Анализатор скриптов PowerShell, который находится в коллекции PowerShell.
  • Для модулей Test-ModuleManifest, который является частью PowerShell.
  • Для скриптов Test-ScriptFileInfo, который поставляется вместе с PowerShell Get.

Анализатор скриптов PowerShell — это средство статического анализа кода, которое будет просматривать код, чтобы убедиться в его соответствии основным правилам кодирования PowerShell. Это средство определяет общие и критические проблемы в коде и должно выполняться регулярно во время разработки, чтобы помочь подготовить элемент к публикации. Анализатор скриптов PowerShell предоставляет список проблем, которые определены как ошибки, предупреждения и сведения. Прежде чем публиковать элемент в коллекции PowerShell, все ошибки необходимо устранить. Необходимо изучить предупреждения и устранить большинство из них. Анализатор скриптов PowerShell выполняется каждый раз при публикации или обновлении элемента в коллекции PowerShell. Группа эксплуатации коллекции PowerShell свяжется с владельцами элементов, чтобы устранить найденные ошибки.

Если сведения манифеста элемента невозможно считать с использованием инфраструктуры коллекции PowerShell, вы не сможете его опубликовать. Командлет Test-ModuleManifest будет перехватывать распространенные проблемы, которые помешают использовать модуль при установке. Он должен выполняться для каждого модуля перед публикацией в коллекции PowerShell.

Аналогичным образом командлет Test-ScriptFileInfo проверяет метаданные в скрипте. Его нужно запускать для каждого скрипта (опубликованного отдельно от модуля) перед публикацией в коллекции PowerShell.

Публикация элементов

Чтобы опубликовать элементы в коллекции PowerShell, необходимо использовать командлет Publish-Script или Publish-Module. Для обеих команд требуется:

  • Путь к элементу, который необходимо опубликовать. Для модуля используйте папку с его именем. Если указать папку, содержащую несколько версий одного модуля, укажите RequiredVersion.
  • Ключ Nuget API. Это ключ API, который находится на странице "Моя учетная запись" в коллекции PowerShell.

Большинство других параметров в командной строке должны быть в данных манифеста элемента, который публикуется, поэтому нет необходимости указывать их в команде.

Чтобы избежать ошибок, перед публикацией мы настоятельно рекомендуем запускать команды с помощью -WhatIf -Verbose. Так вы сэкономите значительную часть времени, так как при каждой публикации в коллекции PowerShell необходимо обновить номер версии в разделе манифеста элемента.

Пример будет следующим:

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Внимательно просмотрите выходные данные и в случае отсутствия ошибок или предупреждений выполните команду повторно без -WhatIf.

Все элементы, публикуемые в коллекции PowerShell, будут проверяться на наличие вирусов и анализироваться с помощью анализатора скриптов PowerShell. Все ошибки, возникающие в процессе, будут отправляться обратно к издателю для устранения.

После публикации элемента в коллекции PowerShell необходимо следить за отзывами о вашем элементе.

  • Обязательно отслеживайте адрес электронной почты, связанный с учетной записью, которая использовалась для публикации. Пользователи и группа эксплуатации коллекции PowerShell будут отправлять отзывы на эту учетную запись, включая проблемы с PSSA или с антивирусным сканированием. Если учетная запись электронной почты недействительна или серьезные проблемы, отправленные на почту, остаются не решенными в течение долгого времени, элементы считаются устаревшими и будут удалены из коллекции PowerShell, как описано в условиях использования.