Professional Documents
Culture Documents
About Preference Variables - Help
About Preference Variables - Help
Preference Variables
SHORT DESCRIPTION
Variables that customize the behavior of Windows PowerShell
LONG DESCRIPTION
Windows PowerShell includes a set of variables that enable you to
customize its behavior. These "preference variables" work like the
options in GUI-based systems.
The preference variables affect the Windows PowerShell operating
environment and all commands run in the environment. In many cases,
the cmdlets have parameters that you can use to override the preference
behavior for a specific command.
The following table lists the preference variables and their default
values.
Variable
-------$ConfirmPreference
$DebugPreference
$ErrorActionPreference
$ErrorView
$FormatEnumerationLimit
$LogCommandHealthEvent
$LogCommandLifecycleEvent
$LogEngineHealthEvent
$LogEngineLifecycleEvent
$LogProviderLifecycleEvent
$LogProviderHealthEvent
$MaximumAliasCount
$MaximumDriveCount
$MaximumErrorCount
$MaximumFunctionCount
$MaximumHistoryCount
$MaximumVariableCount
$OFS
$OutputEncoding
$ProgressPreference
$PSEmailServer
$PSSessionApplicationName
$PSSessionConfigurationName
/microsoft.powershell
$PSSessionOption
$VerbosePreference
$WarningPreference
$WhatIfPreference
Default Value
------------High
SilentlyContinue
Continue
NormalView
4
False (not logged)
False (not logged)
True (logged)
True (logged)
True (logged)
True (logged)
4096
4096
256
4096
64
4096
(Space character (" "))
ASCIIEncoding object
Continue
(None)
WSMAN
http://schemas.microsoft.com/powershell
(See below)
SilentlyContinue
Continue
0
$ConfirmPreference
-----------------Determines which cmdlet actions automatically request confirmation
from the user before they are performed.
When the $ConfirmPreference value (High, Medium, Low, None) is
greater than or equal to the risk of the cmdlet action (High, Medium,
Low, None), Windows PowerShell automatically requests confirmation
from the user before performing the action.
You can use the Confirm parameter of a cmdlet to override the preference
for a specific command.
Valid values:
None:
Low:
PS>
$DebugPreference
-----------------Determines how Windows PowerShell responds to debugging messages
generated by a script, cmdlet or provider, or by a Write-Debug
command at the command line.
Some cmdlets display debugging messages, which are typically very
technical messages designed for programmers and technical support
professionals. By default, debugging messages are not displayed,
but you can display debugging messages by changing the value of
$DebugPreference.
You can also use the Debug common parameter of a cmdlet to display
or hide the debugging messages for a specific command. For more
information, type: "get-help about_commonparameters".
Valid values:
Stop:
Inquire:
Continue:
SilentlyContinue:
(Default)
EXAMPLES
The following examples show the effect of changing the values of
$DebugPreference when a Write-Debug command is entered at the command
line. The change affects all debugging messages, including those
generated by cmdlets and scripts. The examples also show the use of the
PS>
This example shows the effect of the "Inquire" value. The final command
uses the Debug parameter with a value of $false to suppress the message
for a single command.
PS> $debugpreference = "Inquire"
PS> write-debug "Hello, World"
DEBUG: Hello, World
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (defaul
t is "Y"):
PS> write-debug "Hello, World" -Debug:$false
# Use the Debug parameter with
$false
PS>
# The debug message is not
displayed and processing
continues without interruption.
$ErrorActionPreference
---------------------Determines how Windows PowerShell responds to a non-terminating
error (an error that does not stop the cmdlet processing) at the
command line or in a script, cmdlet, or provider, such as the
errors generated by the Write-Error cmdlet.
You can also use the ErrorAction common parameter of a cmdlet to
override the preference for a specific command. For more
information, type: "get-help about_commonparameters".
Valid values:
Stop:
Inquire:
Continue:
SilentlyContinue:
(Default)
EXAMPLES
These examples show the effect of the different values of
$ErrorActionPreference and the use of the ErrorAction common parameter
to override the preference for a single command. The ErrorAction
parameter has the same valid values as the $ErrorActionPreference
variable.
This example shows the effect of the Continue value, which is the
default.
PS> $erroractionpreference
Continue
# Display the value of the preference.
PS> write-error "Hello, World"
# Generate a non-terminating error.
write-error "Hello, World" : Hello, World
# The error message is displayed and
execution continues.
PS> write-error "Hello, World" -ErrorAction:SilentlyContinue
# Use the ErrorAction parameter with a
value of "SilentlyContinue".
PS>
# The error message is not displayed and
execution continues.
This example shows the effect of the SilentlyContinue value.
PS> $ErrorActionPreference = "SilentlyContinue"
# Change the value of the preference.
PS> write-error "Hello, World"
# Generate an error message.
PS>
# Error message is suppressed.
PS> write-error "Hello, World" -erroraction:continue
# Use the ErrorAction parameter with a
value of "Continue".
write-error "Hello, World" -erroraction:continue : Hello, World
# The error message is displayed and
execution continues.
This example shows the effect of a real error. In this case, the command
gets a non-existent file, nofile.txt. The example also uses the
ErrorAction common parameter to override the preference.
PS> $erroractionpreference
SilentlyContinue
# Display the value of the preference.
PS> get-childitem -path nofile.txt
PS>
# Error message is suppressed.
PS> $ErrorActionPreference = "Continue"
# Change the value to Continue.
CategoryView:
ty}], {Reason}
For more information about the fields in CategoryView, see
"ErrorCategoryInfo class" in the Windows PowerShell SDK.
EXAMPLES
These example show the effect of the ErrorView values.
This example shows how an error appears when the value of $ErrorView is
NormalView. In this case, the Get-ChildItem command is used to find a
non-existent file.
PS> $ErrorView
NormalView
: System.Management.Automation.ItemNotFoundException: Canno
'C:\nofile.txt' because it does not exist.
at System.Management.Automation.SessionStateInternal.GetC
hildItems(String path,
Boolean recurse, CmdletProviderContext context)
at System.Management.Automation.ChildItemCmdletProviderIn
trinsics.Get(String path,
Boolean recurse, CmdletProviderContext context)
at Microsoft.PowerShell.Commands.GetChildItemCommand.Proc
essRecord()
TargetObject
: C:\nofile.txt
CategoryInfo
: ObjectNotFound: (C:\nofile.txt:String) [Get-Chil
dItem],
ItemNotFoundException
FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.GetCh
ildItemCommand
ErrorDetails
:
InvocationInfo
: System.Management.Automation.InvocationInfo
$FormatEnumerationLimit
----------------------Determines how many enumerated items are included in a display. This
variable does not affect the underlying objects; just the display.
When the value of $FormatEnumerationLimit is less than the number of
enumerated items, Windows PowerShell adds an ellipsis (...) to
indicate items not shown.
Valid values: Integers (Int32)
Default value: 4
EXAMPLES
This example shows how to use the $FormatEnumerationLimit variable
to improve the display of enumerated items.
The command in this example generates a table that lists all of the
services running on the computer in two groups; one for running
services and one for stopped services. It uses a Get-Service
command to get all of the services, and then send the results
through the pipeline to the Group-Object cmdlet, which groups the
results by the service status.
The resulting display is a table that lists the status in the Name
column and the processes with that status in the Group column. (To
change the column labels, use a hash table. For more information,
see the examples in "get-help format-table -examples".)
There are a maximum of 4 services listed in the Group column for
each status. To increase the number of items listed, increase
the value of $FormatEnumerationLimit to 1000.
In the resulting display, the list in the Group column is now
limited by the line length. In the final command in the example, use
the Wrap parameter of Format-Table to display all of the processes
in each Status group.
PS> $formatenumerationlimit
4
Group
----{AdtAgent, ALG, Ati HotKey Poller, Audio
41 Stopped
Srv...}
rt...}
# The list is truncated after
4 items.
PS> $formatenumerationlimit = 1000
# Increase the limit to 1000.
PS> get-service | group-object -property status
# Repeat the command.
Count Name
Group
----- -------60 Running {AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmExe
c...
41 Stopped {Alerter, AppMgmt, aspnet_state, ATI Smart, Browser, CiSv
c...
PS> get-service | group-object -property status | format-table -wrap
# Add the Wrap parameter.
Count Name
----- ---60 Running
xec, Client
Group
----{AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmE
for NFS, CryptSvc, DcomLaunch, Dhcp, dmserver, Dnscache
, ERSvc,
Eventlog, EventSystem, FwcAgent, helpsvc, HidServ, IISA
DMIN,
InoRPC, InoRT, InoTask, lanmanserver, lanmanworkstation
, LmHosts,
MDM, Netlogon, Netman, Nla, NtLmSsp, PlugPlay, PolicyAg
ent,
ProtectedStorage, RasMan, RemoteRegistry, RpcSs, SamSs,
Schedule,
seclogon, SENS, SharedAccess, ShellHWDetection, SMT PSV
C, Spooler,
srservice, SSDPSRV, stisvc, TapiSrv, TermService, Theme
s, TrkWks,
UMWdf, W32Time, W3SVC, WebClient, winmgmt, wscsvc, wuau
serv,
WZCSVC, zzInterix}
41 Stopped
Svc,
ClipSrv, clr_optimization_v2.0.50727_32, COMSysApp, Cro
nService,
dmadmin, FastUserSwitchingCompatibility, HTTPFilter, Im
apiService,
Mapsvc, Messenger, mnmsrvc, MSDTC, MSIServer, msvsmon80
, NetDDE,
NetDDEdsdm, NtmsSvc, NVSvc, ose, RasAuto, RDSessMgr, Re
moteAccess,
RpcLocator, RSVP, SCardSvr, SwPrv, SysmonLog, TlntSvr,
upnphost,
UPS, VSS, WmdmPmSN, Wmi, WmiApSrv, xmlprov}
$Log*Event
---------The Log*Event preference variables determine which types of events
are written to the Windows PowerShell event log in Event Viewer. By
default, only engine and provider events are logged, but you can use
the Log*Event preference variables to customize your log, such as
logging events about commands.
The Log*Event preference variables are as follows:
$LogCommandHealthEvent: Logs errors and exceptions in command initia
lization
and processing. Default = $false (not logged).
$LogCommandLifecycleEvent:
Logs the starting and stopping of commands and command pipelines
and security exceptions in command discovery. Default = $false (
not logged).
$LogEngineHealthEvent: Logs errors and failures of sessions. Default
= $true (logged).
$LogEngineLifecycleEvent: Logs the opening and closing of sessions.
Default = $true (logged).
$LogProviderHealthEvent: Logs provider errors, such as read and writ
e errors,
lookup errors, and invocation errors. Default = $true (logged).
$LogProviderLifecycleEvent: Logs adding and removing of Windows Powe
rShell providers.
Default = $true (logged). (For information about Windows PowerSh
ell providers, type:
"get-help about_provider".
To enable a Log*Event, type the variable with a value of $true, for exam
ple:
$LogCommandLifeCycleEvent
- or $LogCommandLifeCycleEvent = $true
To disable an event type, type the variable with a value of $false, for
example:
$LogCommandLifeCycleEvent = $false
The events that you enable are effective only for the current Windows Po
werShell
console. To apply the configuration to all consoles, save the variable s
ettings
in your Windows PowerShell profile.
$MaximumAliasCount
-----------------Determines how many aliases are permitted in a Windows PowerShell
session. The default value, 4096, should be sufficient for most
uses, but you can adjust it to meet your needs.
Valid values: 1024 - 32768 (Int32)
Default: 4096
To count the aliases on your system, type:
(get-alias).count
$MaximumDriveCount
------------------
$MaximumErrorCount
-----------------Determines how many errors are saved in the error history
for the session.
Valid values: 256 - 32768 (Int32)
Default: 256
Objects that represent each retained error are stored in the
$Error automatic variable. This variable contains an array of error
record objects, one for each error. The most recent error is the
first object in the array ($Error[0]).
To count the errors on your system, use the Count property of
the $Error array. Type:
$Error.count
To display a specific error, use array notation to display
the error. For example, to see the most recent error, type:
$Error[0]
To display the oldest retained error, type:
$Error[($Error.Count -1]
To display the properties of the ErrorRecord object, type:
$Error[0] | format-list -property * -force
In this command, the Force parameter overrides the special
formatting of ErrorRecord objects and reverts to the conventional
format.
To delete all errors from the error history, use the Clear method
of the error array.
PS> $Error.count
17
PS> $Error.clear()
PS>
PS> $Error.count
0
To find all properties and methods of an error array, use the
$MaximumVariableCount
-----------------Determines how many variables are permitted in a given session,
including automatic variables, preference variables, and the
variables that you create in commands and scripts.
Valid values: 1024 - 32768 (Int32)
Default: 4096
To see the variables in your session, use the Get-Variable cmdlet
and the features of the Windows PowerShell Variable: drive and the
Windows PowerShell Variable provider. For information about the
Variable provider, type "get-help variable".
$OFS
---Output Field Separator. Specifies the character that separates the
elements of an array when the array is converted to a string.
Valid values: Any string.
Default: Space
By default, the $OFS variable does not exist and the output file
separator is a space, but you can add this variable and set it to
any string.
EXAMPLES
This example shows that a space is used to separate the values when an
array is converted to a string. In this case, an array of integers is
stored in a variable and then the variable is cast as a string.
PS> $array = 1,2,3
PS> [string]$array
1 2 3
PS> [string]$array
1+2+3
To restore the default behavior, you can assign a space (" ") to
the value of $OFS or delete the variable. This command deletes the
variable and then verifies that the separator is a space.
PS> Remove-Variable OFS
PS>
# Delete $OFS
PS> [string]$array
1 2 3
$OutputEncoding
--------------Determines the character encoding method used by Windows PowerShell
when it sends text to other applications. For example, if an
application returns Unicode strings to Windows PowerShell, you might
need to change the value to to send the characters correctly.
Valid values: Objects derived from an encoding class, such as
ASCIIEncoding, SBCSCodePageEncoding, UTF7Encoding,
$ProgressPreference
------------------Determines how Windows PowerShell responds to progress 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 status of a command.
Valid values:
Stop:
Inquire:
Continue:
(Default)
SilentlyContinue:
$PSEmailServer
-------------Specifies the default e-mail server that is used to send e-mail
messages. This preference variable is used by 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.
The system default application name is WSMAN, but you can use this
preference variable to change the default.
The application name is the last node in a connection URI. For
example, the application name in the following sample URI is
WSMAN.
http://Server01:8080/WSMAN
The default application name is used when the remote command
does not specify a connection URI or an application name.
The WinRM service uses the application name to select a listener
to service the connection request. The value of this parameter
should match the value of the URLPrefix property of a listener
on the remote computer.
To override the system default and the value of this variable,
and select a different application name for a particular session,
use the ConnectionURI or ApplicationName parameters of the
New-PSSession, Enter-PSSession or Invoke-Command cmdlets.
This preference variable is set on the local computer, but it
specifies a listener on the remote computer. If the application
name that you specify does not exist on the remote computer,
the command to establish the session fails.
$PSSessionConfigurationName
--------------------------Specifies the default session configuration that is used for
For example,
$PSSessionOption = New-PSSessionOption -NoCompression
To use the $PSSessionOption preference variable in every
Windows PowerShell session, add a New-PSSessionOption command
that creates the $PSSessionOption variable to your Windows
PowerShell profile.
For more information about the New-PSSessionOption cmdlet, see
the help topic for New-PSSessionOption. For more information about
remote commands and sessions, see about_Remote and about_PSSessions.
For more information about using a profile, see about_Profiles.
$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. Typically, verbose messages
describe the actions performed to execute a command.
By default, verbose messages are not displayed, but you can change
this behavior by changing the value of $VerbosePreference.
You can also use the Verbose common parameter of a cmdlet to display
or hide the verbose messages for a specific command. For more
information, type: "get-help about_commonparameters".
Valid values:
Stop:
Inquire:
Continue:
with execution.
SilentlyContinue:
executing.
(Default)
EXAMPLES
These examples show the effect of the different values of $VerbosePreference
and the use of the
Verbose common parameter to override the preference value.
This example shows the effect of the SilentlyContinue value, which is the de
fault.
PS> $VerbosePreference
SilentlyContinue
PS>
# Message is not displayed.
$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.
By default, warning messages are displayed and execution continues,
but you can change this behavior by changing the value of
$WarningPreference.
You can also use the WarningAction common parameter of a cmdlet to
determine how Windows PowerShell responds to warnings from a particular
command. For more information, type: "get-help about_commonparameters".
Valid values:
Stop:
Inquire:
Continue:
(Default)
SilentlyContinue:
EXAMPLES
These examples show the effect of the different values of
$WarningPreference and the use of the WarningAction common parameter
to override the preference value.
This example shows the effect of the Continue value, which is the
default.
PS> $WarningPreference
Continue
# Write a warning message.
PS> Write-Warning "This action can delete data."
WARNING: This action can delete data.
# Use the WarningAction parameter to
# suppress the warning for this command
PS> Write-Warning "This action can delete data." -warningaction sile
ntlycontinue
ge the
# response to a warning for the current c
ommand.
re
WARNING: This action can delete data.
Confirm
Continue with this operation?
[Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (def
ault is "Y"):
# Use the WarningAction parameter to chan
ge the
# response to a warning for the current c
ommand.
$WhatIfPreference
-----------------Determines whether WhatIf is automatically enabled for every command
that supports it. When WhatIf is enabled, the cmdlet reports the
expected effect of the command, but does not execute the command.
Valid values:
0:
(Default)
1:
DETAILED EXPLANATION
When a cmdlet supports WhatIf, the cmdlet reports the expected
effect of the command, instead of executing the command. For
example, instead of deleting the test.txt file in response to a
Remove-Item command, Windows PowerShell reports what it would
delete. A subsequent Get-Childitem command confirms that the file
was not deleted.
PS> remove-item test.txt
What if: Performing operation "Remove-Item" on Target "Item:
C:\test.txt
PS> get-childitem test.txt
Directory: Microsoft.PowerShell.Core\FileSystem::C:
Mode
----a---
LastWriteTime
------------7/29/2006 7:15 PM
Length
-----84
Name
---test.txt
EXAMPLES
These examples show the effect of the different values of
$WhatIfPreference. They also show how to use the WhatIf cmdlet parameter
to override the preference value for a specific command.
This example shows the effect of the 0 (not enabled) value, which is the
default.
PS> $whatifpreference
0
PM(K)
WS(K) VM(M)
CPU(s)
Id ProcessNam
------- ------
-----
----- -----
------
-- ----------
e
234
6324
15060
154
0.36
2312 WINWORD
SEE ALSO
about_Automatic_Variables
about_CommonParameters
about_Environment_Variables
about_Profiles
about_Remote
about_Scopes
about_Variables