TOPIC about_Modules SHORT DESCRIPTION Explains how to install, import, and use Windows PowerShell modules. LONG DESCRIPTION A module is a package that contains Windows PowerShell commands, such as cmdlets, providers, functions, 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 Windows PowerShell sessions and use them just like the built-in commands. This topic explains how to use Windows PowerShell modules. For information about how to write Windows PowerShell modules, see "Writing a Windows PowerShell Module" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=144916. HOW TO USE A MODULE To use a module, perform the following tasks: 1. Install the module. (This is often done for you.) 2. Import the module into your Windows PowerShell session. 3. Find the commands that the module added. 4. 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 import it into Windows PowerShell. Most modules are installed for you. Windows PowerShell comes with several pre-installed modules. In Windows Server 2008 R2, the Add Features Wizard in Server Manager automatically installs the feature modules that you select. Many other modules come in an installer or Setup program that installs the module. To install a module folder: 1. Create a Modules directory for the current user if one does not exist. To create a Modules directory, type: new-item -type directory -path $home\Documents\WindowsPowerShell\Modules 2. 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 Windows PowerShell. In Windows 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 -dest $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 Locations and PSModulePath" section. HOW TO FIND INSTALLED MODULEs When a module is installed, you can import it into your Windows PowerShell session. To find modules that are installed in a default module location, at the Windows PowerShell prompt, type: get-module -listAvailable To find the modules that have already been imported into your session, at the Windows PowerShell prompt, type: get-module For more information about the Get-Module cmdlet, see Get-Module. HOW TO IMPORT A MODULE To use the commands in a module, import the module into a Windows PowerShell session. To import modules from a default module 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 For more information about adding modules to your session, see Import-Module. HOW TO IMPORT ALL MODULES INTO YOUR WINDOWS POWERSHELL SESSION In Windows 7 and Windows Server 2008 R2, the "Import all modules" task opens a Windows PowerShell session that includes all the available Windows PowerShell modules and snap-ins. To start a Windows PowerShell session with all the available Windows PowerShell modules and snap-ins, use the following procedure. -- Right-click the Windows PowerShell icon in the taskbar, and then click "Import all modules". Note: In Windows Server 2008 R2, the Windows PowerShell icon is pinned to the taskbar by default. However, you must start Windows PowerShell one time to make the "Import all modules" task appear. In other versions of Windows, to import all the available modules into your session, at the Windows PowerShell prompt, type: get-module -listAvailable | import-module HOW TO FIND THE COMMANDS IN A MODULE After you import a module into your Windows PowerShell session, you can use the commands in the module. To find the commands that a module added, at the Windows PowerShell prompt, type: get-command -module <module-name> For example, to find the commands that the BitsTransfer module adds, type: get-command -module BitsTransfer For more information about the Get-Command cmdlet, see Get-Command. HOW TO FIND HELP FOR THE COMMANDS IN A MODULE If the module contains Help topics for the commands that it exports, the Get-Help cmdlet will display the Help topics. Use the same command format that you would use for any Help topic in Windows PowerShell. To find the Help topic for the commands in a module, at the Windows PowerShell prompt, type: get-help <command-name> For more detailed Help, type: get-help <command-name> -detailed For example, to find detailed Help for the Start-BitsTransfer cmdlet, type: get-help Start-BitsTransfer -detailed For more information about the Get-Help module, see Get-Help. 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 about the Remove-Module cmdlet, see Remove-Module. HOW TO IMPORT A MODULE INTO EVERY SESSION The Import-Module command imports modules into your current Windows PowerShell session. This command affects only the current session. To import a module into every Windows PowerShell session that you start, add the Import-Module command to your Windows PowerShell profile. For more information about profiles, see about_Profiles. MODULE LOCATIONS AND PSMODULEPATH There are two default locations for Windows PowerShell modules, one for the system and one for the current user. System: $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) Current user: $home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules) - or - $home\My Documents\WindowsPowerShell\Modules (%UserProfile%\My Documents\WindowsPowerShell\Modules) Note: In Windows Vista, Windows Server 2008, and later versions of Windows, to add or change files in the %Windir%\System32 directory, start Windows 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 Windows PowerShell profile or use the System item in Control Panel to change the value of the PSModulePath environment variable in the registry. 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. ...
magdula294