关于偏好变量

简短描述

自定义 PowerShell 行为的变量。

详细描述

PowerShell 包含一组变量，使您能够自定义其行为。这些首选项变量的工作方式类似于基于 GUI 的系统中的选项。

首选项变量会影响 PowerShell 操作环境以及在该环境中运行的所有命令。某些 cmdlet 具有允许您覆盖特定命令的首选项行为的参数。

下表列出了首选项变量及其默认值。

高

默默地继续

继续

简明视图

4

默默地继续

$false（未记录）

$false（未记录）

$true（已记录）

$true（已记录）

$true（已记录）

$true（已记录）

4096

空格字符 (" ")

UTF8Encoding 对象

继续

@{}（空哈希表）

$null（无）

全部

Windows 上为 Windows，非 Windows 上为 标准

$假

'wsman'

'http://schemas.microsoft.com/powershell/Microsoft.PowerShell'

PSSessionOption 对象

PSStyle 对象

$null（无）

默默地继续

继续

$假

PowerShell 包含以下存储用户首选项的环境变量。有关这些环境变量的更多信息，请参阅 about_Environment_Variables。

$env:PSExecutionPolicyPreference

$env:PSModulePath

笔记

对首选项变量的更改仅适用于它们所做的范围及其任何子范围。例如，您可以将更改首选项变量的影响限制为单个函数或脚本。有关详细信息，请参阅 about_Scopes。

使用偏好变量

本文档描述了每个偏好变量。

要显示特定首选项变量的当前值，请键入变量的名称。例如，以下命令显示 $ConfirmPreference 变量的值。

 $ConfirmPreference

High

要更改变量的值，请使用赋值语句。例如，以下语句将 $ConfirmPreference 参数的值更改为 Medium。

$ConfirmPreference = "Medium"

您设置的值特定于当前 PowerShell 会话。要使变量在所有 PowerShell 会话中有效，请将它们添加到您的 PowerShell 配置文件中。有关详细信息，请参阅 about_Profiles。

远程工作

当您在远程计算机上运行命令时，远程命令仅受远程计算机的 PowerShell 客户端中设置的首选项的约束。例如，当您运行远程命令时，远程计算机的 $DebugPreference 变量的值决定 PowerShell 如何响应调试消息。

有关远程命令的更多信息，请参阅 about_Remote。

$ConfirmPreference

确定 PowerShell 在运行 cmdlet 或函数之前是否自动提示您进行确认。

$ConfirmPreference 变量采用 ConfirmImpact 枚举值之一：High、Medium、Low强>，或无。

Cmdlet 和函数被分配高、中或低风险。当 $ConfirmPreference 变量的值小于或等于分配给 cmdlet 或函数的风险时，PowerShell 会在运行 cmdlet 或函数之前自动提示您进行确认。有关为 cmdlet 或函数分配风险的详细信息，请参阅 about_Functions_CmdletBindingAttribute。

如果 $ConfirmPreference 变量的值为 None，则 PowerShell 在运行 cmdlet 或函数之前绝不会自动提示您。

要更改会话中所有 cmdlet 和函数的确认行为，请更改 $ConfirmPreference 变量的值。

要覆盖单个命令的 $ConfirmPreference，请使用 cmdlet 或函数的 Confirm 参数。要请求确认，请使用-Confirm。要禁止确认，请使用 -Confirm:$false。

$ConfirmPreference 的有效值：

• 无：PowerShell 不会自动提示。要请求确认特定命令，请使用 cmdlet 或函数的 Confirm 参数。
• 低：PowerShell 在运行具有低、中或高风险的 cmdlet 或函数之前提示您进行确认。
• 中：PowerShell 在运行具有中度或高风险的 cmdlet 或函数之前提示您进行确认。
• 高：PowerShell 在运行具有高风险的 cmdlet 或函数之前提示确认。

详细解释

PowerShell 可以在执行操作之前自动提示您进行确认。例如，当 cmdlet 或函数严重影响系统删除数据或使用大量系统资源时。

Remove-Item -Path C:\file.txt

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\file.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"):

风险估计是 cmdlet 或函数的一个属性，称为其 ConfirmImpact。用户无法更改它。

可能对系统构成风险的 Cmdlet 和函数具有 Confirm 参数，您可以使用该参数请求或禁止对单个命令进行确认。

大多数 cmdlet 和函数都为 ConfirmImpact 保留默认值 Medium。默认情况下，$ConfirmPreference 设置为高。因此，当用户未指定 Confirm 参数时，命令很少会自动提示确认。要将自动确认提示扩展到更多 cmdlet 和函数，请将 $ConfirmPreference 的值设置为 Medium 或 Low。

示例

此示例显示了$ConfirmPreference 变量的默认值High 的效果。 高值仅确认高风险 cmdlet 和函数。由于大多数 cmdlet 和函数都属于中等风险，因此不会自动确认它们，并且 Remove-Item 会删除该文件。在命令中添加 -Confirm 会提示用户确认。

$ConfirmPreference

High

Remove-Item -Path C:\temp1.txt

使用-Confirm请求确认。

Remove-Item -Path C:\temp2.txt -Confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\temp2.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All
[?] Help (default is "Y"):

以下示例显示将 $ConfirmPreference 的值更改为 Medium 的效果。由于大多数 cmdlet 和函数都是中等风险，因此它们会被自动确认。要禁止显示单个命令的确认提示，请使用值为 $false 的 Confirm 参数。

$ConfirmPreference = "Medium"
Remove-Item -Path C:\temp2.txt

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target "C:\temp2.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All
[?] Help (default is "Y"):

