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

Статья
06/26/2024

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Важно указать модули, от которые ваш модуль зависит в манифесте модуля. Это позволяет пользователю не беспокоиться об установке соответствующих версий модулей, от которых зависит ваша служба. Чтобы указать зависимые модули, необходимо использовать необходимое поле модуля в манифесте модуля. При этом все перечисленные модули загружаются в глобальную среду до импорта модуля, если они еще не загружены. Например, некоторые модули уже могут загружаться другим модулем. Кроме того, можно указать определенную версию для загрузки с помощью поля 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 включает в себя хорошую документацию по написанию тестов Пестера, начиная с начала работы с рекомендациями.

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

Включение и/или ссылка на условия лицензии

Все пакеты, опубликованные в коллекции PowerShell, должны указывать условия лицензии или быть привязаны лицензией, включенной в условия использования в выставке A. Лучший подход к указанию другой лицензии — предоставить ссылку на лицензию с помощью 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 сегментами. Многие ранние модули не соответствовали рекомендациям, а выпуски продуктов от Майкрософт включают сведения о сборке в виде 4-го блока чисел (например, 5.1.14393.1066). С точки зрения управления версиями эти различия игнорируются.

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

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

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

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

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

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

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

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

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