Импорт модуля PowerShell Importing a PowerShell Module

После установки модуля в системе может потребоваться импортировать модуль. Once you have installed a module on a system, you will likely want to import the module. Импорт — это процесс, который загружает модуль в активную память, чтобы пользователь мог получить доступ к этому модулю в сеансе PowerShell. Importing is the process that loads the module into active memory, so that a user can access that module in their PowerShell session. В PowerShell 2,0 можно импортировать недавно установленный модуль PowerShell с помощью вызова командлета Import-Module . In PowerShell 2.0, you can import a newly-installed PowerShell module with a call to Import-Module cmdlet. В PowerShell 3,0 PowerShell может неявно импортировать модуль, когда пользователь вызывает одну из функций или командлетов в модуле. In PowerShell 3.0, PowerShell is able to implicitly import a module when one of the functions or cmdlets in the module is called by a user. Обратите внимание, что в обеих версиях предполагается, что модуль устанавливается в расположение, где PowerShell может его найти. Дополнительные сведения см. в разделе Установка модуля PowerShell. Note that both versions assume that you install your module in a location where PowerShell is able to find it; for more information, see Installing a PowerShell Module. Манифест модуля можно использовать для ограничения экспортируемых частей модуля, и можно использовать параметры Import-Module вызова, чтобы ограничить импортируемые части. You can use a module manifest to restrict what parts of your module are exported, and you can use parameters of the Import-Module call to restrict what parts are imported.

Импорт Snap-In (PowerShell 1,0) Importing a Snap-In (PowerShell 1.0)

Модули не существовали в PowerShell 1,0. вместо этого необходимо было зарегистрировать и использовать оснастки. Однако мы не рекомендуем использовать эту технологию на этом этапе, так как модули обычно проще устанавливать и импортировать. Modules did not exist in PowerShell 1.0: instead, you had to register and use snap-ins. However, it is not recommended that you use this technology at this point, as modules are generally easier to install and import. Дополнительные сведения см. в разделе Создание оснастки Windows PowerShell. For more information, see How to Create a Windows PowerShell Snap-in.

Импорт модуля с Import-Module (PowerShell 2,0) Importing a Module with Import-Module (PowerShell 2.0)

Для импорта модулей в PowerShell 2,0 используется командлет Import-Module с соответствующим именем. PowerShell 2.0 uses the appropriately-named Import-Module cmdlet to import modules. При запуске этого командлета Windows PowerShell ищет указанный модуль в каталогах, указанных в PSModulePath переменной. When this cmdlet is run, Windows PowerShell searches for the specified module within the directories specified in the PSModulePath variable. При обнаружении указанного каталога Windows PowerShell ищет файлы в следующем порядке: файлы манифеста модуля (. PSD1), файлы модулей скриптов (. PSM1), двоичные файлы модулей (. dll). When the specified directory is found, Windows PowerShell searches for files in the following order: module manifest files (.psd1), script module files (.psm1), binary module files (.dll). Дополнительные сведения о добавлении каталогов в поиск см. в разделе изменение пути установки PSModulePath. For more information about adding directories to the search, see Modifying the PSModulePath Installation Path. В следующем примере кода показано, как импортировать модуль: The following code describes how to import a module:

Если предположить, что она была размещена в PSModulePath , PowerShell загрузит myModule в активную память. Assuming that myModule was located in the PSModulePath , PowerShell would load myModule into active memory. Если она не была расположена по PSModulePath пути, можно по-прежнему указать PowerShell, где его найти: If myModule was not located on a PSModulePath path, you could still explicitly tell PowerShell where to find it:

Можно также использовать параметр, -Verbose чтобы определить, что экспортируется из модуля и что импортируется в активную память. You can also use the -Verbose parameter to identify what is being exported out of the module, and what is being imported into active memory. Экспорт и импорт ограничивают содержимое, доступное пользователю. разница заключается в том, кто управляет видимостью. Both exports and imports restrict what is exposed to the user: the difference is who is controlling the visibility. По сути, экспорты управляются кодом внутри модуля. Essentially, exports are controlled by code within the module. В отличие от этого, управление импортом осуществляется с помощью Import-Module вызова. In contrast, imports are controlled by the Import-Module call. Дополнительные сведения см. в разделе запрещение импортируемых элементов ниже. For more information, see Restricting Members That Are Imported, below.

Неявный импорт модуля (PowerShell 3,0) Implicitly Importing a Module (PowerShell 3.0)

