about_Pwsh
简短说明
说明如何使用 pwsh
命令-line 接口。 显示命令-line 参数并描述语法。
长说明
有关 Windows PowerShell 5.1 的命令-line 选项的信息,请参阅 about_PowerShell_exe。
语法
Usage: pwsh[.exe]
[-Login]
[[-File] <filePath> [args]]
[-Command { - | <script-block> [-args <arg-array>]
| <string> [<CommandParameters>] } ]
[-ConfigurationFile <filePath>]
[-ConfigurationName <string>]
[-CustomPipeName <string>]
[-EncodedCommand <Base64EncodedCommand>]
[-ExecutionPolicy <ExecutionPolicy>]
[-InputFormat {Text | XML}]
[-Interactive]
[-MTA]
[-NoExit]
[-NoLogo]
[-NonInteractive]
[-NoProfile]
[-NoProfileLoadTime]
[-OutputFormat {Text | XML}]
[-SettingsFile <filePath>]
[-SSHServerMode]
[-STA]
[-Version]
[-WindowStyle <style>]
[-WorkingDirectory <directoryPath>]
pwsh[.exe] -h | -Help | -? | /?
参数
所有参数都区分大小-i写。
-File | -f
如果 的File
-
值为 ,则从标准输入读取命令文本。
在没有重定向的标准输入的情况下运行 pwsh -File -
将启动常规会话。 这与根本不指定 File
参数相同。
如果不存在任何参数,但命令行中存在值,则这是默认参数。 指定的脚本在新会话的本地范围 (“dot-sourced”) 运行,以便脚本创建的函数和变量在新会话中可用。 输入脚本文件路径和任何参数。 File 必须是命令中的最后一个参数,因为在 File 参数名称之后键入的所有字符都解释为脚本文件路径,后跟脚本参数。
通常,将包括或忽略脚本的开关参数。
例如,以下命令使用 Get-Script.ps1 脚本文件的 All 参数: -File .\Get-Script.ps1 -All
在极少数情况下,可能需要为 switch 参数提供 布尔 值。 若要在 File 参数的值中为开关参数提供布尔值,请使用 通常紧跟冒号和布尔值的参数,如下所示:-File .\Get-Script.ps1 -All:$False
。
传递给脚本的参数作为文字字符串(在当前 shell 的解释后)传递。 例如,如果位于 中 cmd.exe
,并且想要传递环境变量值,则可以使用 cmd.exe
语法: pwsh -File .\test.ps1 -TestParam %windir%
相比之下,在 中cmd.exe
运行pwsh -File .\test.ps1 -TestParam $env:windir
会导致脚本接收文本字符串$env:windir
,因为它对当前 cmd.exe
shell 没有特殊含义。 $env:windir
环境变量引用的样式可以在Command 参数中使用,因为它被解释为 PowerShell 代码。
同样,如果要从 Batch 脚本执行相同的命令,可以使用 %~dp0
而不是 .\
或 $PSScriptRoot
来表示当前执行目录: pwsh -File %~dp0test.ps1 -TestParam %windir%
。 如果改用 .\test.ps1
,PowerShell 将引发错误,因为它找不到文本路径 .\test.ps1
注意
File 参数不能支持使用需要参数值数组的参数的脚本。 遗憾的是,这是本机命令获取参数值的方式的限制。 调用本机可执行文件 ((如 powershell
或 pwsh
) )时,它不知道该如何处理数组,因此会将其作为字符串传递。
当脚本文件使用 exit
命令终止时,进程退出代码将设置为与 命令一起使用的 exit
数值参数。 正常终止时,退出代码始终 0
为 。
有关详细信息,请参阅 $LASTEXITCODE
about_Automatic_Variables。
与 -Command
类似,发生脚本终止错误时,退出代码设置为 1
。 但是,与 -Command
不同,当使用 Ctrl+C 中断执行时,退出代码为 0
。
注意
从 PowerShell 7.2 起, 文件 参数仅接受 .ps1
Windows 上的文件。 如果提供了其他文件类型,则会引发错误。 此行为特定于 Windows。 在其他平台上,PowerShell 会尝试运行其他文件类型。
-Command | -c
执行指定的命令 (和任何参数) ,就像在 PowerShell 命令提示符处键入一样,然后退出,除非 NoExit
指定了 参数。
Command 的值可以是 -
、脚本块或字符串。 如果 Command-
的值为 ,则从标准输入读取命令文本。
Command 参数仅在可以将传递给 Command 的值识别为 ScriptBlock 类型时,才接受用于执行的脚本块。 仅当从另一台 PowerShell 主机运行时pwsh
,才可能执行此操作。 在传递给 pwsh
之前,ScriptBlock 类型可以包含在现有变量中、从表达式返回或由 PowerShell 主机分析为大括号 ({}
) 括在大括号中的文字脚本块。
pwsh -Command {Get-WinEvent -LogName security}
在 中 cmd.exe
,没有脚本块 (或 ScriptBlock 类型) ,因此传递给 Command 的值 始终 是字符串。 可以在字符串内编写脚本块,但与其执行脚本块,不如在典型的 PowerShell 提示符下键入脚本块,而是将脚本块的内容打印回你。
传递给 Command 的字符串仍作为 PowerShell 代码执行,因此从 cmd.exe
运行 时,通常不需要脚本块大括号。 若要执行字符串中定义的内联脚本块,可以使用 call 运算符&
:
pwsh -Command "& {Get-WinEvent -LogName security}"
如果 Command 的值为字符串, 则 Command 必须是 pwsh 的最后一个参数,因为它后面的所有参数都解释为要执行的命令的一部分。
从现有 PowerShell 会话中调用时,结果作为反序列化的 XML 对象(而不是实时对象)返回到父 shell。 对于其他 shell,结果以字符串的形式返回。
如果 Command-
的值为 ,则从标准输入读取命令文本。 将 Command 参数与标准输入配合使用时,必须重定向标准输入。 例如:
@'
"in"
"hi" |
% { "$_ there" }
"out"
'@ | powershell -NoProfile -Command -
该示例产生下面的输出:
in
hi there
out
进程退出代码由脚本块中最后一个 () 命令的状态确定。 退出代码是 0
当 $?
为 $true
或 1
时 $?
为 $false
。 如果最后一个命令是显式设置 或 1
以外的0
退出代码的外部程序或 PowerShell 脚本,则退出代码将转换为 1
进程退出代码。 若要保留特定的退出代码,请将 添加到 exit $LASTEXITCODE
命令字符串或脚本块。
有关详细信息,请参阅 $LASTEXITCODE
about_Automatic_Variables。
同样,当脚本终止 (运行空间终止) 错误(如 throw
或 -ErrorAction Stop
)发生时,或者当使用 Ctrl+C 中断执行时,将返回值 1。
-ConfigurationName | -config
指定运行 PowerShell 的配置终结点。 这可以是在本地计算机上注册的任何终结点,包括默认 PowerShell 远程处理终结点或具有特定用户角色功能的自定义终结点。
示例: pwsh -ConfigurationName AdminRoles
-ConfigurationFile
指定会话配置 (.pssc
) 文件路径。 配置文件中包含的配置将应用于 PowerShell 会话。
示例: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"
-CustomPipeName
指定要用于其他 IPC 服务器的名称, (用于调试和其他跨进程通信的命名管道) 。 这为连接到其他 PowerShell 实例提供了可预测的机制。 通常与 上的 Enter-PSHostProcess
CustomPipeName 参数一起使用。
此参数是在 PowerShell 6.2 中引入的。
例如:
# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe
-EncodedCommand | -e | -ec
接受命令的 Base64-encoded 字符串版本。 使用此参数将需要复杂嵌套报价的命令提交到 PowerShell。 Base64 表示形式必须是 UTF-16LE 编码字符串。
例如:
$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand
-ExecutionPolicy | -ex | -ep
设置当前会话的默认执行策略,并将其保存在环境变量中 $env:PSExecutionPolicyPreference
。 此参数不会更改持久配置的执行策略。
此参数仅适用于 Windows 计算机。 在非 Windows 平台上,将忽略 参数和提供的值。
-InputFormat | -inp | -if
描述发送到 PowerShell 的数据格式。 有效值为“Text”(文本字符串)或“XML”(序列化 CLIXML 格式)。
-Interactive | -i
向用户显示交互式提示。 NonInteractive 参数的反转。
-Login | -l
在 Linux 和 macOS 上,启动 PowerShell 作为登录 shell,使用 /bin/sh 执行登录配置文件,如 /etc/profile 和 ~/.profile。 在 Windows 上,此开关不执行任何操作。
重要
此参数必须首先作为登录 shell 启动 PowerShell。 如果此参数在另一个位置传递,则忽略此参数。
若要在 UNIX-like 操作系统上设置为pwsh
登录 shell,请执行以下操作:
验证到 的完整绝对路径
pwsh
是否在 下列出/etc/shells
- 此路径通常类似于
/usr/bin/pwsh
Linux 或/usr/local/bin/pwsh
macOS 上的 - 使用某些安装方法时,将在安装时自动添加此项
- 如果
pwsh
中/etc/shells
不存在 ,请使用编辑器将路径追加到pwsh
最后一行。 这需要提升的权限才能进行编辑。
- 此路径通常类似于
使用 chsh 实用工具将当前用户的 shell 设置为
pwsh
:chsh -s /usr/bin/pwsh
警告
适用于 Linux 的 Windows 子系统 (WSL) 当前不支持将 pwsh
设置为登录 shell,并且尝试将 设置为pwsh
登录 shell 可能会导致无法以交互方式启动 WSL。
-MTA
使用多线程单元启动 PowerShell。 此开关仅在 Windows 上可用。 在非 Windows 平台上使用此参数会导致错误。
-NoExit | -noe
运行启动命令后不退出。
示例: pwsh -NoExit -Command Get-Date
-NoLogo | -nol
在交互式会话启动时隐藏横幅。
-NonInteractive | -noni
此开关用于创建不需要用户输入的会话。 这对于在计划任务或 CI/CD 管道中运行的脚本很有用。 任何尝试使用交互式功能(如 Read-Host
或确认提示)都会导致语句终止错误,而不是挂起。
-NoProfile | -nop
不加载 PowerShell 配置文件。
-NoProfileLoadTime
当加载时间超过 500 毫秒时,隐藏启动时显示的 PowerShell 配置文件加载时间文本。
-OutputFormat | -o | -of
确定 PowerShell 输出内容的格式。 有效值为“Text”(文本字符串)或“XML”(序列化 CLIXML 格式)。
示例: pwsh -o XML -c Get-Date
在 PowerShell 会话中调用时,你会得到反序列化的对象作为输出而不是纯字符串。 从其他 shell 调用时,输出是格式化为 CLIXML 文本的字符串数据。
-SettingsFile | -settings
替代会话的系统-wide powershell.config.json
设置文件。 默认情况下,系统-wide 设置从 目录中的 powershell.config.json
$PSHOME
读取。
请注意,参数指定的 -ConfigurationName
终结点不会使用这些设置。
示例: pwsh -SettingsFile c:\myproject\powershell.config.json
-SSHServerMode | -sshs
在 sshd_config 中用于将 PowerShell 作为 SSH 子系统运行。 它不用于任何其他用途或不受支持。
-STA
使用单线程单元启动 PowerShell。 这是默认值。 此开关仅在 Windows 平台上可用。 在非 Windows 平台上使用此参数会导致错误。
-Version | -v
显示 PowerShell 的版本。 忽略其他参数。
-WindowStyle | -w
为会话设置窗口样式。 有效值包括 Normal、Minimized、Maximized 和 Hidden。 此参数仅适用于 Windows。 在非 Windows 平台上使用此参数会导致错误。
-WorkingDirectory | -wd | -wo
通过在启动时执行 来设置初始工作目录。 支持任何有效的 PowerShell 文件路径。
若要在主目录中启动 PowerShell,请使用: pwsh -WorkingDirectory ~
-Help, -?, /?
显示 的 pwsh
帮助。 如果在 PowerShell 中键入 pwsh 命令,请在命令参数前面加上连字符 (-
) ,而不是) (/
正斜杠。