Сведения о модулях

Статья
06/21/2023

Краткое описание

Описание установки, импорта и использования модулей PowerShell.

Полное описание

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

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

В этом разделе объясняется, как использовать модули PowerShell. Сведения о написании модулей PowerShell см. в статье "Написание модуля PowerShell".

Что такое модуль?

Модуль — это пакет команд. Все командлеты и поставщики в сеансе добавляются модулем или оснасткой.

Автоматическая загрузка модуля

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

Также упрощен поиск команд в модуле. Теперь Get-Command командлет получает все команды во всех установленных модулях, даже если они еще не находятся в сеансе, поэтому вы можете найти команду и использовать ее без импорта.

Каждый из следующих примеров приводит к импорту модуля CimCmdlets, содержащего его Get-CimInstance, в сеанс.

Выполнение команды
```
Get-CimInstance Win32_OperatingSystem
```
Получение команды
```
Get-Command Get-CimInstance
```
Получение справки по команде
```
Get-Help Get-CimInstance
```

Get-Command команды, содержащие подстановочный знак (*), считаются для обнаружения, не используются и не импортируют модули.

Импортируются только модули, хранящиеся в расположении, указанном переменной среды PSModulePath. Модули в других расположениях необходимо импортировать, запустив Import-Module командлет.

Кроме того, команды, использующие поставщики PowerShell, не импортируют модуль автоматически. Например, если вы используете команду, требующую диск WSMan: например Get-PSSessionConfiguration , командлет, может потребоваться выполнить Import-Module командлет для импорта модуля Microsoft.WSMan.Management , включающего WSMan: диск.

Вы по-прежнему Import-Module можете выполнить команду, чтобы импортировать модуль и использовать $PSModuleAutoloadingPreference переменную для включения, отключения и настройки автоматического импорта модулей. Дополнительные сведения см. в разделе about_Preference_Variables.

Использование модуля

Чтобы воспользоваться модулем, выполните следующие действия.

Установите модуль. (Обычно это выполняется автоматически.)
Найдите команды, которые добавил модуль.
Теперь вы можете использовать эти команды.

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

Установка модуля

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

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

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

New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules

Полностью скопируйте папку модуля в каталог Modules. Вы можете использовать любой метод для копирования папки, включая проводник Windows и Cmd.exe, а также PowerShell. В PowerShell используйте Copy-Item командлет. Например, чтобы скопировать папку MyModule из C:\ps-test\MyModule каталога Modules, введите:

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\Modules

Установить модуль можно в любое местоположение, однако если всегда устанавливать их в местоположение модулей по умолчанию, ими проще управлять. Дополнительные сведения о расположениях модулей по умолчанию см. в разделе "Расположения ресурсов Модуля и DSC" и PSModulePath .

Поиск установленных модулей

Чтобы найти модули, установленные в местоположении модулей по умолчанию, но еще не импортированные в сеанс, введите следующее:

Get-Module -ListAvailable

Чтобы найти модули, которые уже импортированы в сеанс, в командной строке PowerShell введите:

Get-Module

Дополнительные сведения о командлете см. в Get-Module разделе Get-Module.

Поиск команд в модуле

Get-Command Используйте командлет для поиска всех доступных команд. Параметры командлета Get-Command можно использовать для фильтрации команд, таких как модуль, имя и существительное.

Чтобы найти все команды в модуле, введите:

Get-Command -Module <module-name>

Например, чтобы найти команды в модуле BitsTransfer, введите:

Get-Command -Module BitsTransfer

Дополнительные сведения о командлете см. в Get-Command разделе Get-Command.

Получение справки по командам в модуле

Если модуль содержит файлы справки для экспортируемых команд, Get-Help командлет отобразит разделы справки. Используйте тот же Get-Help формат команд, который будет использоваться для получения справки по любой команде в PowerShell.

Начиная с PowerShell 3.0, можно скачать файлы справки для модуля и скачать обновления для файлов справки, чтобы они никогда не устарели.

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

Get-Help <command-name>

Чтобы получить справку по команде в модуле, введите:

Get-Help <command-name> -Online

Чтобы скачать и установить файлы справки для команд в модуле, введите:

Update-Help -Module <module-name>

Дополнительные сведения см. в разделе "Get-Help " и Update-Help.

Импорт модуля

Может потребоваться выполнить импорт модуля или файла модуля. Импорт требуется, если модуль не установлен в расположениях, указанных переменной среды PSModulePath , $env:PSModulePathили модуль состоит из файла, например файла .dll или PSM1, а не обычного модуля, доставляемого в виде папки.

