about_Pwsh

  • 项目

简短说明

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

长说明

有关 Windows PowerShell 5.1 的命令-line 选项的信息，请参阅 about_PowerShell_exe。

语法

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <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 | -? | /?

parameters

所有参数均不区分大小写。

-File | -f

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

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

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

在极少数情况下，你可能需要为开关参数提供一个布尔值。 若要在 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。

有关详细信息，请参阅 about_Automatic_Variables 中的 $LASTEXITCODE。

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

注意

从 PowerShell 7.2 起，File 参数仅接受 Windows 上的 .ps1 文件。 如果提供了另一种文件类型，则会引发错误。 此行为特定于 Windows。 在其他平台上，PowerShell 会尝试运行其他文件类型。

-Command | -c

执行指定的命令（和所有参数），就像从 PowerShell 命令提示符下键入的命令一样，如果未指定 NoExit 参数，则随后退出。

Command 的值可以是“-”、脚本块或字符串。 如果 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 的值为“-”，则将从标准输入读取命令文本。 在将 Command 参数与标准输入配合使用时，必须重定向标准输入。 例如：

@'
"in"

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

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

该示例产生下面的输出：

in
hi there
out

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

有关详细信息，请参阅 about_Automatic_Variables 中的 $LASTEXITCODE。

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

-CommandWithArgs | -cwa

这是 7.4 中添加的实验性功能。

使用参数执行 PowerShell 命令。 与 -Command 不同，此参数填充可供命令使用的 $args 内置-i变量。

第一个字符串是命令。 用空格分隔的其他字符串是参数。

例如：

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

该示例产生下面的输出：

arg: arg1
arg: arg2

-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

接受命令的 Base-e64 编码字符串版本。 使用此参数将命令提交到需要复杂嵌套引用的 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 上，使用 /bin/sh 以登录 shell 的形式启动 PowerShell，以执行 /etc/profile 和 ~/.profile 等登录配置文件。 在 Windows 上，此开关不执行任何操作。

重要

此参数必须首先以登录 shell 的形式启动 PowerShell。 如果在另一位置传递此参数，则忽略此参数。

若要在类 UNIX 操作系统上将 pwsh 设置为登录 shell，请执行以下操作：

  • 验证 /etc/shells 下是否列出了 pwsh 的完整绝对路径

    • 此路径通常类似于 Linux 上的 /usr/bin/pwsh 或 macOS 上的 /usr/local/bin/pwsh
    • 使用某些安装方法时，将在安装时自动添加此项
    • 如果 /etc/shells 中不存在 pwsh，请使用编辑器将路径追加到最后一行上的 pwsh。 需要提升的权限才能编辑。

  • 使用 chsh 实用工具将当前用户的 shell 设置为 pwsh：

    chsh -s /usr/bin/pwsh

警告

将 pwsh 设置为 Linux 的 Windows 子系统 (WSL) 当前不支持登录 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 设置从 $PSHOME 目录中的 powershell.config.json 读取。

请注意，-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 命令，请以连字符 (-) 作为命令参数的前缀，不要使用正斜杠 (/)。