Часто задаваемые вопросы о коллекции PowerShell

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

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

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

• Не создавайте сценарии, создавайте модули PowerShell
• Основные сведения о модулях PowerShell

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

После регистрации можно опубликовать свой пакет в коллекции с помощью командлетов Publish-Module или Publish-Script. Дополнительные сведения о запуске этих командлетов см. на вкладке "Публикация" или в документации по командлетам Publish-Module и Publish-Script.

Для установки или сохранения пакетов не требуется регистрироваться в коллекции или входить в нее.

Полное сообщение об ошибке: "Не удалось обработать запрос". "Указанный ключ API является недопустимым или не имеет разрешения на доступ к указанному пакету". Удаленный сервер вернул ошибку: (403) запрещено."

Эта ошибка может возникать по следующим причинам.

• Указан недопустимый ключ API. Проверьте, указан ли правильный ключ API из вашей учетной записи. Чтобы получить ключ API, просмотрите страницу профиля.
• Пакет с указанным именем вам не принадлежит. Если вы убедились, что ключ API правильный, то, возможно, пакет с тем же именем, которое вы пытаетесь использовать, уже существует. Этот пакет мог быть не включен владельцем в список, и в этом случае он будет отсутствовать в любых результатах поиска. Чтобы определить, существует ли уже пакет с таким именем, откройте браузер и перейдите на страницу сведений об этом пакете: https://www.powershellgallery.com/packages/<packageName>. Например, перейдя непосредственно на страницу https://www.powershellgallery.com/packages/pester, вы попадете на страницу сведений о модуле Pester, даже если он не был включен в список. Если пакет с конфликтующим именем уже существует и не включен в список, можно сделать следующее:
  • Выбрать другое имя для пакета.
  • Обратиться к владельцу существующего пакета.

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

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

В коллекции можно опубликовать любой вид модуля PowerShell (модули сценариев, двоичные модули или модули манифестов). Для публикации модуля необходимо сообщить PowerShellGet некоторые сведения об этом модуле: версию, описание, автора и способ лицензирования. Эти сведения считываются в процессе публикации из файла манифеста модуля (PSD1-файла) или из значения параметра LicenseUri командлета Publish-Module. Все модули, которые публикуются в коллекции, должны иметь манифесты модуля. В коллекции может быть опубликован любой модуль, содержащий в своем манифесте следующие сведения.

• Версия
• Описание
• Автор
• URI для условий лицензии модуля, либо в разделе PrivateData манифеста, либо в параметре LicenseUri командлета Publish-Module.

Самый простой способ создать манифест модуля — выполнить командлет New-ModuleManifest. В PowerShell 5.0 или более поздней версии командлет New-ModuleManifest создает правильно сформированный манифест модуля с пустыми полями для нужных метаданных, такими как ProjectUri, LicenseUri и Tags. Просто заполните эти пустые поля или используйте этот созданный манифест в качестве примера правильного формата.

Чтобы убедиться, что все необходимые поля метаданных заполнены правильно, используйте командлет Test-ModuleManifest.

Для обновления полей файла манифеста модуля используйте командлет Update-ModuleManifest.

В коллекции можно опубликовать любой вид сценария PowerShell (сценарии или рабочие процессы). Для публикации сценария необходимо предоставить PowerShellGet некоторые сведения об этом сценарии: версию, описание, автора и способ лицензирования. Эти сведения считываются в рамках процесса публикации из раздела PSScriptInfo файла сценария или из значения параметра LicenseUri командлета Publish-Script. Все сценарии, которые публикуются в коллекции, должны сопровождаться метаданными. В коллекции может быть опубликован любой сценарий, содержащий в своем разделе PSScriptInfo следующие сведения.

• Версия
• Описание
• Автор
• URI для условий лицензии сценария, либо в разделе PSScriptInfo сценария, либо в параметре LicenseUri командлета Publish-Script.

Введите то, что вы ищете, в текстовом поле. Например, если вы хотите найти модули, которые относятся к SQL Azure, введите azure sql. Наша поисковая система будет искать эти ключевые слова во всех опубликованных пакетах, включая заголовки, описания и метаданные. Затем на основании взвешенного балла качества она будет отображать наилучшие соответствия. Также можно выполнять поиск по определенному полю с помощью синтаксиса field:"value" в запросе поиска для следующих полей.

• Теги
• Функции
• Командлеты
• DscResources
• PowerShellVersion

Так, например, при указании в запросе поиска PowerShellVersion:"2.0" будут отображены только результаты, совместимые с PowerShellVersion 2.0 (исходя из соответствующего манифеста модуля или сценария).

