| Server IP : 134.29.175.74 / Your IP : 216.73.216.160 Web Server : nginx/1.10.2 System : Windows NT CST-WEBSERVER 10.0 build 19045 (Windows 10) i586 User : Administrator ( 0) PHP Version : 7.1.0 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Windows/SysWOW64/WindowsPowerShell/v1.0/en-US/ |
Upload File : |
ABOUT MODULES
Short Description
Explains how to install, import, and use PowerShell modules.
Long Description
A module is a package that contains PowerShell commands, 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 of commands. All cmdlets and providers in your
session are added by a module or a snap-in.
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, so you can find a command and use it without importing.
Each of the following examples cause the module containing Get-Mailbox to
be imported into your session.
- 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 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:
New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\Modules
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:
Copy-Item -Path C:\ps-test\MyModule -Destination `
$HOME\Documents\WindowsPowerShell\Modules
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:
Get-Module -ListAvailable
To find the modules that have already been imported into your session, at
the PowerShell prompt, type:
Get-Module
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:
Get-Command -Module <module-name>
For example, to find the commands in the BitsTransfer module, type:
Get-Command -Module BitsTransfer
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:
Get-Help <command-name>
To get help online for command in a module, type:
Get-Help <command-name> -Online
To download and install the help files for the commands in a module, type:
Update-Help -Module <module-name>
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.
Import-Module <module-name>
For example, the following command imports the BitsTransfer module into the
current session.
Import-Module BitsTransfer
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:
Import-Module C:\ps-test\TestCmdlets
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:
Import-Module C:\ps-test\TestCmdlets.dll
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.
Remove-Module <module-name>
For example, the following command removes the BitsTransfer module from the
current session.
Remove-Module BitsTransfer
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.
[!NOTE] You can verify the location of your DOCUMENTS folder using
the following command: [Environment]::GetFolderPath('MyDocuments').
- The ALLUSERS location is $env:PROGRAMFILES\WindowsPowerShell\Modules on
Windows.
[!NOTE] 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:
$Env:PSModulePath
To add a default module location, use the following command format.
$Env:PSModulePath = $Env:PSModulePath + ";<path>"
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:
$Env:PSModulePath + ";C:\ps-test\Modules"
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:
Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module
For example, to find the source of the Get-Date cmdlet, type:
Get-Command Get-Date | Format-List -Property verb,noun,module
For more information about PowerShell snap-ins, see about_PSSnapins.
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.
[!NOTE] 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.ODataUtils
- Microsoft.PowerShell.Security
- Microsoft.PowerShell.Utility
- Microsoft.WSMan.Management
- PackageManagement
- PowerShellGet
- PSDesiredStateConfiguration
- PSDiagnostics
- PSScheduledJob
- PSWorkflow
- PSWorkflowUtility
- ISE
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
about_EventLogs and about_Group_Policy_Settings.
See Also
about_Command_Precedence
about_DesiredStateConfiguration
about_EventLogs
about_Group_Policy_Settings
about_PSSnapins
Get-Command
Get-Help
Get-Module
Import-Module
Remove-Module