Начиная с Windows PowerShell 3.0, модули импортируются автоматически, когда любой командлет или любая функция из модуля используются в команде. Beginning in Windows PowerShell 3.0, modules are imported automatically when any cmdlet or function in the module is used in a command. Эта функция работает для любого модуля в каталоге, который входит в значение переменной среды PSModulePath . This feature works on any module in a directory that this included in the value of the PSModulePath environment variable. Если вы не сохраните модуль по действительному пути, вы по-прежнему можете загрузить их с помощью явного параметра Import-Module , описанного выше. If you do not save your module on a valid path however, you can still load them using the explicit Import-Module option, described above.

Следующие действия активируют автоматический импорт модуля, также известный как «Автоматическая загрузка модуля». The following actions trigger automatic importing of a module, also known as «module auto-loading.»

Использование командлета в команде. Using a cmdlet in a command. Например, при вводе Get-ExecutionPolicy импортируется модуль Microsoft. PowerShell. Security, содержащий Get-ExecutionPolicy командлет. For example, typing Get-ExecutionPolicy imports the Microsoft.PowerShell.Security module that contains the Get-ExecutionPolicy cmdlet.

Использование командлета Get-Command для получения команды. Using the Get-Command cmdlet to get the command. Например, при вводе Get-Command Get-JobTrigger импортируется модуль PSScheduledJob , содержащий Get-JobTrigger командлет. For example, typing Get-Command Get-JobTrigger imports the PSScheduledJob module that contains the Get-JobTrigger cmdlet. Get-Command Команда, содержащая подстановочные знаки, считается обнаружением и не инициирует импорт модуля. A Get-Command command that includes wildcard characters is considered to be discovery and does not trigger importing of a module.

Использование командлета Get-Help для получения справки по командлету. Using the Get-Help cmdlet to get help for a cmdlet. Например, при вводе Get-Help Get-WinEvent импортируется модуль Microsoft. PowerShell. Diagnostics, содержащий Get-WinEvent командлет. For example, typing Get-Help Get-WinEvent imports the Microsoft.PowerShell.Diagnostics module that contains the Get-WinEvent cmdlet.

Для поддержки автоматического импорта модулей Get-Command командлет получает все командлеты и функции во всех установленных модулях, даже если модуль не импортируется в сеанс. To support automatic importing of modules, the Get-Command cmdlet gets all cmdlets and functions in all installed modules, even if the module is not imported into the session. Дополнительные сведения см. в разделе справки по командлету Get-Command . For more information, see the help topic for the Get-Command cmdlet.

Процесс импорта The Importing Process

При импорте модуля для модуля создается новое состояние сеанса, а в памяти создается объект System. Management. Automation. PSModuleInfo . When a module is imported, a new session state is created for the module, and a System.Management.Automation.PSModuleInfo object is created in memory. Состояние сеанса создается для каждого импортируемого модуля (включая корневой модуль и все вложенные модули). A session-state is created for each module that is imported (this includes the root module and any nested modules). Элементы, экспортированные из корневого модуля, включая все элементы, экспортированные в корневой модуль любыми вложенными модулями, затем импортируются в состояние сеанса вызывающего. The members that are exported from the root module, including any members that were exported to the root module by any nested modules, are then imported into the caller’s session state.

Метаданные элементов, экспортированных из модуля, имеют свойство ModuleName. The metadata of members that are exported from a module have a ModuleName property. Это свойство заполняется именем модуля, в котором они были экспортированы. This property is populated with the name of the module that exported them.

Если имя экспортированного элемента использует неутвержденную команду или если имя члена использует ограниченные символы, то при выполнении командлета Import-Module отображается предупреждение. If the name of an exported member uses an unapproved verb or if the name of the member uses restricted characters, a warning is displayed when the Import-Module cmdlet is run.

По умолчанию командлет Import-Module не возвращает ни одного объекта в конвейер. By default, the Import-Module cmdlet does not return any objects to the pipeline. Однако командлет поддерживает параметр PassThru , который можно использовать для возврата объекта System. Management. Automation. PSModuleInfo для каждого импортируемого модуля. However, the cmdlet supports a PassThru parameter that can be used to return a System.Management.Automation.PSModuleInfo object for each module that is imported. Для отправки выходных данных на узел Пользователи должны запустить командлет Write-Host . To send output to the host, users should run the Write-Host cmdlet.

Ограничьте импортируемые элементы Restricting the Members That Are Imported

