about_Automatic_Variables

TOPIC
	about_Automatic_Variables

SHORT DESCRIPTION
	Describes variables that store state information for Windows PowerShell.
	These variables are created and maintained by Windows PowerShell.

LONG DESCRIPTION
	Here is a list of the automatic variables in Windows PowerShell:
   

	$$
	 Contains the last token in the last line received by the session.


	$?  
	 Contains the execution status of the last operation. It contains
	TRUE if the last operation succeeded and FALSE if it failed.

	$^
	 Contains the first token in the last line received by the session.

	$_
	 Contains the current object in the pipeline object. You can use this
	 variable in commands that perform an action on every object or on
	 selected objects in a pipeline.

	$Args
	 Contains an array of the undeclared parameters and/or parameter
	 values that are passed to a function, script, or script block.
	 When you create a function, you can declare the parameters by using the
	 param keyword or by adding a comma-separated list of parameters in
	 parentheses after the function name.

	$ConsoleFileName
	 Contains the path of the console file (.psc1) that was most
	 recently used in the session. This variable is populated when
	 you start Windows PowerShell with the PSConsoleFile parameter or
	 when you use the Export-Console cmdlet to export snap-in names to a
	 console file. 

	 When you use the Export-Console cmdlet without parameters, it
	 automatically updates the console file that was most recently
	 used in the session. You can use this automatic variable to determine
	 which file will be updated.

	$Error
	 Contains an array of error objects that represent the most
	 recent errors. The most recent error is the first error object in the 
	 array ($Error[0]).


	$Event
		Contains a PSEventArgs object that represents the event that is being
		processed.  This variable is populated only within the Action block of
		an event registration command, such as Register-ObjectEvent. The value
		of this variable is the same object that the Get-Event cmdlet returns. 
		Therefore, you can use the properties of the $Event variable, such as
		$Event.TimeGenerated , in an Action script block.

	$EventSubscriber
		Contains a PSEventSubscriber object that represents the event subscriber
		of the event that is being processed. This variable is populated only
		within the Action block of an event registration command. The value of
		this variable is the same object that the Get-EventSubscriber cmdlet
		returns. 

	$ExecutionContext
	 Contains an EngineIntrinsics object that represents the 
	 execution context of the Windows PowerShell host. You can
	 use this variable to find the execution objects that are
	 available to cmdlets.

	$False
	 Contains FALSE. You can use this variable to represent
	 FALSE in commands and scripts instead of using the string "false". 
	 The string can be interpreted as TRUE if it is converted to a non-empty
	 string or to a non-zero integer.

	$ForEach
	 Contains the enumerator of a ForEach-Object loop. You can use the 
	 properties and methods of enumerators on the value of the $ForEach 
	 variable. This variable exists only while the For loop is running. It
	 is deleted when the loop is completed.

	$Home
	 Contains the full path of the user's home directory. This variable is
	 the equivalent of the %homedrive%%homepath% environment variables,
	 typically C:\Documents and Settings\<user>.

	$Host
	 Contains an object that represents the current host application 
	 for Windows PowerShell. You can use this variable to represent the
	 current host in commands or to display or change the properties of		 
	 the host, such as $Host.version or $Host.CurrentCulture, or
	 $host.ui.rawui.setbackgroundcolor("Red").

	$Input
	 An enumerator that contains the input that is passed to a function. The
	 $Input variable is case-sensitive and is available only in functions and
	 in script blocks. (Script blocks are essentially unnamed functions.) 
	 In the Process block of a function, the $Input variable contains the 
	 object that is currently in the pipeline. When the Process block is 
	 completed, the value of $Input is NULL. If the function does not have a
	 Process block, the value of $Input is available to the End block, and it
	 contains all the input to the function.

	$LastExitCode
	 Contains the exit code of the last Windows-based program that was run.

	$Matches
	 The $Matches variable works with the -match and -not match operators.
	 When you submit scalar input to the -match or -notmatch operator, and
	 either one detects a match, they return a Boolean value and populate
	 the $Matches automatic variable with a hash table of any string values
	 that were matched. For more information about the -match operator, see 
	 about_comparison_operators.

	$MyInvocation
	 Contains an object with information about the current command, such as
	 a script, function, or script block. You can use the information in the
	 object, such as the path and file name of the script 
	 ($myinvocation.mycommand.path) or the name of a function
	 ($myinvocation.mycommand.name) to identify the current command. This is
	 particularly useful for finding the name of the script that is running.

	$NestedPromptLevel
	 Contains the current prompt level. A value of 0 indicates the original
	 prompt level. The value is incremented when you enter a nested level and
	 decremented when you exit it.

	 For example, Windows PowerShell presents a nested command prompt when
	 you use the $Host.EnterNestedPrompt method. Windows PowerShell also 
	 presents a nested command prompt when you reach a breakpoint in the
	 Windows PowerShell debugger.

	 When you enter a nested prompt, Windows PowerShell pauses the current
	 command, saves the execution context, and increments the value of
	 the $NestedPromptLevel variable. To create additional nested command 
	 prompts (up to 128 levels) or to return to the original command prompt,
	 complete the command, or type "exit". 

	 The $NestedPromptLevel variable helps you track the prompt level. You
	 can create an alternative Windows PowerShell command prompt that 
	 includes this value so that it is always visible.

	$NULL
	 Contains a NULL or empty value. You can use this variable to
	 represent NULL in commands and scripts instead of using the string 
	 "NULL". The string can be interpreted as TRUE if it is converted to a 
	 non-empty string or a non-zero integer.

	$PID
	 Contains the process identifier (PID) of the process that is hosting
	 the current Windows PowerShell session.
  
	$Profile
	 Contains the full path of the Windows PowerShell profile for the
	 current user and the current host application. You can use this variable
	 to represent the profile in commands. For example, you can use it in
	 a command to determine whether a profile has been created:

		 test-path $profile

	 Or, you can use it in a command to create a profile:

		 new-item -type file -path $pshome -force

	 You can also use it in a command to open the profile in Notepad:

		 notepad $profile

	$PSBoundParameters
	 Contains a dictionary of the active parameters and their current 
	 values. This variable has a value only in a scope where parameters
	 are declared, such as a script or function. You can use it to 
	 display or change the current values of parameters or to pass
	 parameter values to another script or function.

	 For example:

		 function test {
			param($a, $b)
		
			# Display the parameters in dictionary format.
			$psboundparameters
			 
			# Call the Test1 function with $a and $b.
			test1 @psboundparameters	 
		 }

	$PsCmdlet
	 Contains an object that represents the cmdlet or advanced function
	 that is being run. 

	 You can use the properties and methods of the object in your cmdlet
	 or function code to respond to the conditions of use. For example,
	 the ParameterSetName property contains the name of the parameter set
	 that is being used, and the ShouldProcess method adds the WhatIf and
	 Confirm parameters to the cmdlet dynamically.

	 For more information about the $PSCmdlet automatic variable, see
	 about_Functions_Advanced.

	$PsCulture
	 Contains the name of the culture currently in use in the operating
	 system. The culture determines the display format of items such
	 as numbers, currrency, and dates. This is the value of the 
	 System.Globalization.CultureInfo.CurrentCulture.Name property of the
	 system. To get the System.Globalization.CultureInfo object for the
	 system, use the Get-Culture cmdlet.

	$PSDebugContext
	 While debugging, this variable contains information about the
	 debugging environment. Otherwise, it contains a NULL value. 
	 As a result, you can use it to indicate whether the debugger has 
	 control. When populated, it contains a PsDebugContext object that has
	 Breakpoints and InvocationInfo properties. The InvocationInfo property 
	 has several useful properties, including the Location property. The 
	 Location property indicates the path of the script that is being 
	 debugged.


	$PsHome
	 Contains the full path of the installation directory for Windows
	 PowerShell, typically, %windir%\System32\WindowsPowerShell\v1.0. You
	 can use this variable in the paths of Windows PowerShell files. For 
	 example, the following command searches the conceptual Help topics for 
	 the word "variable": 

			select-string -pattern variable -path $pshome\*.txt

	$PSScriptRoot
	 Contains the directory from which the script module is being executed.
	 This variable allows scripts to use the module path to access other
	 resources.


	$PsUICulture
	 Contains the name of the user interface (UI) culture that is currently
	 in use in the operating system. The UI culture determines which text 
	 strings are used for user interface elements, such as menus and 
	 messages. This is the value of the 
	 System.Globalization.CultureInfo.CurrentUICulture.Name property of the
	 system. To get the System.Globalization.CultureInfo object for the
	 system, use the Get-UICulture cmdlet. 


	$PsVersionTable
		Contains a read-only hash table that displays details about the
		version of Windows PowerShell that is running in the current session.
		The table includes the following items:

			CLRVersion:			The version of the common language runtime (CLR)

			BuildVersion:		The build number of the current version

			PSVersion:			 The Windows PowerShell version number

			WSManStackVersion:	 The version number of the WS-Management stack

			PSCompatibleVersions:  Versions of Windows PowerShell that are
								 compatible with the current version

			SerializationVersion   The version of the serialization method

			PSRemotingProtocolVersion
								 The version of the Windows PowerShell remote
								 management protocol

	$Pwd
	 Contains a path object that represents the full path of the current
	 directory. 

	$Sender
		Contains the object that generated this event. This variable is
		populated only within the Action block of an event registration command.
		The value of this variable can also be found in the Sender property of
		the PSEventArgs (System.Management.Automation.PSEventArgs) object that
		Get-Event returns.

	$ShellID
	 Contains the identifier of the current shell.


	$SourceArgs
		Contains objects that represent the event arguments of the event that
		is being processed. This variable is populated only within the Action
		block of an event registration command.  The value of this variable
		can also be found in the SourceArgs property of the PSEventArgs
		(System.Management.Automation.PSEventArgs) object that Get-Event
		returns.

	$SourceEventArgs
		Contains an object that represents the first event argument that derives
		from EventArgs of the event that is being processed. This variable is
		populated only within the Action block of an event registration command.
		The value of this variable can also be found in the SourceArgs property
		of the PSEventArgs (System.Management.Automation.PSEventArgs) object
		that Get-Event returns.

	$This
		In a script block that defines a script property or script method, the
		$This variable refers to the object that is being extended. 

	$True
	 Contains TRUE. You can use this variable to represent
	 TRUE in commands and scripts.


SEE ALSO
	about_Hash_Tables
	about_Preference_Variables
	about_Variables