Кроме того, можно импортировать модуль, чтобы можно было использовать параметры Import-Module команды, такие как параметр Префикса, который добавляет отличительный префикс в имена существительных всех импортированных команд или параметр NoClobber , который не позволяет модулю добавлять команды, которые будут скрывать или заменять существующие команды в сеансе.

Чтобы импортировать модули, используйте Import-Module командлет.

Чтобы импортировать модули в расположении PSModulePath в текущий сеанс, используйте следующий формат команды.

Import-Module <module-name>

Например, следующая команда импортирует модуль BitsTransfer в текущий сеанс.

Import-Module BitsTransfer

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

Например, чтобы добавить модуль TestCmdlets в каталог в C:\ps-test сеанс, введите:

Import-Module C:\ps-test\TestCmdlets

Чтобы импортировать файл модуля, который не расположен в папке модуля, укажите в команде полный путь к файлу модуля.

Например, чтобы добавить модуль TestCmdlets.dll в каталог в C:\ps-test сеанс, введите:

Import-Module C:\ps-test\TestCmdlets.dll

Дополнительные сведения о добавлении модулей в сеанс см. в разделе Import-Module.

Импорт модуля в каждый сеанс

Команда Import-Module импортирует модули в текущий сеанс PowerShell. Чтобы импортировать модуль в каждый запускаемый сеанс PowerShell, добавьте команду в Import-Module профиль PowerShell.

Дополнительные сведения о профилях см. в разделе about_Profiles.

Удаление модуля

Если удалить модуль, добавленные им команды удаляются из сеанса.

Чтобы удалить модуль из сеанса, используйте следующий формат команды.

Remove-Module <module-name>

Например, следующая команда удаляет модуль BitsTransfer из текущего сеанса.

Remove-Module BitsTransfer

Удаление модуля отменяет операцию импорта модуля. При этом установка модуля не отменяется. Дополнительные сведения см. в разделе Remove-Module.

Расположения ресурсов модуля и DSC и PSModulePath

Переменная $env:PSModulePath среды содержит список расположений папок, искомых для поиска модулей и ресурсов.

По умолчанию назначенные действующие расположения $env:PSModulePath :

Расположения на уровне системы: $PSHOME\Modules

Эти папки содержат модули, которые поставляются с Windows и PowerShell.

Ресурсы DSC, включенные в PowerShell, хранятся в папке $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources .
Модули для конкретных пользователей: это модули, установленные пользователем в области действия пользователя. Install-Module имеет параметр Scope , позволяющий указать, установлен ли модуль для текущего пользователя или для всех пользователей. Дополнительные сведения см. в разделе Install-Module.

Расположение CurrentUser для конкретного пользователя в Windows — это PowerShell\Modules папка, расположенная в расположении "Документы" в профиле пользователя. Конкретный путь к такому расположению зависит от версии Windows и того, используете ли вы перенаправление папок. Microsoft OneDrive также может изменить расположение папки "Документы ".

По умолчанию в Windows 10 это $HOME\Documents\PowerShell\Modulesрасположение. В Linux или Mac расположение CurrentUser — это $HOME/.local/share/powershell/Modules.

Примечание

Вы можете проверить расположение папки "Документы" с помощью следующей команды: [Environment]::GetFolderPath('MyDocuments')
Расположение AllUsers находится $env:PROGRAMFILES\PowerShell\Modules в Windows. В Linux или Mac модули хранятся в ./usr/local/share/powershell/Modules

Примечание

Чтобы добавить или изменить файлы в $env:Windir\System32 каталоге, запустите PowerShell с помощью параметра "Запуск от имени администратора ".

Расположение модулей по умолчанию в системе можно изменить, изменив значение переменной $Env:PSModulePathсреды PSModulePath. Переменная среды PSModulePath моделиируется в переменной среды Path и имеет тот же формат.

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

$Env:PSModulePath

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

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

Точка с запятой (;) в команде отделяет новый путь от пути, предшествующего ему в списке.

Например, чтобы добавить C:\ps-test\Modules каталог, введите:

$Env:PSModulePath + ";C:\ps-test\Modules"

Чтобы добавить расположение модуля по умолчанию в Linux или MacOS, используйте следующий формат команды:

$Env:PSModulePath += ":<path>"

Например, чтобы добавить /usr/local/Fabrikam/Modules каталог в значение переменной среды PSModulePath , введите:

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

В Linux или MacOS двоеточие (:) в команде отделяет новый путь от пути, предшествующего ему в списке.

При добавлении пути в PSModulePathGet-Module и Import-Module команды включают модули в этот путь.