Самый простой способ создать правильно сформированный файл сценария — выполнить командлет New-ScriptFileInfo. В PowerShell 5.0 командлет New-ScriptFileInfo создает правильно сформированный файл сценария с пустыми полями для нужных метаданных, такими как ProjectUri, LicenseUri и Tags. Просто заполните эти пустые поля или используйте этот созданный файл сценария в качестве примера правильного формата.

Чтобы убедиться, что все необходимые поля метаданных заполнены правильно, используйте командлет Test-ScriptFileInfo.

Для обновления полей метаданных сценария используйте командлет Update-ScriptFileInfo.

Термин "модуль PowerShell" также относится к файлам, которые реализуют фактическую функциональность. Файлы модулей сценариев (PSM1-файлы) содержат код PowerShell. Файлы двоичных модулей (DLL-файлы) содержат скомпилированный код.

Вот как это можно себе представить: папка, которая содержит модуль, — это папка модуля. Папка модуля может содержать манифест модуля (PSD1-файл), описывающий содержимое папки. Файлы, фактически выполняющие работу, — это файлы модулей сценариев (PSM1-файлы) и файлы двоичных модулей (DLL-файлы). Ресурсы DSC расположены в специальной вложенной папке и реализованы в виде файлов модулей сценариев или файлов двоичных модулей.

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

PackageManagement — это общий интерфейс для работы с любым диспетчером пакетов. В конечном счете, работаете ли вы с модулями PowerShell, MSI-файлами, джемами Ruby, пакетами NuGet или же с модулями Perl, вам нужно будет использовать команды PackageManagement (Find-Package и Install-Package), чтобы найти и установить их. PackageManagement делает это при наличии поставщика пакетов для каждого диспетчера пакетов, который подключается к PackageManagement. Поставщики выполняют всю фактическую работу; они извлекают содержимое из репозиториев и устанавливают это содержимое локально. Часто поставщики пакетов просто являются оболочкой существующих инструментов диспетчера пакетов для конкретного типа пакета.

PowerShellGet — это диспетчер пакетов для пакетов PowerShell. Существует поставщик пакетов PSModule, который предоставляет функциональные возможности PowerShellGet через PackageManagement. По этой причине для установки модуля из коллекции PowerShell можно выполнить команду Install-Module или Install-Package -Provider PSModule. Некоторые функциональные возможности PowerShellGet, в том числе командлеты Update-Module и Publish-Module, недоступны через команды PackageManagement.

Таким образом, PowerShellGet обеспечивает лишь высококлассные возможности управления пакетами для содержимого PowerShell. PackageManagement предназначен для предоставления всех возможностей управления пакетами через один общий набор инструментов. Если этот ответ вас не удовлетворяет, более подробный ответ можно найти в конце этого документа в разделе Как фактически соотносятся PackageManagement и PowerShellGet?.

Дополнительные сведения см. на странице проекта PackageManagement.

Коллекция PowerShell является модифицированной версией коллекции NuGet. PowerShellGet использует поставщик NuGet для работы с репозиториями на основе NuGet, такими как коллекция PowerShell.

PowerShellGet можно использовать с любым допустимым репозиторием NuGet или с общим файловым ресурсом. Нужно просто добавить этот репозиторий, выполнив командлет Register-PSRepository.

Да.

За кулисами PowerShellGet интенсивно использует инфраструктуру PackageManagement.

На уровне командлетов PowerShell командлет Install-Module в действительности является тонкой оболочкой для команды Install-Package -Provider PSModule.

На уровне поставщиков пакетов PackageManagement поставщик пакетов PSModule в действительности обращается к другим поставщикам пакетов PackageManagement. Например, при работе с коллекциями на основе NuGet (такими как коллекция PowerShell) поставщик пакетов PSModule использует поставщик пакетов NuGet для работы с репозиторием.

Рис. 1. Архитектура PowerShellGet

В целом рекомендуется выбрать последнюю версию модуля PowerShellGet (обратите внимание, что для этого требуется .NET 4.5).

Для модуля PowerShellGet требуется PowerShell 3.0 или более поздней версии.

Таким образом, для PowerShellGet требуется одна из следующих операционных систем:

• Windows 10
• Windows 8.1 Профессиональная
• Windows 8.1 Корпоративная
• Windows 7 SP1
• Windows Server 2016
• Windows Server 2012 R2
• Windows Server 2008 R2 с пакетом обновления 1 (SP1)

Для PowerShellGet также требуется .NET Framework 4.5 или более поздней версии. См. дополнительные сведения об установке .NET Framework для разработчиков.

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

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

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