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.

		-- 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 prevent name conflicts, use the Prefix parameter of Import-Command
	to create unique names for the imported commands.

	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.

	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 Windows 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, Windows 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 Windows PowerShell drives. 
	Snap-ins can add only cmdlets and providers.

	In fact, although you can add functions, aliases, variables, and drives
	to your session by typing them or running a script that adds them, all
	the cmdlets and providers in your session come from a module or a snap-in.

	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, pssnapin, module

	For more information about Windows PowerShell snap-ins, see about_PSSnapins.


 MODULE-RELATED WARNINGS AND ERRORS
	The commands that a module exports should follow the Windows 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.



SEE ALSO
	about_Command_Precedence
	about_PSSnapins
	Get-Command
	Get-Help
	Get-Module
	Import-Module
	Remove-Module