关于 pwsh

项目
08/03/2024

简短说明

介绍如何使用 pwsh 命令行接口。显示命令行参数并描述语法。

长说明

语法

pwsh[.exe]
   [[-File] <filePath> [args]]
   [-Command { - | <script-block> [-args <arg-array>]
                 | <string> [<CommandParameters>] } ]
   [-ConfigurationName <string>]
   [-CustomPipeName <string>]
   [-EncodedCommand <Base64EncodedCommand>]
   [-ExecutionPolicy <ExecutionPolicy>]
   [-InputFormat {Text | XML}]
   [-Interactive]
   [-NoExit]
   [-NoLogo]
   [-NonInteractive]
   [-NoProfile]
   [-OutputFormat {Text | XML}]
   [-SettingsFile <SettingsFilePath>]
   [-Version]
   [-WindowStyle <style>]
   [-WorkingDirectory <directoryPath>]

pwsh[.exe] -h | -Help | -? | /?

参数

所有参数都区分大小写。

-File |-f

如果 File 的值 -，则从标准输入中读取命令文本。在没有重定向的标准输入的情况下运行 pwsh -File - 将启动常规会话。这与根本不指定 File 参数相同。

如果没有参数，但命令行中存在值，则这是默认参数。指定的脚本在本地范围（“dot-sourced”）中运行，以便脚本创建的函数和变量在当前会话中可用。输入脚本文件路径和任何参数。文件必须是命令中的最后一个参数，因为在 File 参数名称之后键入的所有字符都解释为脚本文件路径，后跟脚本参数。

通常，包括或省略脚本的开关参数。例如，以下命令使用 Get-Script.ps1 脚本文件的 All 参数：-File .\Get-Script.ps1 -All

在极少数情况下，可能需要为 switch 参数提供 布尔值 值。若要在 File 参数的值中为 switch 参数提供布尔值，请使用参数通常紧跟冒号和布尔值，例如：-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

当脚本文件以 exit 命令终止时，进程退出代码将设置为与 exit 命令一起使用的数字参数。正常终止时，退出代码始终 0。

与 -Command类似，当发生脚本终止错误时，退出代码将设置为 1。但是，与 -Command不同，当执行中断时，Ctrl-C 退出代码 0。

-Command |-c

执行指定的命令（和任何参数），就像在 PowerShell 命令提示符处键入它们一样，然后退出，除非指定了 NoExit 参数。

Command 的值可以是 -、脚本块或字符串。如果命令的值 -，则从标准输入读取命令文本。

Command 参数仅接受脚本块以供执行，当它可以将传递给 Command 的值识别为 ScriptBlock 类型。仅当从另一个 PowerShell 主机运行 pwsh 时，才能。 ScriptBlock 类型可以包含在现有变量中，从表达式返回，或由 PowerShell 主机分析为文本脚本块，包含在大括号（{}），然后传递给 pwsh。

pwsh -Command {Get-WinEvent -LogName security}

在 cmd.exe中，没有脚本块（或 ScriptBlock 类型），因此传递给 Command 的值始终字符串。可以在字符串内编写脚本块，但与其执行脚本块的行为完全相同，就像在典型的 PowerShell 提示符下键入脚本块一样，将脚本块的内容打印回你。

传递给 Command 的字符串仍作为 PowerShell 代码执行，因此从 cmd.exe运行时，通常不需要脚本块大括号。若要执行字符串中定义的内联脚本块，可以使用调用运算符&：

pwsh -Command "& {Get-WinEvent -LogName security}"

如果 Command 的值是字符串，Command 必须是 pwsh 的最后一个参数，因为其后面的所有参数都将解释为要执行的命令的一部分。

从现有 PowerShell 会话中调用时，结果将作为反序列化的 XML 对象（而不是实时对象）返回到父 shell。对于其他 shell，结果将作为字符串返回。

如果命令的值 -，则从标准输入读取命令文本。在将 Command 参数与标准输入配合使用时，必须重定向标准输入。例如：

@'
"in"

"hi" |
  % { "$_ there" }

"out"
'@ | powershell -NoProfile -Command -

此示例生成以下输出：

in
hi there
out

进程退出代码由脚本块中最后一个（已执行）命令的状态确定。当 $true$? 或 1$?$false时，退出代码 0。如果最后一个命令是外部程序或显式设置除 0 或 1以外的退出代码的 PowerShell 脚本，则退出代码将转换为进程退出代码的 1。若要保留特定的退出代码，请将 exit $LASTEXITCODE 添加到命令字符串或脚本块。

同样，当发生脚本终止（runspace-terminating）错误（如 throw 或 -ErrorAction Stop）时，或者当 Ctrl-C中断执行时，将返回值 1。

-ConfigurationName |-config

指定运行 PowerShell 的配置终结点。这可以是在本地计算机上注册的任何终结点，包括默认 PowerShell 远程处理终结点或具有特定用户角色功能的自定义终结点。

示例：pwsh -ConfigurationName AdminRoles

-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 编码字符串版本。使用此参数将命令提交到需要复杂嵌套引用的 PowerShell。 Base64 表示形式必须是 UTF-16 编码的字符串。

例如：

$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 平台上不存在 $env:PSExecutionPolicyPreference 环境变量。

-InputFormat |-in |-if

描述发送到 PowerShell 的数据的格式。有效值为“Text”（文本字符串）或“XML”（序列化 CLIXML 格式）。

-Interactive |-i

向用户显示交互式提示。 NonInteractive 参数的反函数。

-NoExit |-noe

运行启动命令后不会退出。

示例：pwsh -NoExit -Command Get-Date

-NoLogo |-nol

在交互式会话启动时隐藏版权横幅。

-NonInteractive |-noni

不向用户显示交互式提示。任何尝试使用交互式功能（如 Read-Host 或确认提示）都会导致语句终止错误。

-NoProfile |-nop

不加载 PowerShell 配置文件。

-OutputFormat |-o |-of

确定 PowerShell 的输出的格式。有效值为“Text”（文本字符串）或“XML”（序列化 CLIXML 格式）。

示例：pwsh -o XML -c Get-Date

使用 PowerShell 会话调用时，你会获得反序列化的对象作为输出而不是纯字符串。从其他 shell 调用时，输出是格式化为 CLIXML 文本的字符串数据。

-SettingsFile |-settings

替代会话的系统范围的 powershell.config.json 设置文件。默认情况下，系统范围的设置从 $PSHOME 目录中的 powershell.config.json 读取。

请注意，-ConfigurationName 参数指定的终结点不使用这些设置。

示例：pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode |-sshs

在 sshd_config 中用于将 PowerShell 作为 SSH 子系统运行。它不用于任何其他用途或不受支持。

-Version |-v

显示 PowerShell 的版本。将忽略其他参数。

-WindowStyle |-w

设置会话的窗口样式。有效值为 Normal、Minimized、Maximized 和 Hidden。

-WorkingDirectory |-wd

通过在启动时执行来设置初始工作目录。支持任何有效的 PowerShell 文件路径。

若要在主目录中启动 PowerShell，请使用：pwsh -WorkingDirectory ~

-帮助-？/？

显示有关 pwsh的帮助。如果要在 PowerShell 中键入 pwsh 命令，请使用连字符（-），而不是正斜杠（/）前面添加命令参数。

通过