Руководства и рекомендации для публикации коллекции PowerShell

Статья
06/26/2023

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

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

См. дополнительные сведения о создании и публикации пакета в коллекции PowerShell.

Мы будем рады получить ваши отзывы об этом руководстве. Чтобы оставить отзыв, перейдите на вкладку с вопросами в репозитории документации GitHub.

Используйте PSScriptAnalyzer.

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

Мы рекомендуем запустить Invoke-ScriptAnalyzer с предупреждением -Recurse и -Severity.

Просмотрите результаты и убедитесь, что:

в документации исправлены или устранены все ошибки;
все предупреждения проверены и по возможности устранены.

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

Добавление документации и примеров

Документация и примеры — это лучший способ для пользователей воспользоваться преимуществами любого общего кода.

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

Рекомендации по предоставлению справки см. в статье How to Write Cmdlet Help (Как писать справку по командлетам).
Создание справки по командлетам (самый оптимальный вариант для любого скрипта, функции или командлета PowerShell). См. дополнительные сведения о написании справки по командлетам. Сведения о том, как добавить справку в скрипт, см. в статье About Comment Based Help (Справка на основе комментариев).
Много модулей также содержат документацию в текстовом формате, например файлы MarkDown. Это может быть особенно полезно при наличии сайта проекта на GitHub, где часто используется формат Markdown. Мы рекомендуем использовать GitHub Flavored Markdown.

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

Хороший образец для примеров можно найти в модуле PSDscResource в папке Examples\RegistryResource. Существует четыре примера варианта использования с кратким описанием в верхней части каждого файла, которые содержат сведения о рассматриваемых вариантах.

Управление зависимостями

В манифесте модуля важно указать модули, от которых зависит ваш модуль. Это позволит конечному пользователю не беспокоиться об установке правильных версий модулей, от которых зависит ваш модуль. Чтобы указать зависимые модули, следует использовать требуемое поле модуля в манифесте модуля. При этом все указанные модули будут загружены в глобальную среду до импорта модуля (если они еще не загружены). Так, некоторые модули могли быть загружены другим модулем. Можно также указать определенную версию для загрузки с помощью поля RequiredVersion, а не поля ModuleVersion. При использовании поля ModuleVersion будет загружаться последняя доступная версия не ниже указанной. Если не использовать поле RequiredVersion для указания конкретной версии, важно отслеживать обновления версий для требуемого модуля. Особенно важно учитывать все критические изменения, которые могут повлиять на работу пользователей с вашим модулем.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Обратная связь с пользователями

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

В коллекции PowerShell можно использовать следующий метод обратной связи:

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

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

Если в любом из этих каналов связи наблюдается неуместное поведение, воспользуйтесь функцией Report Abuse (Сообщить о нарушении) коллекции PowerShell, чтобы связаться с администраторами коллекции.

Модули и скрипты

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

Структура папок модулей PowerShell позволяет включать в пакет несколько папок и файлов. Структура модуля позволяет добавлять другие пакеты, перечисленные в списке рекомендаций: справка по командлетам, документация, примеры и тесты. Существенным недостатком является то, что скрипт внутри модуля должен предоставляться и использоваться как функция. Сведения о создании модуля см. в статье Writing a Windows PowerShell Module (Написание модуля Windows PowerShell).

Существуют ситуации, когда скрипт улучшает взаимодействие с пользователем, в особенности с конфигурацией DSC. Мы рекомендуем опубликовать конфигурацию DSC как скрипт с сопутствующим модулем, содержащим документы, примеры и тесты. Скрипт указывает сопутствующий модуль с помощью RequiredModules = @(Name of the Module). Этот подход можно использовать для любого скрипта.

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

Предоставление ссылки на сайт проекта

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

Чтобы добавить ссылку, включите ProjectURI в раздел PSData манифеста следующим образом:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Если указан ProjectURI, коллекция PowerShell будет отображать ссылку на сайт проекта в левой части страницы пакета.

Пометьте пакет с указанием совместимых PSEditions и платформ

Чтобы продемонстрировать пользователям, какие пакеты хорошо взаимодействуют со средой, используйте следующие теги:

PSEdition_Desktop: пакеты, которые совместимы с Windows PowerShell
PSEdition_Core: пакеты, совместимые с PowerShell 6 и более поздними версиями.
Windows: пакеты, которые совместимы с операционной системой Windows
Linux: пакеты, которые совместимы с операционной системой Linux
MacOS: пакеты, которые совместимы с операционной системой компьютеров Mac

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

Включение тестов

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

Мы рекомендуем написать тест, чтобы воспользоваться преимуществами тестовой платформы Pester, разработанной специально для PowerShell. Pester доступен на сайте GitHub, в коллекции PowerShell и предоставляется в Windows 10, Windows Server 2016, WMF 5.0 и WMF 5.1.

Сайт проекта Pester в GitHub содержит отличную документацию по написанию тестов Pester для начинающих и продвинутых пользователей.

Целевые объекты для тестов указаны в документации по высококачественному модулю ресурсов с рекомендуемым покрытием кода модульных тестов 70 %.

Включите условия лицензионного соглашения и/или предоставьте ссылку на них.

