Рекомендации и рекомендации по публикации PowerShellGallery

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

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

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

Отзыв об этих рекомендациях приветствуется. Если у вас есть отзывы, откройте проблемы в нашем репозитории документации GitHub.

Использование PSScriptAnalyzer

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

Лучше всего запускать Invoke-ScriptAnalyzer с -Recurse и -Severity Warning.

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

Все ошибки исправлены или устранены в документации.
Все предупреждения проверяются и рассматриваются, где это применимо.

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

Включение документации и примеров

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

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

Рекомендации по предоставлению справки см. в разделе Как написать справку по командлету.
Создание справки по командлету, которая является лучшим подходом для любого скрипта, функции или командлета PowerShell. Сведения о том, как создать справку по командлету, см. в статье Как написать справку по командлету. Сведения о добавлении справки в сценарий см. в разделе О справке на основе комментариев.
Многие модули также включают документацию в текстовом формате, например файлы MarkDown. Это может быть особенно полезно, если в GitHub есть сайт проекта, где Markdown является широко используемым форматом. Лучше всего использовать Markdown со вкусом GitHub.

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

Хороший шаблон для примеров можно найти в модуле 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, и отвечать на возникающие проблемы. Одним из недостатков этого метода является то, что только пользователь и владелец когда-либо увидят связь, поэтому владельцу может потребоваться ответить на один и тот же вопрос много раз.

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

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

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

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

Модули PowerShell имеют структуру папок, которая позволяет включать в пакет несколько папок и файлов. Структура модуля включает в себя другие пакеты, которые мы перечисляем в качестве рекомендаций: справку по командлетам, документацию, примеры и тесты. Самым большим недостатком является то, что скрипт внутри модуля должен быть предоставлен и использоваться в качестве функции. Сведения о создании модуля см. в разделе Написание модуля 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 будет включать ссылку на сайт проекта слева от страницы пакета.

Пометьте свой пакет совместимыми psEdition и платформами

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

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, , и Update-Module командлеты проверят подпись, Install-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 сегментами. Многие ранние модули не соответствовали рекомендациям, и выпуски продуктов от Microsoft включают информацию о сборке в виде 4-го блока цифр (например 5.1.14393.1066, ). С точки зрения управления версиями эти различия игнорируются.

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

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

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

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

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

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

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2024-06-26