TOPIC
	about_PSSessions

SHORT DESCRIPTION
	Describes Windows PowerShell sessions (PSSessions) and explains how to 
	establish a persistent connection to a remote computer. 


LONG DESCRIPTION
	To run Windows PowerShell commands on a remote computer, you can use the 
	ComputerName parameter of a cmdlet, or you can create a Windows PowerShell 
	session (PSSession) and run commands in the PSSession. 

	When you create a PSSession, Windows PowerShell establishes a persistent 
	connection to the remote computer. Use a PSSession to run a series of 
	related commands on a remote computer. Commands that run in the same 
	PSSession can share data, such as the values of variables, aliases, and 
	functions.

	You can also create a PSSession on the local computer and run commands
	in it. A local PSSession uses the Windows PowerShell remoting 
	infrastructure to create and maintain the PSSession.

	This topic explains how to create, use, get, and delete PSSessions. 
	For more advanced information, see about_PSSession_Details.

	Note: PSSessions use the Windows PowerShell remoting infrastructure.
		To use PSSessions, the local and remote computers must be configured 
		for remoting. For more information, see about_Remote_Requirements. 
	
		In Windows Vista and later versions of Windows, to create a 
		PSSession on a local computer, you must start Windows PowerShell
		with the "Run as administrator" option. 


 WHAT IS A SESSION?

	A session is an environment in which Windows PowerShell runs. 

	Each time you start Windows PowerShell, a session is created for you, and 
	you can run commands in the session. You can also add items to your session, 
	such as modules and snap-ins, and you can create items, such as variables, 
	functions, and aliases. These items exist only in the session and are 
	deleted when the session ends.

	You can also create additional sessions, known as "Windows PowerShell 
	sessions" or "PSSessions," on the local computer or on a remote computer. 
	Like the default session, you can run commands in a PSSession and add and 
	create items.

	However, unlike the session that starts automatically, you can control the 
	PSSessions that you create. You can get, create, configure, and remove them, 
	and you can run multiple commands in the same PSSession. The PSSession 
	remains open and available until you delete it from your session.

	Typically, you create a PSSession to run a series of related commands on a 
	remote computer. When you create a PSSession on a remote computer, 
	Windows PowerShell establishes a persistent connection to the remote
	computer to support the session. 

	If you use the computerName parameter of the Invoke-Command or 
	Enter-PSSession cmdlet to run a remote command or to start an interactive
	session, Windows PowerShell creates a temporary session on the remote 
	computer and closes the session as soon as the command is complete or as 
	soon as the interactive session ends. You cannot control these temporary 
	sessions, and you cannot use them for more than a single command or a 
	single interactive session.

	In Windows PowerShell, the "current session" is the session that you are 
	working in. The "current session" can refer to any session, including a 
	temporary session or a PSSession.


 WHY USE A PSSESSION?

	Use a PSSession when you need a persistent connection to a remote computer. 
	With a PSSession, you can run a series of commands that share data, such as 
	the value of variables, the contents of a function, or the definition of an 
	alias.

	You can run remote commands without creating a PSSession. Use the 
	ComputerName parameter of remote-enabled cmdlets to run a single command
	or a series of unrelated commands on one or many computers.

	When you use the ComputerName parameter of Invoke-Command or Enter-PSSession,
	Windows PowerShell establishes a temporary connection to the remote computer
	and then closes the connection as soon as the command is complete. Any data
	elements that you create are lost when the connection is closed. 

	Other cmdlets that have a ComputerName parameter, such as Get-Eventlog and
	Get-WmiObject, use different remoting technologies to gather data. None 
	create a persistent connection like a PSSession.
	 

 HOW TO CREATE A PSSESSION

	To create a PSSession, use the New-PSSession cmdlet. To create the 
	PSSession on a remote computer, use the ComputerName parameter of the
	New-PSSession cmdlet.

	For example, the following command creates a new PSSession on the
	Server01 computer.

		new-pssession -computername Server01

	When you submit the command, New-PSSession creates the PSSession and 
	returns an object that represents the PSSession. You can save the object in 
	a variable when you create the PSSession, or you can use a Get-PSSession 
	command to get the PSSession at a later time.

	For example, the following command creates a new PSSession on the Server01
	computer and saves the resulting object in the $ps variable.

		$ps = new-pssession -computername Server01


 HOW TO CREATE PSSESSIONS ON MULTIPLE COMPUTERS

	To create PSSessions on multiple computers, use the ComputerName parameter
	of the New-PSSession cmdlet. Type the names of the remote computers in a
	comma-separated list. 

	For example, to create PSSessions on the Server01, Server02, and Server03
	computers, type:

		new-PSSession -computername Server01, Server02, Server03

	New-PSSession creates one PSSession on each of the remote computers. 


 HOW TO GET PSSESSIONS
 
	To get the PSSessions that were created in your current session, use the 
	Get-PSSession cmdlet. Get-PSSession returns the same type of object that 
	New-PSSession returns. 

	The following command gets all the PSSessions that were created in the 
	current session.

		get-PSSession

	The default display of the PSSessions shows their ID and a default display
	name. You can assign an alternate display name when you create the 
	session.

		Id   Name	 ComputerName	State	ConfigurationName
		---  ----	 ------------	-----	---------------------
		1	Session1   Server01		Opened   Microsoft.PowerShell
		2	Session2   Server02		Opened   Microsoft.PowerShell
		3	Session3   Server03		Opened   Microsoft.PowerShell

   
	You can also save the PSSessions in a variable. The following command gets 
	the PSSessions and saves them in the $ps123 variable.

		$ps123 = get-PSSession   

	When using the PSSession cmdlets, you can refer to a PSSession by its ID, by  
	its name, or by its instance ID (a GUID). The following command gets a 
	PSSession by its ID and saves it in the $ps01 variable.

		$ps01 = get-PSSession -id 1

	Get-PSSession gets only the PSSessions that were created in the current
	session. It does not get PSSessions that were created in other sessions or 
	on other computers, even if the sessions are connected to and are running 
	commands on the local computer. 



 HOW TO RUN COMMANDS IN A PSSESSION

	To run a command in one or more PSSessions, use the Invoke-Command cmdlet. 
	Use the Session parameter to specify the PSSessions and the ScriptBlock 
	parameter to specify the command.

	For example, to run a Get-ChildItem ("dir") command in each of the three 
	PSSessions saved in the $ps123 variable, type:

		invoke-command -session $ps123 -scriptblock {get-childitem}

 
 HOW TO DELETE PSSESSIONS

	When you are finished with the PSSession, use the Remove-PSSession cmdlet 
	to delete the PSSession and to release the resources that it was using.

		remove-PSSession -session $ps

		- or - 
	
		remove-PSSession -id 1
 
	If you do not delete the PSSession, the PSSession remains open and 
	available for use until you close the current session or until you exit 
	Windows PowerShell.

	You can also use the TimeOut parameter of New-PSSession to set an 
	expiration time for an idle PSSession. For more information, 
	see new-PSSession.


 THE PSSESSION CMDLETS

	Cmdlet				Description
	-----------------	 ------------------------------------------------------
	New-PSSession		 Creates a new PSSession on a local or remote computer.

	Get-PSSession		 Gets the PSSessions in the current session.

	Remove-PSSession	Deletes the PSSessions in the current session.

	Enter-PSSession	 Starts an interactive session.

	Exit-PSSession		Ends an interactive session.



	For a list of PSSession cmdlets, type:
	
		get-help *-PSSession


 FOR MORE INFORMATION

	For more information about PSSessions, see about_PSSession_Details.


SEE ALSO
	about_Remote
	about_Remote_Requirements
	New-PSSession
	Get-PSSession
	Remove-PSSession
	Enter-PSSession
	Exit-PSSession
	Invoke-Command