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

about_Modules

  • Статья

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

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

Подробное описание

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

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

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

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

Модуль — это пакет, содержащий элементы PowerShell, такие как командлеты, поставщики, функции, рабочие процессы, переменные и псевдонимы. Члены этого пакета могут быть реализованы в скрипте PowerShell, скомпилированной библиотеке DLL или в сочетании этих компонентов. Эти файлы обычно группируются в одном каталоге. Дополнительные сведения см. в разделе Основные сведения о модуле Windows PowerShell документации по пакету SDK.

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

Начиная с 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.

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

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

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

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

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

Если вы получаете модуль в виде папки с файлами в нем, необходимо установить его на компьютере, прежде чем использовать его в 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

Установить модуль можно в любое местоположение, однако если всегда устанавливать их в местоположение модулей по умолчанию, ими проще управлять. Дополнительные сведения о расположениях модулей по умолчанию см. в разделе Module и DSC Resource Locations, and 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 команды, такие как параметр Prefix, который добавляет отличительный префикс к именам всех импортированных команд, или параметр 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 с параметром Запуск от имени администратора .

Вы можете изменить расположения модулей по умолчанию в системе, изменив значение переменной среды PSModulePath , $Env: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 in панель управления, чтобы изменить значение переменной среды PSModulePath в реестре.

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

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

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

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

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

Скрытый

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

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

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

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

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

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

Вы также можете использовать параметры Import-ModuleAlias, Cmdlet, Function и Variable для выбора только команд, которые требуется импортировать, и исключить команды, вызывающие конфликты имен в сеансе.

Авторы модулей могут предотвращать конфликты имен с помощью свойства 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 для ведущих программ, реализующих InitialSessionState.CreateDefault2 API начального состояния сеанса, оснастка 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. Дополнительные сведения см. в статьях о ведении журналов и групповой политике.

См. также раздел