При импорте модуля с помощью командлета Import-Module по умолчанию все экспортированные элементы модуля импортируются в сеанс, включая все команды, экспортированные в модуль вложенным модулем. When a module is imported by using the Import-Module cmdlet, by default, all exported module members are imported into the session, including any commands exported to the module by a nested module. По умолчанию переменные и псевдонимы не экспортируются. By default, variables and aliases are not exported. Чтобы ограничить экспортируемые элементы, используйте манифест модуля. To restrict the members that are exported, use a module manifest. Чтобы ограничить импортируемые элементы, используйте следующие параметры Import-Module командлета. To restrict the members that are imported, use the following parameters of the Import-Module cmdlet.

Функция: этот параметр разрешает экспорт экспортируемых функций. Function: This parameter restricts the functions that are exported. (Если вы используете манифест модуля, см. раздел FunctionsToExport Key.) (If you are using a module manifest, see the FunctionsToExport key.)

`Командлет. Этот параметр позволяет ограничивать экспортируемые командлеты (если вы используете манифест модуля, см. раздел CmdletsToExport). `Cmdlet: This parameter restricts the cmdlets that are exported (If you are using a module manifest, see the CmdletsToExport key.)

Переменная. Этот параметр позволяет ограничивать экспортируемые переменные (если используется манифест модуля, см. раздел вариаблестоекспорт). Variable: This parameter restricts the variables that are exported (If you are using a module manifest, see the VariablesToExport key.)

Псевдоним. Этот параметр позволяет ограничивать экспортируемые псевдонимы (если вы используете манифест модуля, см. раздел алиасестоекспорт). Alias: This parameter restricts the aliases that are exported (If you are using a module manifest, see the AliasesToExport key.)

About Modules

Short Description

Explains how to install, import, and use PowerShell modules.

Long Description

A module is a package that contains PowerShell members, such as cmdlets, providers, functions, workflows, variables, and aliases.

People who write commands can use modules to organize their commands and share them with others. People who receive modules can add the commands in the modules to their PowerShell sessions and use them just like the built-in commands.

This topic explains how to use PowerShell modules. For information about how to write PowerShell modules, see Writing a PowerShell Module.

What Is a Module?

A module is a package that contains PowerShell members, such as cmdlets, providers, functions, workflows, variables, and aliases. The members of this package can be implemented in a PowerShell script, a compiled DLL, or a combination of both. These files are usually grouped together in a single directory. For more information, see Understanding a Windows PowerShell Module in the SDK documentation.

Module Auto-Loading

Beginning in PowerShell 3.0, PowerShell imports modules automatically the first time that you run any command in an installed module. You can now use the commands in a module without any set-up or profile configuration, so there’s no need to manage modules after you install them on your computer.

The commands in a module are also easier to find. The Get-Command cmdlet now gets all commands in all installed modules, even if they are not yet in the session. You can find a command and use it without importing needing to import the module first.

Each of the following examples cause the CimCmdlets module, which contains Get-CimInstance , to be imported into your session.

Run the Command

Get the Command

Get Help for the Command

Get-Command commands that include a wildcard character ( * ) are considered to be for discovery, not use, and do not import any modules.

Only modules that are stored in the location specified by the PSModulePath environment variable are automatically imported. Modules in other locations must be imported by running the Import-Module cmdlet.

Also, commands that use PowerShell providers do not automatically import a module. For example, if you use a command that requires the WSMan: drive, such as the Get-PSSessionConfiguration cmdlet, you might need to run the Import-Module cmdlet to import the Microsoft.WSMan.Management module that includes the WSMan: drive.

You can still run the Import-Module command to import a module and use the $PSModuleAutoloadingPreference variable to enable, disable and configure automatic importing of modules. For more information, see about_Preference_Variables.

How to Use a Module

To use a module, perform the following tasks:

1. Install the module. (This is often done for you.)
2. Find the commands that the module added.
3. Use the commands that the module added.

This topic explains how to perform these tasks. It also includes other useful information about managing modules.

How to Install a Module

If you receive a module as a folder with files in it, you need to install it on your computer before you can use it in PowerShell.

Most modules are installed for you. PowerShell comes with several preinstalled modules, sometimes called the core modules. On Windows-based computers, if features that are included with the operating system have cmdlets to manage them, those modules are preinstalled. When you install a Windows feature, by using, for example, the Add Roles and Features Wizard in Server Manager, or the Turn Windows features on or off dialog box in Control Panel, any PowerShell modules that are part of the feature are installed. Many other modules come in an installer or Setup program that installs the module.

Use the following command to create a Modules directory for the current user:

Copy the entire module folder into the Modules directory. You can use any method to copy the folder, including Windows Explorer and Cmd.exe, as well as PowerShell. In PowerShell use the Copy-Item cmdlet. For example, to copy the MyModule folder from C:\ps-test\MyModule to the Modules directory, type:

You can install a module in any location, but installing your modules in a default module location makes them easier to manage. For more information about the default module locations, see the Module and DSC Resource Locations, and PSModulePath section.

How to Find Installed Modules

To find modules that are installed in a default module location, but not yet imported into your session, type:

To find the modules that have already been imported into your session, at the PowerShell prompt, type:

For more information about the Get-Module cmdlet, see Get-Module.

How to Find the Commands in a Module

Use the Get-Command cmdlet to find all available commands. You can use the parameters of the Get-Command cmdlet to filter commands such as by module, name, and noun.

To find all commands in a module, type:

For example, to find the commands in the BitsTransfer module, type:

For more information about the Get-Command cmdlet, see Get-Command.

How to Get Help for the Commands in a Module

If the module contains Help files for the commands that it exports, the Get-Help cmdlet will display the Help topics. Use the same Get-Help command format that you would use to get help for any command in PowerShell.

Beginning in PowerShell 3.0, you can download Help files for a module and download updates to the Help files so they are never obsolete.

To get help for a commands in a module, type:

To get help online for command in a module, type:

To download and install the help files for the commands in a module, type:

For more information, see Get-Help and Update-Help.

How to Import a Module

You might have to import a module or import a module file. Importing is required when a module is not installed in the locations specified by the PSModulePath environment variable, $env:PSModulePath , or the module consists of file, such as a .dll or .psm1 file, instead of typical module that is delivered as a folder.

You might also choose to import a module so that you can use the parameters of the Import-Module command, such as the Prefix parameter, which adds a distinctive prefix to the noun names of all imported commands, or the NoClobber parameter, which prevents the module from adding commands that would hide or replace existing commands in the session.

To import modules, use the Import-Module cmdlet.

To import modules in a PSModulePath location into the current session, use the following command format.

For example, the following command imports the BitsTransfer module into the current session.

To import a module that is not in a default module location, use the fully qualified path to the module folder in the command.

For example, to add the TestCmdlets module in the C:\ps-test directory to your session, type:

To import a module file that is not contained in a module folder, use the fully qualified path to the module file in the command.

For example, to add the TestCmdlets.dll module in the C:\ps-test directory to your session, type:

For more information about adding modules to your session, see Import-Module.

How to Import a Module into Every Session

The Import-Module command imports modules into your current PowerShell session. To import a module into every PowerShell session that you start, add the Import-Module command to your PowerShell profile.

For more information about profiles, see about_Profiles.

How to Remove a Module

When you remove a module, the commands that the module added are deleted from the session.

To remove a module from your session, use the following command format.

For example, the following command removes the BitsTransfer module from the current session.

Removing a module reverses the operation of importing a module. Removing a module does not uninstall the module. For more information, see Remove-Module.

Module and DSC Resource Locations, and PSModulePath

The $env:PSModulePath environment variable contains a list of folder locations that are searched to find modules and resources.

By default, the effective locations assigned to $env:PSModulePath are:

System-wide locations: $PSHOME\Modules

These folders contain modules that ship with Windows and PowerShell.

DSC resources that are included with PowerShell are stored in the $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources folder.

User-specific modules: These are modules installed by the user in the user’s scope. Install-Module has a Scope parameter that allows you to specify whether the module is installed for the current user or for all users. For more information, see Install-Module.

The user-specific CurrentUser location on Windows is the PowerShell\Modules folder located in the Documents location in your user profile. The specific path of that location varies by version of Windows and whether or not you are using folder redirection. Microsoft OneDrive can also change the location of your Documents folder.

By default, on Windows 10, that location is $HOME\Documents\PowerShell\Modules . On Linux or Mac, the CurrentUser location is $HOME/.local/share/powershell/Modules .

You can verify the location of your Documents folder using the following command: [Environment]::GetFolderPath(‘MyDocuments’) .

The AllUsers location is $env:PROGRAMFILES\PowerShell\Modules on Windows. On Linux or Mac the modules are stored at /usr/local/share/powershell/Modules .

To add or change files in the $env:Windir\System32 directory, start PowerShell with the Run as administrator option.

You can change the default module locations on your system by changing the value of the PSModulePath environment variable, $Env:PSModulePath . The PSModulePath environment variable is modeled on the Path environment variable and has the same format.

To view the default module locations, type:

To add a default module location, use the following command format.

The semi-colon ( ; ) in the command separates the new path from the path that precedes it in the list.