Remove-Item -Path C:\temp3.txt -Confirm:$false

$调试首选项

确定 PowerShell 如何响应由脚本、cmdlet 或提供程序生成的调试消息，或者由命令行中的 Write-Debug 命令生成的调试消息。

$DebugPreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

某些 cmdlet 显示调试消息，这些消息通常是为程序员和技术支持专业人员设计的技术消息。默认情况下，不显示调试消息，但您可以通过更改 $DebugPreference 的值来显示调试消息。

您可以使用 cmdlet 的调试通用参数来显示或隐藏特定命令的调试消息。有关更多信息，请参阅 about_CommonParameters。

有效值如下：

• Break - 当发生错误或引发异常时进入调试器。
• 停止：显示调试消息并停止执行。将错误写入控制台。
• 询问：显示调试消息并询问您是否要继续。
• 继续：显示调试消息并继续执行。
• SilentlyContinue：（默认）无效果。不显示调试消息并且执行继续而不会中断。

向命令添加 Debug 通用参数，当命令配置为生成调试消息时，将 $DebugPreference 变量的值更改为 Continue 。

示例

以下示例显示了在命令行输入 Write-Debug 命令时更改 $DebugPreference 值的效果。此更改会影响所有调试消息，包括 cmdlet 和脚本生成的消息。这些示例显示了 Debug 参数，该参数显示或隐藏与单个命令相关的调试消息。

此示例显示了$DebugPreference 变量的默认值SilentlyContinue 的效果。默认情况下，不会显示 Write-Debug cmdlet 的调试消息并继续处理。当使用调试参数时，它会覆盖单个命令的首选项。显示调试消息。

$DebugPreference

SilentlyContinue

Write-Debug -Message "Hello, World"

Write-Debug -Message "Hello, World" -Debug

DEBUG: Hello, World

此示例显示 $DebugPreference 与 Continue 值的效果。将显示调试消息并且命令继续处理。

$DebugPreference = "Continue"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World

此示例使用值为 $false 的 Debug 参数来抑制单个命令的消息。不显示调试消息。

Write-Debug -Message "Hello, World" -Debug:$false

此示例显示将 $DebugPreference 设置为 Stop 值的效果。显示调试消息并停止命令。

$DebugPreference = "Stop"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World
Write-Debug : The running command stopped because the preference variable
 "DebugPreference" or common parameter is set to Stop: Hello, World
At line:1 char:1
+ Write-Debug -Message "Hello, World"

此示例使用值为 $false 的 Debug 参数来抑制单个命令的消息。不会显示调试消息并且处理不会停止。

Write-Debug -Message "Hello, World" -Debug:$false

此示例显示将 $DebugPreference 设置为 Inquire 值的效果。显示调试消息并提示用户确认。

$DebugPreference = "Inquire"
Write-Debug -Message "Hello, World"

DEBUG: Hello, World

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

此示例使用值为 $false 的 Debug 参数来抑制单个命令的消息。不显示调试消息并且处理继续。

Write-Debug -Message "Hello, World" -Debug:$false

$ErrorActionPreference

确定 PowerShell 如何响应非终止错误（不会停止 cmdlet 处理的错误）。例如，在命令行或脚本、cmdlet 或提供程序中，例如 Write-Error cmdlet 生成的错误。

$ErrorActionPreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

您可以使用 cmdlet 的 ErrorAction 通用参数来覆盖特定命令的首选项。

有效值如下：

• Break - 当发生错误或引发异常时进入调试器。
• 继续：（默认）显示错误消息并继续执行。
• 忽略：抑制错误消息并继续执行命令。 忽略值旨在供每个命令使用，而不是用作保存的首选项。 Ignore 不是 $ErrorActionPreference 变量的有效值。
• 询问：显示错误消息并询问您是否要继续。
• 静默继续：没有效果。不会显示错误消息，并且执行会继续而不会中断。
• 停止：显示错误消息并停止执行。除了生成的错误之外，Stop 值还会生成一个 ActionPreferenceStopException 对象到错误流。
• 暂停：自动暂停工作流程作业以进行进一步调查。调查结束后，工作流程即可恢复。 挂起值旨在供每个命令使用，而不是用作保存的首选项。 挂起 不是 $ErrorActionPreference 变量的有效值。

$ErrorActionPreference 和 ErrorAction 参数不会影响 PowerShell 如何响应停止 cmdlet 处理的终止错误。有关 ErrorAction 公共参数的更多信息，请参阅 about_CommonParameters。

许多本机命令写入 stderr 作为附加信息的替代流。在查看错误时，此行为可能会导致混乱，或者如果将 $ErrorActionPreference 设置为静音输出的状态，则用户可能会丢失附加输出信息。

从 PowerShell 7.2 开始，从本机命令重定向的错误记录（例如使用重定向运算符 (2>&1) 时）不会写入 $Error 变量和首选项变量$ErrorActionPreference 不会影响重定向的输出。

PowerShell 7.3 添加了一项实验性功能，允许您控制如何处理写入 stderr 的消息。

有关详细信息，请参阅 $PSNativeCommandUseErrorActionPreference。

示例

这些示例显示了 $ErrorActionPreference 变量的不同值的效果。 ErrorAction 参数用于覆盖 $ErrorActionPreference 值。

此示例显示 $ErrorActionPreference 默认值 Continue。生成非终止错误。将显示该消息并继续处理。

# Change the ErrorActionPreference to 'Continue'
$ErrorActionPreference = 'Continue'
# Generate a non-terminating error and continue processing the script.
Write-Error -Message  'Test Error' ; Write-Host 'Hello World'

