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 P
rompt function. Then, you
can save this function in your Windows PowerShe
ll 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 Prom
pt function.

The Prompt function has the following syntax:

function prompt { <function-body> }

The Prompt function must return an object, ty

pically a string. We
recommend that it return a string or an objec
t that is formatted as a
string. The string should fit on an 80-charac
ter line.

For example:

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

Hello, World >

Like all functions, the Prompt function is st

ored in the Function: drive.
To display the code in the current Prompt fun
ction, type:

(get-item function:prompt).definition

This command uses the Get-Item cmdlet to disp

lay the Prompt item in the
Function: drive. Then, it uses dot notation t
o 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 func

tion generates an error or
when the prompt function does not return a st
ring 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 yo
ur own prompt function.

The Built-in Prompt

Windows PowerShell includes a built-in prompt

function that creates the
familiar prompts. The built-in prompt functio
n is:

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

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

) `

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

>>' }) + '> '
}

The function uses the Test-Path cmdlet to det

ermine whether the
$PSDebugContext automatic variable is populat
ed. If $PSDebugContext is
populated, you are in debugging mode, and "[D
BG]" is added to the prompt,
as follows:

[DBG] PS C:\ps-test>

If $PSDebugContext is not populated, the func

tion adds "PS" to the
prompt. And, the function uses the Get-Locati
on 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 a

dds two angle brackets (>>)
to the prompt. (You are in a nested prompt if
the value of the
$NestedPromptLevel automatic variable is grea
ter than 1.)

For example, when you are debugging in a nest

ed 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 th
e Enter-PSSession cmdlet to
start a session with a remote computer, the c
ommand 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 an

d alternate shells might
have their own custom command prompts.
 For more information about the $PSDebugContex
t and $NestedPromptLevel
automatic variables, see about_Automatic_Vari
ables.

Customizing the Prompt

To customize the prompt, write a new Prompt f

unction. The function is not
protected, so you can overwrite it.

To write a prompt function, type the followin

g:

function prompt { }

Then, between the curly braces, enter the com

mands or the string that
creates your prompt.

For example, the following prompt includes yo

ur computer name:

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

On the Server01 computer, the prompt resemble

s the following prompt:

PS [Server01] >

The following prompt function includes the cu

rrent 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 functi

on:

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

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

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

>>' }) + '> '
}

For example, the following modified Prompt fu

nction adds "[ADMIN]:" to
the built-in Windows PowerShell prompt when W
indows PowerShell is opened
by using the "Run as administrator" option:

function prompt
{
$identity = [Security.Principal.Windo
wsIdentity]::GetCurrent()
$principal = [Security.Principal.Wind
owsPrincipal] $identity

$(if (test-path variable:/PSDebugCont

ext) { '[DBG]: ' }

elseif($principal.IsInRole([Security
.Principal.WindowsBuiltInRole] "Administrator"))
{ "[ADMIN]: " }
 else { '' }) + 'PS ' + $(Get-Locatio
n) + $(if ($nestedpromptlevel -ge 1) { '>>' }) + '
> '
}

When you start Windows PowerShell by using th

e "Run as administrator"
option, a prompt that resembles the following
prompt appears:

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

The following Prompt function displays the hi

story 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, Wind
ows 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 applie

s only in the current
session. To save the Prompt function for futu
re sessions, add it to your
Windows PowerShell profiles. For more informa
tion 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