TOPIC
    about_Prompts

SHORT DESCRIPTION
    Describes the Prompt function and demonstrates how to create a custom 
    Prompt function.

  
LONG DESCRIPTION
    The Windows PowerShell command prompt indicates that Windows PowerShell 
    is ready to run a command: 

	PS C:\>


    The Windows PowerShell prompt is determined by the Prompt function. You 
    can customize the prompt by creating your own Prompt function. Then, you
    can save this function in your Windows PowerShell profile.

   
  The Prompt Function

      The Prompt function determines the appearance of the Windows PowerShell 
      prompt. Windows PowerShell comes with a built-in Prompt function, but
      you can override it by defining your own Prompt function.


      The Prompt function has the following syntax:

	  function prompt { <function-body> }


      The Prompt function must return an object, typically a string. We 
      recommend that it return a string or an object that is formatted as a 
      string. The string should fit on an 80-character line.


      For example:

	  PS C:\> function prompt {"Hello, World > "}
          Hello, World > 

  
      Like all functions, the Prompt function is stored in the Function: drive. 
      To display the code in the current Prompt function, type:

	  (get-item function:prompt).definition


      This command uses the Get-Item cmdlet to display the Prompt item in the 
      Function: drive. Then, it uses dot notation to display the value of the
      Definition property of the Prompt function. 

    
  The Default Prompt 

      The default Windows PowerShell prompt is:

	  PS>


      This prompt appears only when the prompt function generates an error or 
      when the prompt function does not return a string or object.

          PS C:\> function prompt {$null}
          PS>


      Because Windows PowerShell comes with a built-in prompt, you usually do 
      not see the default prompt until you write your own prompt function.


  The Built-in Prompt
    
 
      Windows PowerShell includes a built-in prompt function that creates the 
      familiar prompts. The built-in prompt function is:

          function prompt
          {
              $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } 

              else { '' }) + 'PS ' + $(Get-Location) `

              + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> '
          } 


      The function uses the Test-Path cmdlet to determine whether the 
      $PSDebugContext automatic variable is populated. If $PSDebugContext is 
      populated, you are in debugging mode, and "[DBG]" is added to the prompt,
      as follows:

	  [DBG] PS C:\ps-test>
	
     
      If $PSDebugContext is not populated, the function adds "PS" to the 
      prompt. And, the function uses the Get-Location cmdlet to get the current
      file system directory location. Then, it adds a right angle bracket (>). 
      For example:        
           
	  PS C:\ps-test>	


      If you are in a nested prompt, the function adds two angle brackets (>>) 
      to the prompt. (You are in a nested prompt if the value of the 
      $NestedPromptLevel automatic variable is greater than 1.)


      For example, when you are debugging in a nested prompt, the prompt 
      resembles the following prompt:

	  [DBG] PS C:\ps-test>>>


      The Enter-PSSession cmdlet prepends the name of the remote computer to
      the current Prompt function.  When you use the Enter-PSSession cmdlet to
      start a session with a remote computer, the command prompt changes to
      include the name of the remote computer. For example:

          PS Hello, World> Enter-PSSession Server01

          [Server01]: PS Hello, World>


      Other Windows PowerShell host applications and alternate shells might 
      have their own custom command prompts.


      For more information about the $PSDebugContext and $NestedPromptLevel 
      automatic variables, see about_Automatic_Variables.
 	

  Customizing the Prompt

      To customize the prompt, write a new Prompt function. The function is not 
      protected, so you can overwrite it. 
 

      To write a prompt function, type the following:

	  function prompt { }


      Then, between the curly braces, enter the commands or the string that 
      creates your prompt.


      For example, the following prompt includes your computer name:

	  function prompt {"PS [$env:COMPUTERNAME]> "}


      On the Server01 computer, the prompt resembles the following prompt:

	  PS [Server01] >


      The following prompt function includes the current date and time:

	  function prompt {"$(get-date)> "}


      The prompt resembles the following prompt:

	  01/01/2008 17:49:47>


      You can also modify the default Prompt function:


          function prompt
          {
              $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } 

              else { '' }) + "$(get-date)" `

              + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> '
          } 

  
      For example, the following modified Prompt function adds "[ADMIN]:" to
      the built-in Windows PowerShell prompt when Windows PowerShell is opened
      by using the "Run as administrator" option:
    
          function prompt 
          {
              $identity = [Security.Principal.WindowsIdentity]::GetCurrent()
              $principal = [Security.Principal.WindowsPrincipal] $identity

              $(if (test-path variable:/PSDebugContext) { '[DBG]: ' } 

              elseif($principal.IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator"))
    	          { "[ADMIN]: " }

              else { '' }) + 'PS ' + $(Get-Location) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '> '
          }



      When you start Windows PowerShell by using the "Run as administrator"
      option, a prompt that resembles the following prompt appears:
                
	  [ADMIN]: PS C:\ps-test>


      The following Prompt function displays the history ID of the next
      command. To view the command history, use the Get-History
      cmdlet.   

          function prompt
          {
             # The at sign creates an array in case only one history item exists.
             $history = @(get-history)
             if($history.Count -gt 0)
             {
                $lastItem = $history[$history.Count - 1]
                $lastId = $lastItem.Id
             }

             $nextCommand = $lastId + 1
             $currentDirectory = get-location
             "PS: $nextCommand $currentDirectory >"
          }



      The following prompt uses the Write-Host and Get-Random cmdlets to create
      a prompt that changes color randomly. Because Write-Host writes to the 
      current host application but does not return an object, this function 
      includes a Return statement. Without it, Windows PowerShell uses the 
      default prompt, "PS>".

          function prompt
          {
              $color = get-random -min 1 -max 16
              write-host ("PS " + $(get-location) +">") -nonewline -foregroundcolor $color
              return " "
          }


  Saving the Prompt
	
      Like any function, the Prompt function applies only in the current 
      session. To save the Prompt function for future sessions, add it to your
      Windows PowerShell profiles. For more information about profiles, 
      see about_Profiles.


SEE ALSO
    Get-Location
    Enter-PSSession
    Get-History
    Get-Random
    Write-Host
    about_Profiles
    about_Functions
    about_Scopes
    about_Debuggers
    about_Automatic_Variables