For example, to add the C:\ps-test\Modules directory, type:

To add a default module location on Linux or MacOS, use the following command format:

For example, to add the /usr/local/Fabrikam/Modules directory to the value of the PSModulePath environment variable, type:

On Linux or MacOS, the colon ( : ) in the command separates the new path from the path that precedes it in the list.

When you add a path to PSModulePath, Get-Module and Import-Module commands include modules in that path.

The value that you set affects only the current session. To make the change persistent, add the command to your PowerShell profile or use System in Control Panel to change the value of the PSModulePath environment variable in the registry.

Also, to make the change persistent, you can also use the SetEnvironmentVariable method of the System.Environment class to add a Path to the PSModulePath environment variable.

For more information about the PSModulePath variable, see about_Environment_Variables.

Modules and Name Conflicts

Name conflicts occur when more than one command in the session has the same name. Importing a module causes a name conflict when commands in the module have the same names as commands or items in the session.

Name conflicts can result in commands being hidden or replaced.

Hidden

A command is hidden when it is not the command that runs when you type the command name, but you can run it by using another method, such as by qualifying the command name with the name of the module or snap-in in which it originated.

Replaced

A command is replaced when you cannot run it because it has been overwritten by a command with the same name. Even when you remove the module that caused the conflict, you cannot run a replaced command unless you restart the session.

Import-Module might add commands that hide and replace commands in the current session. Also, commands in your session can hide commands that the module added.

To detect name conflicts, use the All parameter of the Get-Command cmdlet. Beginning in PowerShell 3.0, Get-Command gets only that commands that run when you type the command name. The All parameter gets all commands with the specific name in the session.

To prevent name conflicts, use the NoClobber or Prefix parameters of the Import-Module cmdlet. The Prefix parameter adds a prefix to the names of imported commands so that they are unique in the session. The NoClobber parameter does not import any commands that would hide or replace existing commands in the session.

You can also use the Alias, Cmdlet, Function, and Variable parameters of Import-Module to select only the commands that you want to import, and you can exclude commands that cause name conflicts in your session.

Module authors can prevent name conflicts by using the DefaultCommandPrefix property of the module manifest to add a default prefix to all command names. The value of the Prefix parameter takes precedence over the value of DefaultCommandPrefix.

Even if a command is hidden, you can run it by qualifying the command name with the name of the module or snap-in in which it originated.

The PowerShell command precedence rules determine which command runs when the session includes commands with the same name.

For example, when a session includes a function and a cmdlet with the same name, PowerShell runs the function by default. When the session includes commands of the same type with the same name, such as two cmdlets with the same name, by default, it runs the most recently added command.

For more information, including an explanation of the precedence rules and instructions for running hidden commands, see about_Command_Precedence.

Modules and Snap-ins

You can add commands to your session from modules and snap-ins. Modules can add all types of commands, including cmdlets, providers, and functions, and items, such as variables, aliases, and PowerShell drives. Snap-ins can add only cmdlets and providers.

Before removing a module or snap-in from your session, use the following commands to determine which commands will be removed.

To find the source of a cmdlet in your session, use the following command format:

For example, to find the source of the Get-Date cmdlet, type:

Module-related Warnings and Errors

The commands that a module exports should follow the PowerShell command naming rules. If the module that you import exports cmdlets or functions that have unapproved verbs in their names, the Import-Module cmdlet displays the following warning message.

WARNING: Some imported command names include unapproved verbs which might make them less discoverable. Use the Verbose parameter for more detail or type Get-Verb to see the list of approved verbs.

This message is only a warning. The complete module is still imported, including the non-conforming commands. Although the message is displayed to module users, the naming problem should be fixed by the module author.

To suppress the warning message, use the DisableNameChecking parameter of the Import-Module cmdlet.

Built-in Modules and Snap-ins

In PowerShell 2.0 and in older-style host programs in PowerShell 3.0 and later, the core commands that are installed with PowerShell are packaged in snap-ins that are added automatically to every PowerShell session.

Beginning in PowerShell 3.0, for host programs that implement the InitialSessionState.CreateDefault2 initial session state API the Microsoft.PowerShell.Core snap-in is added to every session by default. Modules are loaded automatically on first-use.

Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins.

The following modules (or snap-ins) are installed with 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

Logging Module Events

Beginning in PowerShell 3.0, you can record execution events for the cmdlets and functions in PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to $True . You can also use a Group Policy setting, Turn on Module Logging, to enable module logging in all PowerShell sessions. For more information, see the logging and group policy articles.