Для всех пакетов, опубликованных в коллекции PowerShell, необходимо указать условия лицензии, или же использование пакета должно регулироваться лицензией, представленной в приложении А к условиям использования. Чтобы указать другую лицензию, лучше всего предоставить на нее ссылку с помощью LicenseURI в PSData. Дополнительные сведения см. в статье о манифесте пакета и пользовательском интерфейсе коллекции.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Подписание кода

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

подписание файлов скрипта;
подписание модулей каталога.

Подписание файлов PowerShell — это проверенный способ предоставить гарантию того, что выполняемый код создан с помощью надежного источника и не изменялся. Сведения о том, как подписать файлы скрипта PowerShell, приводятся в этой статье. Вообще, подпись можно добавить в любой файл .PS1, который проверяется PowerShell во время загрузки скрипта. Действия PowerShell можно ограничить с помощью командлетов политики выполнения, чтобы обеспечить использование подписанных скриптов.

Функция подписания модулей каталога была добавлена в PowerShell версии 5.1. Сведения о подписании модулей см. в статье Командлеты для работы с каталогами. Для подписания каталога создается файл каталога, содержащий значение хэша для каждого файла модуля, после чего подписывается файл.

Командлеты PowerShellGetPublish-Module, Install-Module и Update-Module проверят достоверность подписи, а затем подтвердят, что значение хэша каждого пакета соответствует значениям в каталоге. Save-Module не проверяет подпись. Если в системе установлена предыдущая версия модуля, в командлете Install-Module будет показано, что заверитель подписи для новой версии совпадает с заверителем для установленной ранее. Install-Module и Update-Module будут использовать подпись для файла .PSD1, если для пакета не подписан каталог. Подписание каталога работает с подписанными файлами скрипта, но не заменяет их. PowerShell не выполняет проверку подписи каталога во время загрузки модуля.

Следуйте рекомендациям SemVer по управлению версиями

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

Она должна быть обозначена числовым блоком с тремя сегментами, разделенными точками, например 0.1.1 или 4.11.192.
Если номер версии начинается с 0, это значит, что пакет еще не готов к использованию в рабочей среде. Версия должна начинаться с 0, только если она является единственной.
Изменения в первом числе (1.9.9999 на 2.0.0) указывают на основные и критические изменения в версиях.
Изменения во втором числе (1.1 на 1.2) указывают на изменения на уровне компонента, например добавление новых командлетов в модуль.
Изменения в третьем числе указывают на некритические изменения, например новые параметры, обновленные примеры или новые тесты.
При перечислении версий PowerShell отсортирует версии как строки. Поэтому 1.01.0 будет считаться новее 1.001.0.

PowerShell была создана перед публикацией SemVer, поэтому она поддерживает большинство элементов SemVer, в частности:

Она не поддерживает строки предварительной версии в номерах версий. Это удобно, если издателю необходимо обнародовать предварительную версию новой основной версии после выпуска версии 1.0.0. Эта функция будет добавлена в будущих выпусках коллекции PowerShell и командлетов PowerShellGet.
PowerShell и коллекция PowerShell позволяют использовать строки версии с 1, 2 и 4 сегментами. Многие предыдущие версии модулей не соответствовали рекомендациям, а выпуски продуктов корпорации Майкрософт обозначались блоками из четырех чисел (например, 5.1.14393.1066). С точки зрения управления версиями эти различия игнорируются.

Тестирование с помощью локального репозитория

Коллекция PowerShell не должна использоваться для тестирования процесса публикации. Лучший способ протестировать весь процесс публикации в коллекции PowerShell — настроить и использовать ваш собственный локальный репозиторий. Это можно сделать несколькими способами:

Настройте локальный экземпляр коллекции PowerShell с помощью проекта закрытой коллекции PS в GitHub. Предварительная версия проекта поможет вам создать управляемый экземпляр коллекции PowerShell, который можно использовать для тестов.
Настройте внутренний репозиторий Nuget. Данный способ более трудоемкий, однако он позволит вам проверить соответствие еще ряду требований (например, проверить использование ключа API и наличие в целевом объекте зависимостей при публикации).
Настройте общую папку в качестве тестового репозитория. Сделать это несложно, но, поскольку используется общая папка, указанные выше проверки выполняться не будут. Одно из возможных преимуществ этого способа в том, что общая папка не проверяет требуемый ключ API и вы можете использовать тот же ключ, что и для публикации в коллекции PowerShell.

В любом из этих решений с помощью Register-PSRepository определите новый репозиторий, который используется в параметре -Repository для Publish-Module.

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

Публикация с помощью PowerShellGet

Издателям настоятельно рекомендуется использовать командлеты Publish-Module и Publish-Script при работе с коллекцией PowerShell. PowerShellGet избавляет вас от необходимости запоминать всю процедуру установки из коллекции PowerShell и публикации в ней. В некоторых случаях издатели используют клиент NuGet вместо PowerShellGet или командлеты PackageManagement вместо Publish-Module. При этом возможно упущение ряда сведений, что приводит к росту обращений в службу поддержки.

Если по какой-либо причине вы не можете использовать Publish-Module или Publish-Script, сообщите нам об этом. Зарегистрируйте вопрос в репозитории GitHub PowerShellGet и укажите причины, побудившие вас выбрать NuGet или PackageManagement.