Preference Variables
SHORT DESCRIPTION
Variables that customize the behavior of Window
s PowerShell
LONG DESCRIPTION
Windows PowerShell includes a set of variables
that enable you to
customize its behavior. These "preference varia
bles" work like the
options in GUI-based systems.
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command
[S] Suspend [?] Help (default is "Y"):
$ErrorActionPreference
----------------------
Determines how Windows PowerShell responds to a
non-terminating
error (an error that does not stop the cmdl
et processing) at the
command line or in a script, cmdlet, or pro
vider, such as the
errors generated by the Write-Error cmdlet.
Valid values:
Stop: Displays the error mess
age and stops
executing.
EXAMPLES
PS> $erroractionpreference
# Generate a non-te
rminating error.
# Generate an error
message.
PS>
# Error message is
suppressed.
PS> write-error "Hello, World" -erroraction
:continue
# Use the ErrorActi
on parameter with a
value of "Continu
e".
write-error "Hello, World" -erroraction:con
tinue : Hello, World
# The error message
is displayed and
execution continu
es.
This example shows the effect of a real error.
In this case, the command
gets a non-existent file, nofile.txt. The examp
le also uses the
ErrorAction common parameter to override the pr
eference.
PS> $erroractionpreference
Confirm
Cannot find path 'C:\nofile.txt' because it
does not exist.
[Y] Yes [A] Yes to All [H] Halt Command
[S] Suspend [?] Help (default is "Y"):
$ErrorView
----------
Determines the display format of error mess
ages in Windows
PowerShell.
Valid values:
NormalView: A detailed view designe
d for most users.
(default) Consists of a descr
iption of the error, the
name of the object
involved in the error,
and arrows (<<<<) t
hat point to the words
in the command that
caused the error.
EXAMPLES
PS> $ErrorView # Ve
rify the value.
NormalView
Exception : System.Management.Automation
.ItemNotFoundException: Cannot find path
'C:\nofile.txt' because it d
oes not exist.
at System.Management.Automa
tion.SessionStateInternal.GetChildItems(String pat
h,
Boolean recurse, CmdletProvi
derContext context)
at System.Management.Automa
tion.ChildItemCmdletProviderIntrinsics.Get(String
path,
Boolean recurse, CmdletProvi
derContext context)
at Microsoft.PowerShell.Comm
ands.GetChildItemCommand.ProcessRecord()
TargetObject : C:\nofile.txt
CategoryInfo : ObjectNotFound: (C:
\nofile.txt:String) [Get-ChildItem],
ItemNotFoundExcepti
on
FullyQualifiedErrorId : PathNotFound,Micro
soft.PowerShell.Commands.GetChildItemCommand
ErrorDetails :
InvocationInfo : System.Management.A
utomation.InvocationInfo
$FormatEnumerationLimit
-----------------------
Determines how many enumerated items are in
cluded in a display. This
variable does not affect the underlying obj
ects; just the display.
When the value of $FormatEnumerationLimit i
s less than the number of
enumerated items, Windows PowerShell adds a
n ellipsis (...) to
indicate items not shown.
EXAMPLES
# The li
st is truncated after
4 item
s.
$Log*Event
----------
The Log*Event preference variables determin
e which types of events
are written to the Windows PowerShell event
log in Event Viewer. By
default, only engine and provider events ar
e logged, but you can use
the Log*Event preference variables to custo
mize your log, such as
logging events about commands.
$LogCommandLifecycleEvent:
Logs the starting and stopping of c
ommands and command pipelines
and security exceptions in command
discovery. Default = $false (not logged).
$LogCommandLifeCycleEvent
- or -
$LogCommandLifeCycleEvent = $true
$LogCommandLifeCycleEvent = $false
$MaximumAliasCount
------------------
Determines how many aliases are permitted i
n a Windows PowerShell
session. The default value, 4096, should be
sufficient for most
uses, but you can adjust it to meet your ne
eds.
(get-alias).count
$MaximumDriveCount
------------------
Determines how many Windows PowerShell driv
es are permitted in a
given session. This includes file system dr
ives and data stores that
are exposed by Windows PowerShell providers
and appear as drives,
such as the Alias: and HKLM: drives.
Valid values: 1024 - 32768 (Int32)
Default: 4096
(get-psdrive).count
$MaximumErrorCount
------------------
Determines how many errors are saved in the
error history
for the session.
$Error.count
$Error[0]
PS> $Error.count
17
PS> $Error.clear()
PS>
PS> $Error.count
0
$MaximumFunctionCount
------------------
Determines how many functions are permitted
in a given session.
get-childitem function:
(get-childitem function:).count
$MaximumHistoryCount
------------------
Determines how many commands are saved in t
he command history
for the current session.
(get-history).count
$MaximumVariableCount
------------------
Determines how many variables are permitted
in a given session,
including automatic variables, preference v
ariables, and the
variables that you create in commands and s
cripts.
(get-variable).count
$OFS
----
Output Field Separator. Specifies the chara
cter that separates the
elements of an array when the array is conv
erted to a string.
EXAMPLES
$OutputEncoding
---------------
Determines the character encoding method use
d by Windows PowerShell
when it sends text to other applications. Fo
r example, if an
application returns Unicode strings to Windo
ws PowerShell, you might
need to change the value to to send the char
acters correctly.
EXAMPLES
test.txt: <Unicode-characters>
$ProgressPreference
-------------------
Determines how Windows PowerShell responds to p
rogress updates
generated by a script, cmdlet or provider,
such as the progress bars
generated by the Write-Progress cmdlet. The
Write-Progress cmdlet
creates progress bars that depict the statu
s of a command.
Valid values:
Stop: Does not display the pr
ogress bar. Instead,
it displays an erro
r message and stops executing.
$PSEmailServer
--------------
Specifies the default e-mail server that is
used to send e-mail
messages. This preference variable is used b
y cmdlets that send
e-mail, such as the Send-MailMessage cmdlet.
$PSSessionApplicationName
---------------------------
Specifies the default application name for a
remote command
that uses WS-Management technology.
http://Server01:8080/WSMAN
$PSSessionConfigurationName
---------------------------
Specifies the default session configuration
that is used for
PSSessions created in the current session.
http://schemas.microsoft.com/powershell/mi
crosoft.powershell
http://schemas.microsoft.com/powershell/
$PSSessionOption
----------------
Establishes the default values for advanced
user options in a
remote session. These option preferences ov
erride the system
default values for session options.
For example,
$PSSessionOption = New-PSSessionOption
-NoCompression
$VerbosePreference
------------------
Determines how Windows PowerShell responds
to verbose messages
generated by a script, cmdlet or provider,
such as the messages
generated by the Write-Verbose cmdlet. Typi
cally, verbose messages
describe the actions performed to execute a
command.
Valid values:
Stop: Displays the verbose me
ssage and an error
message and then st
ops executing.
EXAMPLES
PS> # Write
a verbose message.
# Messag
e is not displayed.
# Change
the value to Continue.
PS> Write-Verbose "Verbose message test."
# Write
a verbose message.
VERBOSE: Verbose message test.
# Messag
e is displayed.
# Change
the value to Stop.
PS> Write-Verbose "Verbose message test."
# Write
a verbose message.
VERBOSE: Verbose message test.
Write-Verbose : Command execution stopped
because the shell variable "VerbosePreference"
is set to Stop.
At line:1 char:14
+ Write-Verbose <<<< "Verbose message test
."
# Change t
he value to Inquire.
PS> Write-Verbose "Verbose message test."
$WarningPreference
------------------
Determines how Windows PowerShell responds
to warning messages
generated by a script, cmdlet or provider,
such as the messages
generated by the Write-Warning cmdlet.
EXAMPLES
# Write a war
ning message.
PS> Write-Warning "This action can dele
te data."
WARNING: This action can delete data.
# Change the
value to Inquire.
PS> Write-Warning "This action can delet
e data."
# Write a war
ning message.
WARNING: This action can delete data.
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Comma
nd [S] Suspend [?] Help (default is "Y"): y
PS>
# Change the v
alue to Stop.
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Comma
nd [S] Suspend [?] Help (default is "Y"):
# Use the Wa
rningAction parameter to change the
# response t
o a warning for the current command.
$WhatIfPreference
------------------
Determines whether WhatIf is automatically
enabled for every command
that supports it. When WhatIf is enabled, t
he cmdlet reports the
expected effect of the command, but does no
t execute the command.
Valid values:
0: WhatIf is not automatic
ally enabled. To
(Default) enable it manually,
use the WhatIf parameter
of the command.
1: WhatIf is automatic
ally enabled on any
command that suppor
ts it. Users can use the
WhatIf command with
a value of False to
disable it manually
(WhatIf:$false).
DETAILED EXPLANATION
Directory: Microsoft.PowerShell.Core\
FileSystem::C:
Mode LastWriteTime
Length Name
---- -------------
------ ----
-a--- 7/29/2006 7:15 PM
84 test.txt
EXAMPLES
PS> $whatifpreference
0 # Check the
current value.
PS> $whatifpreference = 1
PS> $whatifpreference
1 # Change the
value.
PS> $whatifpreference = 1
# Change the v
alue to 1.
SEE ALSO
about_Automatic_Variables
about_CommonParameters
about_Environment_Variables
about_Profiles
about_Remote
about_Scopes
about_Variables