Write-Error: Test Error
Hello World

此示例显示 $ErrorActionPreference 默认值 Inquire。将生成错误并显示操作提示。

# Change the ErrorActionPreference to 'Inquire'
$ErrorActionPreference = 'Inquire'
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'

Confirm
Test Error
[Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"):

此示例显示将 $ErrorActionPreference 设置为 SilentlyContinue。错误消息被抑制。

# Change the ErrorActionPreference to 'SilentlyContinue'
$ErrorActionPreference = 'SilentlyContinue'
# Generate an error message
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'
# Error message is suppressed and script continues processing

Hello World

此示例显示将 $ErrorActionPreference 设置为 Stop。它还显示为 $Error 变量生成的额外对象。

# Change the ErrorActionPreference to 'Stop'
$ErrorActionPreference = 'Stop'
# Error message is generated and script stops processing
Write-Error -Message 'Test Error' ; Write-Host 'Hello World'

# Show the ActionPreferenceStopException and the error generated
$Error[0]
$Error[1]

Write-Error: Test Error

ErrorRecord                 : Test Error
WasThrownFromThrowStatement : False
TargetSite                  : System.Collections.ObjectModel.Collection`1[System.Management.Automation.PSObject]
                              Invoke(System.Collections.IEnumerable)
StackTrace                  :    at System.Management.Automation.Runspaces.PipelineBase.Invoke(IEnumerable input)
                                 at Microsoft.PowerShell.Executor.ExecuteCommandHelper(Pipeline tempPipeline,
                              Exception& exceptionThrown, ExecutionOptions options)
Message                     : The running command stopped because the preference variable "ErrorActionPreference" or
                              common parameter is set to Stop: Test Error
Data                        : {System.Management.Automation.Interpreter.InterpretedFrameInfo}
InnerException              :
HelpLink                    :
Source                      : System.Management.Automation
HResult                     : -2146233087

Write-Error: Test Error

$ErrorView

确定 PowerShell 中错误消息的显示格式。

$ErrorView 变量采用 ErrorView 枚举值之一：NormalView、CategoryView 或 ConciseView 。

有效值如下：

• ConciseView：（默认）为高级模块构建器提供简洁的错误消息和重构视图。从 PowerShell 7.2 开始，如果错误来自命令行或脚本模块，则输出为单行错误消息。否则，您将收到一条多行错误消息，其中包含错误和指向错误的指针，显示该错误在该行中发生的位置。如果终端支持虚拟终端，则使用 ANSI 颜色代码来提供颜色强调。可以在 $Host.PrivateData.ErrorAccentColor 更改强调颜色。使用 Get-Error cmdlet 获取完全限定错误的全面详细视图，包括内部异常。

  PowerShell 7 中添加了 ConciseView。

• NormalView：为大多数用户设计的详细视图。由错误的描述和错误中涉及的对象的名称组成。

• CategoryView：专为生产环境设计的简洁、结构化的视图。格式如下：

  {Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

有关 CategoryView 中字段的详细信息，请参阅 ErrorCategoryInfo 类。

示例

此示例显示当 $ErrorView 的值为默认值 ConciseView 时如何出现错误。 Get-ChildItem 用于查找不存在的目录。

Get-ChildItem -path 'C:\NoRealDirectory'

Get-ChildItem: Can't find path 'C:\NoRealDirectory' because it doesn't exist.

此示例显示当 $ErrorView 的值为默认值 ConciseView 时如何出现错误。 Script.ps1 运行并从 Get-Item 语句引发错误。

./Script.ps1

Get-Item: C:\Script.ps1
Line |
  11 | Get-Item -Path .\stuff
     | ^ Can't find path 'C:\demo\stuff' because it doesn't exist.

此示例显示当 $ErrorView 的值更改为 NormalView 时如何出现错误。 Get-ChildItem 用于查找不存在的文件。

Get-ChildItem -Path C:\nofile.txt

Get-ChildItem : Can't find path 'C:\nofile.txt' because it doesn't exist.
At line:1 char:1
+ Get-ChildItem -Path C:\nofile.txt

此示例显示当 $ErrorView 的值更改为 CategoryView 时如何出现相同的错误。

$ErrorView = "CategoryView"
Get-ChildItem -Path C:\nofile.txt

ObjectNotFound: (C:\nofile.txt:String) [Get-ChildItem], ItemNotFoundException

此示例演示了 $ErrorView 的值仅影响错误显示。它不会更改存储在 $Error 自动变量中的错误对象的结构。有关 $Error 自动变量的信息，请参阅 about_automatic_variables。

以下命令获取与错误数组中最新错误关联的 ErrorRecord 对象，元素 0，并格式化列表中对象的属性。

$Error[0] | Format-List -Property * -Force

PSMessageDetails      :
Exception             : System.Management.Automation.ItemNotFoundException:
                          Cannot find path 'C:\nofile.txt' because it does
                          not exist.
                        at System.Management.Automation.SessionStateInternal.
                          GetChildItems(String path, Boolean recurse, UInt32
                          depth, CmdletProviderContext context)
                        at System.Management.Automation.ChildItemCmdlet
                          ProviderIntrinsics.Get(String path, Boolean
                          recurse, UInt32 depth, CmdletProviderContext context)
                        at Microsoft.PowerShell.Commands.GetChildItemCommand.
                          ProcessRecord()
TargetObject          : C:\nofile.txt
CategoryInfo          : ObjectNotFound: (C:\nofile.txt:String) [Get-ChildItem],
                          ItemNotFoundException
FullyQualifiedErrorId : PathNotFound,
                          Microsoft.PowerShell.Commands.GetChildItemCommand
ErrorDetails          :
InvocationInfo        : System.Management.Automation.InvocationInfo
ScriptStackTrace      : at <ScriptBlock>, <No file>: line 1
PipelineIterationInfo : {0, 1}

$FormatEnumerationLimit

确定显示中包含多少个枚举项。该变量不会影响底层对象，只会影响显示。当 $FormatEnumerationLimit 的值小于枚举项的数量时，PowerShell 会添加省略号 (...) 以指示未显示的项。

有效值：整数 (Int32)

默认值：4

示例

此示例演示如何使用 $FormatEnumerationLimit 变量来改进枚举项的显示。

此示例中的命令生成一个表，其中列出了计算机上运行的所有服务，分为两组：一组用于正在运行的服务，一组用于已停止的服务。它使用 Get-Service 命令获取所有服务，然后通过管道将结果发送到 Group-Object cmdlet，后者按服务状态对结果进行分组。

结果是一个表格，其中在名称列中列出了状态，在组列中列出了进程。要更改列标签，请使用哈希表，请参阅 about_Hash_Tables。有关详细信息，请参阅格式表中的示例。

查找 $FormatEnumerationLimit 的当前值。

$FormatEnumerationLimit

4

列出按状态分组的所有服务。每个状态的 Group 列中最多列出四个服务，因为 $FormatEnumerationLimit 的值为 4。

Get-Service | Group-Object -Property Status

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv...}
41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart...}

要增加列出的项目数，请将 $FormatEnumerationLimit 的值增加到 1000。使用Get-Service 和Group-Object 显示服务。

$FormatEnumerationLimit = 1000
Get-Service | Group-Object -Property Status

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmExec...
41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart, Browser, CiSvc...

使用 Format-Table 和 Wrap 参数来显示服务列表。

Get-Service | Group-Object -Property Status | Format-Table -Wrap

Count  Name       Group
-----  ----       -----
60     Running    {AdtAgent, ALG, Ati HotKey Poller, AudioSrv, BITS, CcmExec,
                  Client for NFS, CryptSvc, DcomLaunch, Dhcp, dmserver,
                  Dnscache, ERSvc, Eventlog, EventSystem, FwcAgent, helpsvc,
                  HidServ, IISADMIN, InoRPC, InoRT, InoTask, lanmanserver,
                  lanmanworkstation, LmHosts, MDM, Netlogon, Netman, Nla,
                  NtLmSsp, PlugPlay, PolicyAgent, ProtectedStorage, RasMan,
                  RemoteRegistry, RpcSs, SamSs, Schedule, seclogon, SENS,
                  SharedAccess, ShellHWDetection, SMT PSVC, Spooler,
                  srservice, SSDPSRV, stisvc, TapiSrv, TermService, Themes,
                  TrkWks, UMWdf, W32Time, W3SVC, WebClient, winmgmt, wscsvc,
                  wuauserv, WZCSVC, zzInterix}

41     Stopped    {Alerter, AppMgmt, aspnet_state, ATI Smart, Browser, CiSvc,
                  ClipSrv, clr_optimization_v2.0.50727_32, COMSysApp,
                  CronService, dmadmin, FastUserSwitchingCompatibility,
                  HTTPFilter, ImapiService, Mapsvc, Messenger, mnmsrvc,
                  MSDTC, MSIServer, msvsmon80, NetDDE, NetDDEdsdm, NtmsSvc,
                  NVSvc, ose, RasAuto, RDSessMgr, RemoteAccess, RpcLocator,
                  SCardSvr, SwPrv, SysmonLog, TlntSvr, upnphost, UPS, VSS,
                  WmdmPmSN, Wmi, WmiApSrv, xmlprov}

$InformationPreference

$InformationPreference 变量允许您设置要向用户显示的信息流首选项。具体来说，是通过添加 Write-Information cmdlet 添加到命令或脚本的信息性消息。如果使用 InformationAction 参数，则其值将覆盖 $InformationPreference 变量的值。 Write-Information 是在 PowerShell 5.0 中引入的。

$InformationPreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

有效值如下：

• Break - 当写入信息流时进入调试器。
• 停止：在出现Write-Information 命令时停止命令或脚本。
• 查询：显示您在Write-Information 命令中指定的信息消息，然后询问您是否要继续。
• 继续：显示信息性消息，并继续运行。
• SilentlyContinue：（默认）无效果。不会显示信息性消息，并且脚本会继续执行而不会中断。

$日志*事件

Log*Event 首选项变量确定将哪些类型的事件写入事件查看器中的 PowerShell 事件日志。默认情况下，仅记录引擎和提供程序事件。但是，您可以使用Log*Event首选项变量来自定义日志，例如记录有关命令的事件。

Log*Event 首选项变量如下：

• $LogCommandHealthEvent：记录命令初始化和处理中的错误和异常。默认值为 $false （不记录）。
• $LogCommandLifecycleEvent：记录命令和命令管道的启动和停止以及命令发现中的安全异常。默认值为 $false （不记录）。
• $LogEngineHealthEvent：记录会话的错误和失败。默认值为 $true （已记录）。
• $LogEngineLifecycleEvent：记录会话的打开和关闭。默认值为 $true （已记录）。
• $LogProviderHealthEvent：记录提供程序错误，例如读写错误、查找错误和调用错误。默认值为 $true （已记录）。
• $LogProviderLifecycleEvent：记录 PowerShell 提供程序的添加和删除。默认值为 $true （已记录）。有关 PowerShell 提供程序的信息，请参阅 about_Providers。

要启用 Log*Event，请键入值为 $true 的变量，例如：

$LogCommandLifeCycleEvent = $true

要禁用事件类型，请键入值为 $false 的变量，例如：

$LogCommandLifeCycleEvent = $false

您启用的事件仅对当前 PowerShell 控制台有效。要将配置应用到所有控制台，请将变量设置保存在 PowerShell 配置文件中。有关详细信息，请参阅 about_Profiles。

$MaximumHistoryCount

确定当前会话的命令历史记录中保存的命令数量。

有效值：1 - 32768 (Int32)

默认：4096

要确定命令历史记录中当前保存的命令数，请键入：

(Get-History).Count

要查看会话历史记录中保存的命令，请使用 Get-History cmdlet。有关更多信息，请参阅 about_History。

$OFS

输出字段分隔符 (OFS) 指定用于分隔转换为字符串的数组的元素的字符。

有效值：任何字符串。

默认：空格

默认情况下，$OFS 变量不存在，并且输出文件分隔符为空格，但您可以添加此变量并将其设置为任何字符串。您可以通过键入 $OFS="" 来更改会话中 $OFS 的值。

笔记

如果您希望脚本、模块或配置输出中出现空格 (" ") 的默认值，请注意 $OFS 默认值尚未出现在代码的其他地方被更改。

示例

此示例显示当数组转换为字符串时，使用空格来分隔值。在这种情况下，整数数组存储在变量中，然后将该变量转换为字符串。

$array = 1,2,3,4
[string]$array

1 2 3 4

要更改分隔符，请通过为其赋值来添加 $OFS 变量。该变量必须命名为$OFS。

$OFS = "+"
[string]$array

1+2+3+4

要恢复默认行为，您可以为 $OFS 的值分配一个空格 (" ") 或删除该变量。以下命令删除变量，然后验证分隔符是否为空格。

Remove-Variable OFS
[string]$array

1 2 3 4

$输出编码

确定 PowerShell 在将数据传输到本机应用程序时使用的字符编码方法。

笔记

在大多数情况下，$OutputEncoding 的值应与 [Console]::InputEncoding 的值对齐。

有效值如下： 从 Encoding 类派生的对象，例如 ASCIIEncoding、UTF7Encoding、UTF8Encoding、UTF32Encoding > 和 Unicode 编码。

默认：UTF8Encoding 对象。

示例

第一个命令查找 $OutputEncoding 的值。由于该值是编码对象，因此仅显示其 EncodingName 属性。

$OutputEncoding.EncodingName

其余示例使用以下保存为 hexdump.ps1 的 PowerShell 脚本来说明 $OutputEncoding 的行为。

$inputStream = [Console]::OpenStandardInput()
try {
    $buffer = [byte[]]::new(1024)
    $read = $inputStream.Read($buffer, 0, $buffer.Length)
    Format-Hex -InputObject $buffer -Count $read
} finally {
    $inputStream.Dispose()
}

以下示例展示了字符串值 café 在通过管道传输到上面创建的 hexdump.ps1 时如何编码为字节。它演示了字符串值是使用 UTF8Encoding 方案进行编码的。

'café' | pwsh -File ./hexdump.ps1

   Label: Byte[] (System.Byte[]) <28873E25>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 63 61 66 C3 A9 0D 0A                            caf�

以下示例显示将编码更改为 UnicodeEncoding 时字节如何变化。

$OutputEncoding = [System.Text.Encoding]::Unicode
'café' | pwsh -File ./hexdump.ps1

   Label: Byte[] (System.Byte[]) <515A7DC3>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 FF FE 63 00 61 00 66 00 E9 00 0D 00 0A 00       ÿþc a f é � �

$ProgressPreference

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的进度更新，例如 Write-Progress cmdlet 生成的进度条。 Write-Progress cmdlet 创建显示命令状态的进度条。

$ProgressPreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

有效值如下：

• Break - 写入进度流时进入调试器。
• 停止：不显示进度条。相反，它会显示一条错误消息并停止执行。
• 查询：不显示进度条。提示允许继续。如果您回复 Y 或 A，则会显示进度条。
• 继续：（默认）显示进度条并继续执行。
• SilentlyContinue：执行命令，但不显示进度条。

$PSDefaultParameterValues

指定 cmdlet 和高级函数的参数的默认值。 $PSDefaultParameterValues 的值是一个哈希表，其中键由 cmdlet 名称和参数名称组成，并用冒号分隔 (:)。该值是您指定的自定义默认值。

$PSDefaultParameterValues 是在 PowerShell 3.0 中引入的。

有关此首选项变量的详细信息，请参阅 about_Parameters_Default_Values。

$PSEmail服务器

指定用于发送电子邮件的默认电子邮件服务器。此首选项变量由发送电子邮件的 cmdlet 使用，例如 Send-MailMessage cmdlet。

$PSModuleAutoloadingPreference

启用和禁用会话中模块的自动导入。默认情况下，$PSModuleAutoloadingPreference 变量不存在。未定义变量时的默认行为与 $PSModuleAutoloadingPreference='All' 相同。

要自动导入模块，请获取或使用模块中包含的命令。

$PSModuleAutoloadingPreference 变量采用 PSModuleAutoLoadingPreference 枚举值之一：

• 全部：模块在首次使用时自动导入。
• ModuleQualified：仅当用户在模块中使用命令的模块限定名称时，才会自动导入模块。例如，如果用户键入 MyModule\MyCommand，PowerShell 会导入 MyModule 模块。
• None：禁用模块的自动导入。要导入模块，请使用 Import-Module cmdlet。

有关自动导入模块的更多信息，请参阅 about_Modules。

$PSNativeCommandArgumentPassing

PowerShell 7.3 更改了解析本机命令命令行的方式。新的 $PSNativeCommandArgumentPassing 首选项变量控制此行为。

警告

新行为是对先前行为的重大更改。这可能会破坏调用本机应用程序时解决各种问题的脚本和自动化。

自动变量 $PSNativeCommandArgumentPassing 允许您在运行时选择行为。有效值为 Legacy、Standard 和 Windows。 Legacy 是历史行为。

$PSNativeCommandArgumentPassing 变量是默认定义的，但该值是特定于平台的。

• 在 Windows 上，首选项设置为 Windows。
• 在非 Windows 平台上，首选项设置为标准。
• 如果您已删除 $PSNativeCommandArgumentPassing 变量，PowerShell 将使用标准 行为。

Windows 和 Standard 模式的行为相同，只是在 Windows 模式下，PowerShell 使用以下的Legacy 行为：运行以下文件时传递参数。

cmd.exe

cscript.exe

find.exe

sqlcmd.exe

wscript.exe

.bat

.cmd

.js

.vbs

.wsf

如果 $PSNativeCommandArgumentPassing 设置为 Legacy 或 Standard，则解析器不会检查这些文件。有关新行为的示例，请参阅 about_Parsing。

PowerShell 7.3 还添加了跟踪本机命令参数绑定的功能。有关详细信息，请参阅跟踪命令。

$PSNativeCommandUseErrorActionPreference

当 $PSNativeCommandUseErrorActionPreference 为 $true 时，具有非零退出代码的本机命令会根据 $ErrorActionPreference 发出错误。

一些本机命令（例如 robocopy）使用非零退出代码来表示错误以外的信息。在这些情况下，您可以暂时禁用该行为并防止非零退出代码发出错误。

& {
    # Disable $PSNativeCommandUseErrorActionPreference for this scriptblock
    $PSNativeCommandUseErrorActionPreference = $false
    robocopy.exe D:\reports\operational "\reporting\ops" CY2022Q4.md
    if ($LASTEXITCODE -gt 8) {
        throw "robocopy failed with exit code $LASTEXITCODE"
    }
}

在此示例中，$PSNativeCommandUseErrorActionPreference 变量在脚本块内更改。更改是脚本块本地的。当脚本块退出时，变量将恢复为其之前的值。

$PSSessionApplicationName

指定使用 Web 管理服务 (WS-Management) 技术的远程命令的默认应用程序名称。有关详细信息，请参阅关于 Windows 远程管理。

系统默认应用程序名称为 WSMAN，但您可以使用此首选项变量来更改默认值。

应用程序名称是连接 URI 中的最后一个节点。例如，以下示例 URI 中的应用程序名称是 WSMAN。

http://Server01:8080/WSMAN

当远程命令未指定连接 URI 或应用程序名称时，将使用默认应用程序名称。

WinRM 服务使用应用程序名称来选择侦听器来服务连接请求。该参数的值应与远程计算机上侦听器的 URLPrefix 属性的值匹配。

要覆盖系统默认值和此变量的值，并为特定会话选择不同的应用程序名称，请使用 New-PSSession 的 ConnectionURI 或 ApplicationName 参数，输入-PSSession 或 Invoke-Command cmdlet。

$PSSessionApplicationName 首选项变量在本地计算机上设置，但它指定远程计算机上的侦听器。如果远程计算机上不存在您指定的应用程序名称，则建立会话的命令将失败。

$PSSessionConfigurationName

指定用于在当前会话中创建新会话的默认会话配置。

此首选项变量在本地计算机上设置，但它指定位于远程计算机上的会话配置。

$PSSessionConfigurationName 变量的值是完全限定的资源 URI。

默认值 http://schemas.microsoft.com/PowerShell/microsoft.PowerShell 指示远程计算机上的 Microsoft.PowerShell 会话配置。

如果仅指定配置名称，则会在前面添加以下架构 URI：

http://schemas.microsoft.com/PowerShell/

您可以使用 New-PSSession、Enter-PSSession 的 ConfigurationName 参数覆盖默认值并为特定会话选择不同的会话配置。或 Invoke-Command cmdlet。

您可以随时更改此变量的值。执行此操作时，请记住您选择的会话配置必须存在于远程计算机上。如果不是，则创建使用会话配置的会话的命令将失败。

此首选项变量无法确定远程用户创建连接到此计算机的会话时使用哪些本地会话配置。但是，您可以使用本地会话配置的权限来确定哪些用户可以使用它们。

$PSSessionOption

建立远程会话中高级用户选项的默认值。这些选项首选项会覆盖会话选项的系统默认值。

$PSSessionOption 变量包含一个 PSSessionOption 对象。有关详细信息，请参阅 System.Management.Automation.Remoting.PSSessionOption。对象的每个属性代表一个会话选项。例如，NoCompression 属性会在会话期间开启数据压缩。

默认情况下，$PSSessionOption 变量包含一个 PSSessionOption 对象，其中包含所有选项的默认值，如下所示。

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : None
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
IncludePortInSPN                  : False
OutputBufferingMode               : None
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         : 209715200
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : -00:00:00.0010000

有关这些选项的说明和更多信息，请参阅 New-PSSessionOption。有关远程命令和会话的详细信息，请参阅 about_Remote 和 about_PSSessions。

要更改 $PSSessionOption 首选项变量的值，请使用 New-PSSessionOption cmdlet 创建一个包含您喜欢的选项值的 PSSessionOption 对象。将输出保存在名为 $PSSessionOption 的变量中。

$PSSessionOption = New-PSSessionOption -NoCompression

要在每个 PowerShell 会话中使用 $PSSessionOption 首选项变量，请添加一个 New-PSSessionOption 命令，以将 $PSSessionOption 变量创建到您的 PowerShell 配置文件中。有关详细信息，请参阅 about_Profiles。

您可以为特定远程会话设置自定义选项。您设置的选项优先于系统默认值和 $PSSessionOption 首选项变量的值。

要设置自定义会话选项，请使用 New-PSSessionOption cmdlet 创建 PSSessionOption 对象。然后，使用 PSSessionOption 对象作为创建会话的 cmdlet 中 SessionOption 参数的值，例如 New-PSSession、输入-PSSession 和Invoke-Command。

$PS风格

从 PowerShell 7.2 开始，您现在可以访问 $PSStyle 自动变量来查看和更改 ANSI 字符串输出的呈现。 $PSStyle 是 PSStyle 类的实例。此类的成员定义包含 ANSI 转义序列的字符串，这些序列控制终端中文本的呈现。

基本成员返回映射到其名称的 ANSI 转义序列字符串。这些值可设置以允许定制。属性名称使您可以更轻松地使用制表符补全创建修饰字符串。例如：

"$($PSStyle.Background.BrightCyan)Power$($PSStyle.Underline)$($PSStyle.Bold)Shell$($PSStyle.Reset)"

Background 和 Foreground 成员还有一个 FromRgb() 方法来指定 24 位颜色。

有关 $PSStyle 的详细信息，请参阅 about_ANSI_Terminals。

$成绩单

由 Start-Transcript 用于指定转录文件的名称和位置。如果您没有指定 Path 参数的值，Start-Transcript 将使用 $Transcript 全局变量值中的路径。如果您尚未创建此变量，Start-Transcript 会使用默认名称将转录本存储在以下位置：

• 在 Windows 上：$HOME\Documents
• 在 Linux 或 macOS 上：$HOME

默认文件名是：PowerShell_transcript....txt。

$VerbosePreference

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的详细消息，例如 Write-Verbose cmdlet 生成的消息。详细消息描述了执行命令所执行的操作。

默认情况下，不显示详细消息，但您可以通过更改 $VerbosePreference 的值来更改此行为。

$VerbosePreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

有效值如下：

• Break - 写入 Verbose 流时进入调试器。
• 停止：显示详细消息和错误消息，然后停止执行。
• 查询：显示详细消息，然后显示提示，询问您是否要继续。
• 继续：显示详细消息，然后继续执行。
• SilentlyContinue：（默认）不显示详细消息。继续执行。

您可以使用 cmdlet 的详细通用参数来显示或隐藏特定命令的详细消息。有关更多信息，请参阅 about_CommonParameters。

示例

这些示例显示了 $VerbosePreference 和 Verbose 参数的不同值覆盖首选项值的效果。

此示例显示了 SilentlyContinue 值（默认值）的效果。该命令使用 Message 参数，但不会将消息写入 PowerShell 控制台。

Write-Verbose -Message "Verbose message test."

当使用 Verbose 参数时，将写入消息。

Write-Verbose -Message "Verbose message test." -Verbose

VERBOSE: Verbose message test.

此示例显示了继续值的效果。 $VerbosePreference 变量设置为Continue 并显示消息。

$VerbosePreference = "Continue"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.

此示例使用 Verbose 参数，其值为 $false，该参数将覆盖 Continue 值。该消息不显示。

Write-Verbose -Message "Verbose message test." -Verbose:$false

此示例显示停止值的效果。 $VerbosePreference 变量设置为 Stop 并显示消息。命令停止。

$VerbosePreference = "Stop"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.
Write-Verbose : The running command stopped because the preference variable
  "VerbosePreference" or common parameter is set to Stop: Verbose message test.
At line:1 char:1
+ Write-Verbose -Message "Verbose message test."

此示例使用 Verbose 参数，其值为 $false，该参数会覆盖 Stop 值。该消息不显示。

Write-Verbose -Message "Verbose message test." -Verbose:$false

此示例显示查询值的效果。 $VerbosePreference 变量设置为查询。将显示该消息并提示用户确认。

$VerbosePreference = "Inquire"
Write-Verbose -Message "Verbose message test."

VERBOSE: Verbose message test.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

此示例使用 Verbose 参数，其值为 $false，该参数会覆盖 Inquire 值。不会提示用户，也不会显示消息。

Write-Verbose -Message "Verbose message test." -Verbose:$false

$WarningPreference

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的警告消息，例如 Write-Warning cmdlet 生成的消息。

默认情况下，会显示警告消息并继续执行，但您可以通过更改 $WarningPreference 的值来更改此行为。

$WarningPreference 变量采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

有效值如下：

• Break - 当写入警告消息时进入调试器。
• 停止：显示警告消息和错误消息，然后停止执行。
• 查询：显示警告消息，然后提示是否允许继续。
• 继续：（默认）显示警告消息，然后继续执行。
• SilentlyContinue：不显示警告消息。继续执行。

您可以使用 cmdlet 的 WarningAction 通用参数来确定 PowerShell 如何响应来自特定命令的警告。有关更多信息，请参阅 about_CommonParameters。

示例

这些示例显示了 $WarningPreference 不同值的效果。 WarningAction 参数会覆盖首选项值。

此示例显示默认值继续的效果。

$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.

此示例使用带有值 SilentlyContinue 的 WarningAction 参数来抑制警告。该消息不显示。

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction SilentlyContinue

此示例将 $WarningPreference 变量更改为 SilentlyContinue 值。该消息不显示。

$WarningPreference = "SilentlyContinue"
$m = "This action can delete data."
Write-Warning -Message $m

此示例使用 WarningAction 参数在生成警告时停止。

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction Stop

WARNING: This action can delete data.
Write-Warning : The running command stopped because the preference variable
  "WarningPreference" or common parameter is set to Stop:
    This action can delete data.
At line:1 char:1
+ Write-Warning -Message $m -WarningAction Stop

此示例将 $WarningPreference 变量更改为 Inquire 值。系统会提示用户确认。

$WarningPreference = "Inquire"
$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

此示例使用值为 SilentlyContinue 的 WarningAction 参数。该命令继续执行并且不显示任何消息。

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction SilentlyContinue

此示例将 $WarningPreference 值更改为 Stop。

$WarningPreference = "Stop"
$m = "This action can delete data."
Write-Warning -Message $m

WARNING: This action can delete data.
Write-Warning : The running command stopped because the preference variable
  "WarningPreference" or common parameter is set to Stop:
    This action can delete data.
At line:1 char:1
+ Write-Warning -Message $m

此示例使用 WarningAction 和 Inquire 值。出现警告时会提示用户。

$m = "This action can delete data."
Write-Warning -Message $m -WarningAction Inquire

WARNING: This action can delete data.

Confirm
Continue with this operation?
[Y] Yes  [A] Yes to All  [H] Halt Command  [?] Help (default is "Y"):

$WhatIfPreference

确定是否为每个支持它的命令自动启用 WhatIf。启用 WhatIf 后，cmdlet 会报告命令的预期效果，但不会执行该命令。

有效值如下：

• False（0，未启用）：（默认）WhatIf 不会自动启用。要手动启用它，请使用 cmdlet 的 WhatIf 参数。
• True（1，启用）：WhatIf 在任何支持它的命令上自动启用。用户可以使用值为False的WhatIf参数来手动禁用它，例如-WhatIf:$false。

示例

这些示例显示了 $WhatIfPreference 的不同值的效果。它们展示了如何使用 WhatIf 参数来覆盖特定命令的首选项值。

此示例显示将 $WhatIfPreference 变量设置为默认值 False 的效果。使用 Get-ChildItem 验证文件是否存在。 Remove-Item 删除文件。文件删除后，您可以使用 Get-ChildItem 验证删除。

Get-ChildItem -Path .\test.txt
Remove-Item -Path ./test.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           9/13/2019    10:53             10 test.txt

Get-ChildItem -Path .\test.txt

Get-ChildItem : Cannot find path 'C:\Test\test.txt' because it does not exist.
At line:1 char:1
+ Get-ChildItem -File test.txt

此示例显示当 $WhatIfPreference 的值为 False 时使用 WhatIf 参数的效果。

验证该文件是否存在。

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

使用 WhatIf 参数确定尝试删除文件的结果。

Remove-Item -Path .\test2.txt -WhatIf

What if: Performing the operation "Remove File" on target "C:\Test\test2.txt".

验证该文件未被删除。

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

此示例显示将 $WhatIfPreference 变量设置为值 True 的效果。当您使用Remove-Item删除文件时，会显示文件的路径，但文件不会被删除。

尝试删除文件。将显示一条消息，说明运行 Remove-Item 时会发生什么情况，但文件并未被删除。

$WhatIfPreference = "True"
Remove-Item -Path .\test2.txt

What if: Performing the operation "Remove File" on target "C:\Test\test2.txt".

使用 Get-ChildItem 验证该文件未被删除。

Get-ChildItem -Path .\test2.txt

    Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           2/28/2019    17:06             12 test2.txt

此示例演示如何在 $WhatIfPreference 的值为 True 时删除文件。它使用值为 $false 的 WhatIf 参数。使用 Get-ChildItem 验证文件是否已删除。

Remove-Item -Path .\test2.txt -WhatIf:$false
Get-ChildItem -Path .\test2.txt

Get-ChildItem : Cannot find path 'C:\Test\test2.txt' because it does not exist.
At line:1 char:1
+ Get-ChildItem -Path .\test2.txt

以下是不支持 WhatIf 的 Get-Process cmdlet 和支持 WhatIfStop-Process 的示例强>。 $WhatIfPreference 变量的值为True。

Get-Process 不支持 WhatIf。执行命令时，会显示Winword进程。

Get-Process -Name Winword

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    130   119.84     173.38       8.39   15024   4 WINWORD

Stop-Process 支持WhatIf。 Winword 进程不会停止。

Stop-Process -Name Winword

What if: Performing the operation "Stop-Process" on target "WINWORD (15024)".

您可以使用值为 $false 的 WhatIf 参数来覆盖 Stop-Process WhatIf 行为。 Winword 进程已停止。

Stop-Process -Name Winword -WhatIf:$false

要验证 Winword 进程是否已停止，请使用 Get-Process。

Get-Process -Name Winword

Get-Process : Cannot find a process with the name "Winword".
  Verify the process name and call the cmdlet again.
At line:1 char:1
+ Get-Process -Name Winword

参见

• about_automatic_variables
• about_公共参数
• about_Environment_Variables
• about_个人资料
• about_Remote
• about_范围
• about_变量