Задаваемое значение влияет только на текущий сеанс. Чтобы сохранить изменения, добавьте команду в профиль PowerShell или используйте system в панель управления, чтобы изменить значение переменной среды PSModulePath в реестре.

Кроме того, чтобы сохранить изменения, можно также использовать метод SetEnvironmentVariable класса System.Environment , чтобы добавить путь к переменной среды PSModulePath .

Дополнительные сведения о переменной PSModulePath см. в about_Environment_Variables.

Модули и конфликты имен

Конфликт имен происходит, когда в сеансе имеется несколько команд с одинаковым именем. При импорте модуля возникает конфликт имен, если содержащиеся в нем команды имеют такие же имена, как команды или элементы, уже имеющиеся в сеансе.

Конфликты имен могут возникать в результате скрытия или замены команд.

Скрытый

Скрытой называется команда, не выполняемая при вводе ее имени, но выполняемая другими способами (например, с указанием имени модуля или оснастки, из которой добавлена команда).

Замененный текст

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

Import-Module может добавлять команды, которые скрывают и заменяют команды в текущем сеансе. Кроме того, команды в текущем сеансе могут скрыть команды, добавленные модулем.

Чтобы обнаружить конфликты имен, используйте параметр All командлета Get-Command . Начиная с PowerShell 3.0, получает только те команды, Get-Command которые выполняются при вводе имени команды. Параметр All получает все команды с определенным именем в сеансе.

Чтобы предотвратить конфликты имен, используйте параметры NoClobber или Prefix командлета Import-Module . Параметр Prefix добавляет префикс к именам импортированных команд, чтобы они были уникальными в сеансе. Параметр NoClobber не импортирует команды, которые будут скрывать или заменять существующие команды в сеансе.

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

Авторы модулей могут предотвратить конфликты имен с помощью свойства DefaultCommandPrefix манифеста модуля, чтобы добавить префикс по умолчанию ко всем именам команд. Значение параметра Prefix имеет приоритет над значением DefaultCommandPrefix.

Даже если команда скрыта, можно выполнить ее, указав (помимо ее имени) имя модуля или оснастки, из которой она добавлена.

Правила приоритета команд PowerShell определяют, какая команда выполняется, если сеанс включает команды с тем же именем.

Например, если сеанс включает функцию и командлет с тем же именем, PowerShell запускает функцию по умолчанию. Если сеанс содержит команды одинакового типа (например, два командлета) с одинаковым именем, по умолчанию выполняется команда, добавленная последней.

Дополнительные сведения, включая описание правил очередности и инструкций по выполнению скрытых команд, см. в about_Command_Precedence.

Модули и оснастки

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

Прежде чем удалить модуль или оснастку из сеанса, с помощью следующих команд определите, какие команды будут при этом удалены

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

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

Например, чтобы найти источник командлета Get-Date , введите:

Get-Command Get-Date | Format-List -Property verb,noun,module

Команды, экспортируемые модулем, должны соответствовать правилам именования команд PowerShell. Если модуль, импортируемый при импорте, экспортирует командлеты или функции с неутвержденными командами в именах, Import-Module командлет отображает следующее предупреждающее сообщение.

ПРЕДУПРЕЖДЕНИЕ. Некоторые импортированные имена команд включают неутвержденные команды, которые могут сделать их менее обнаруживаемыми. Чтобы получить подробные сведения, используйте параметр Verbose, или введите Get-Verb, чтобы просмотреть список утвержденных команд.

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

Чтобы отключить предупреждающее сообщение, используйте параметр DisableNameChecking командлета Import-Module .

Встроенные модули и оснастки

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

Начиная с PowerShell 3.0, для ведущих программ, реализующих API начального InitialSessionState.CreateDefault2 состояния сеанса, оснастка Microsoft.PowerShell.Core добавляется в каждый сеанс по умолчанию. Модули загружаются автоматически при первом использовании.

Примечание

Удаленные сеансы, включая сеансы, запускаемые с помощью командлета New-PSSession , — это сеансы старого стиля, в которых встроенные команды упаковываются в оснастки.

Следующие модули (или оснастки) устанавливаются с помощью PowerShell.

CimCmdlets
Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PackageManagement
PowerShellGet
PSDesiredStateConfiguration
PSDiagnostics
PSReadline

События модуля ведения журнала

Начиная с PowerShell 3.0, можно записывать события выполнения для командлетов и функций в модулях PowerShell и оснастки, задав для свойства LogPipelineExecutionDetails модулей и оснастки $Trueзначение . Для включения ведения журнала модулей во всех сеансах PowerShell можно также использовать параметр групповая политика , включить ведение журнала модулей. Дополнительные сведения см. в статьях о ведении журнала и групповой политике.