about_Automatic_Variables

Applies To: Windows PowerShell 2.0

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:\Users\<UserName>.

    $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
       Contains an enumerator that enumerates all input that is passed to a
       function. The $input variable is available only to functions and script
       blocks (which are unnamed functions).  In the Process block of a
       function, the $input variable enumerates the object that is currently
       in the pipeline. When the Process block  completes, there are no objects
       left in the pipeline, so the $input variable enumerates an empty
       collection. If the function does not have a Process block, then in the
       End block, the $input variable enumerates the collection of all 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 -notmatch 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
       $null is an automatic variable that contains a NULL or empty value. You
       can use this variable to represent an absent or undefined value in commands
       and scripts.

       Windows PowerShell treats $null as an object with a value, that is, as an
       explicit placeholder, so you can use $null to represent an empty value in a
       series of values.  

       For example, when $null is included in a collection, it is counted as one of
       the objects.

           C:\PS> $a = ".dir", $null, ".pdf"
           C:\PS> $a.count
           3

       If you pipe the $null variable to the ForEach-Object cmdlet, it generates a
       value for $null, just as it does for the other objects.

           PS C:\ps-test> ".dir", "$null, ".pdf" | Foreach {"Hello"}
           Hello
           Hello
           Hello

       As a result, you cannot use $null to mean "no parameter value." A parameter
       value of $null overrides the default parameter value.

       However, because Windows PowerShell treats the $null variable as a placeholder,
       you can use it scripts like the following one, which would not work if $null
       were ignored.

           $calendar = @($null, $null, “Meeting”, $null, $null, “Team Lunch”, $null)
           $days = Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"
           $currentDay = 0

           foreach($day in $calendar)
           {
               if($day –ne $null)
               {
                   "Appointment on $($days[$currentDay]): $day"
               }
    
               $currentDay++
           } 

           Appointment on Tuesday: Meeting
           Appointment on Friday: Team lunch


    $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 a script module (.psm1) is being executed.
       This variable allows script modules to use the module path to access other
       resources. This variable is valid only in a script module (.psm1).


    $PSSenderInfo
       Contains information about the user who started the PSSession, 
       including  the user identity and the time zone of the originating
       computer. This variable is available only in PSSessions.

       The $PSSenderInfo variable includes a user-configurable property, 
       ApplicationArguments, which, by default, contains only the 
       $PSVersionTable from the originating session. To add data to the 
       ApplicationArguments property, use the ApplicationArguments parameter
       of the New-PSSessionOption cmdlet.


    $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. 


    $ReportErrorShowExceptionClass
    $ReportErrorShowInnerException
    $ReportErrorShowSource
    $ReportErrorShowStackTrace
        The "ReportErrorShow" variables are defined in Windows PowerShell, but 
        they are not implemented. Get-Variable gets them, but they do not contain
        valid data.
        

    $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.

    $StackTrace
        Contains a stack trace for the most recent error.


    $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