about_Modules

Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0

РАЗДЕЛ

about_Modules

КРАТКОЕ ОПИСАНИЕ

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

ПОДРОБНОЕ ОПИСАНИЕ

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

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

В этом разделе описывается, как использовать модули Windows PowerShell. Сведения о процедуре создания модулей Windows PowerShell см. в разделе «Создание модуля Windows PowerShell» в библиотеке MSDN (Microsoft Developer Network) по адресу https://go.microsoft.com/fwlink/?LinkId=144916.

ЧТО ТАКОЕ МОДУЛЬ?

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

НОВЫЕ ВОЗМОЖНОСТИ МОДУЛЕЙ: АВТОМАТИЧЕСКАЯ ЗАГРУЗКА МОДУЛЯ

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

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

Импортировать модуль в сеанс можно с помощью любой из следующих команд.

        #Run the command
        Get-Mailbox –Identity Chris  

        #Get the command
        Get-Command Get-Mailbox

        #Get help for the command
        Get-Help Get-Mailbox

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

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

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

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

ИСПОЛЬЗОВАНИЕ МОДУЛЯ

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

1. Установите модуль. (Обычно это выполняется автоматически.)

2. Найдите команды, которые добавил модуль.

3. Теперь вы можете использовать эти команды.

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

УСТАНОВКА МОДУЛЯ

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

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

Для установки модуля, предоставленного в виде папки, выполните следующие действия.

1. Создайте каталог Modules для текущего пользователя, если он не существует.

Для этого введите следующую команду:

               New-Item -Type Directory -Path $home\Documents\WindowsPowerShell\Modules

2. Полностью скопируйте папку модуля в каталог Modules.

Скопировать папку можно любыми средствами, включая проводник, программу Cmd.exe и Windows PowerShell.

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

               Copy-Item -Path c:\ps-test\MyModule -Destination $home\Documents\WindowsPowerShell\Modules

Установить модуль можно в любое местоположение, однако если всегда устанавливать их в местоположение модулей по умолчанию, ими проще управлять. Подробнее о местоположении модулей по умолчанию см. в разделе «МЕСТОПОЛОЖЕНИЕ МОДУЛЕЙ И РЕСУРСОВ DSC И ПЕРЕМЕННАЯ PSMODULEPATH».

ПОИСК УСТАНОВЛЕННЫХ МОДУЛЕЙ

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

         Get-Module -ListAvailable

Чтобы найти модули, уже импортированные в сеанс, в командной строке Windows 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 такого же формата, как и для поиска раздела справки по любой команде в Windows PowerShell.

В Windows 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 импортирует модули в текущий сеанс Windows PowerShell. Она затрагивает только текущий сеанс.

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

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

УДАЛЕНИЕ МОДУЛЯ

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

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

        Remove-Module <module-name>

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

        Remove-Module BitsTransfer

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

МЕСТОПОЛОЖЕНИЕ МОДУЛЕЙ И РЕСУРСОВ DSC И ПЕРЕМЕННАЯ PSMODULEPATH

Ниже указаны расположения по умолчанию для модулей Windows PowerShell. Начиная с версии Windows PowerShell 4.0, с появлением DSC, была добавлена новая папка по умолчанию для модулей и ресурсов DSC. Подробнее о DSC см. в разделе about_DesiredStateConfiguration.

Для системы:

$pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules). Системные модули — это модули, которые поставляются вместе с Windows и Windows PowerShell.

Начиная с версии Windows PowerShell 4.0, с появлением службы настройки требуемого состояния Windows PowerShell (DSC), ресурсы DSC, включенные в Windows PowerShell, также хранятся в папке $pshome\Modules во вложенной папке $pshome\Modules\PSDesiredStateConfiguration\DSCResources.

Для текущего пользователя:

$home\Documents\WindowsPowerShell\Modules (%профиль_пользователя%\Documents\WindowsPowerShell\Modules)

– или –

$home\My Documents\WindowsPowerShell\Modules (%профиль_пользователя%\My Documents\WindowsPowerShell\Modules). Это расположение для добавленных пользователем модулей до версии Windows PowerShell 4.0.

В Windows PowerShell 4.0 и более поздних версиях Windows PowerShell добавляемые пользователем модули и ресурсы DSC хранятся в папке C:\Program Files\WindowsPowerShell\Modules. Модули и ресурсы DSC в этой папке доступны всем пользователям компьютера. Это изменение было необходимо по той причине, что подсистема DSC работает как локальная система и не имеет доступа к папкам конкретного пользователя, таким как $home\Documents\WindowsPowerShell\Modules.

Примечание.

Чтобы добавить или изменить файлы в каталоге %Windir%\System32, запустите Windows PowerShell с параметром «Запуск от имени администратора».

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

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

        $env:psmodulepath

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

        $env:psmodulepath = $env:psmodulepath + ";<path>"

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

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

        $env:psmodulepath + ";c:\ps-test\Modules"

После добавления пути в переменную PSModulePath команды Get-Module и Import-Module действуют в том числе на модули в каталоге, на который указывает этот путь.

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

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

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

МОДУЛИ И КОНФЛИКТЫ ИМЕН

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

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

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

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

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

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

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

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

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

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

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

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

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

МОДУЛИ И ОСНАСТКИ

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

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

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

        get-command <cmdlet-name> | format-list -property verb, noun, pssnapin, module

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

        get-command get-date | format-list -property verb, noun, pssnapin, module

Подробнее об оснастках Windows PowerShell см. в разделе about_PSSnapins.

ПРЕДУПРЕЖДЕНИЯ И ОШИБКИ, СВЯЗАННЫЕ С МОДУЛЯМИ

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

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

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

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

ВСТРОЕННЫЕ МОДУЛИ И ОСНАСТКИ

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

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

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

ПРИМЕЧАНИЕ. Удаленные сеансы, включая сеансы, которые запускаются с помощью командлета New-PSSession, представляют собой сеансы старого стиля, где встроенные команды упакованы в оснастки.

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

        Microsoft.PowerShell.Core
        Microsoft.PowerShell.Diagnostics
        Microsoft.PowerShell.Host
        Microsoft.PowerShell.Management
        Microsoft.PowerShell.ScheduledJob
        Microsoft.PowerShell.Security
        Microsoft.PowerShell.Utility
        Microsoft.WSMan.Management
        PSDesiredStateConfiguration
        PSWorkflow
        PSWorkflowUtility
        ISE

РЕГИСТРАЦИЯ СОБЫТИЙ МОДУЛЯ

Начиная с Windows PowerShell 3.0 можно записывать события выполнения командлетов и функций в модулях и оснастках Windows PowerShell, присвоив свойству LogPipelineExecutionDetails модулей и оснасток значение $True. Для включения функции ведения журнала во всех сеансах Windows PowerShell можно также использовать параметр групповой политики «Включить ведение журнала модулей». Дополнительные сведения см. в разделах about_EventLogs (https://go.microsoft.com/fwlink/?LinkID=113224) и about_Group_Policy_Settings (https://go.microsoft.com/fwlink/?LinkID=251696).

СМ. ТАКЖЕ

about_Command_Precedence

about_DesiredStateConfiguration

about_EventLogs

about_Group_Policy_Settings

about_PSSnapins

Get-Command

Get-Help

Get-Module

Import-Module

Remove-Module