关于普沃什

简短描述

解释如何使用 pwsh 命令行界面。显示命令行参数并描述语法。

详细描述

有关 Windows PowerShell 5.1 命令行选项的信息，请参阅 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 | -? | /?

参数

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

-文件| -f

File 的值可以是 - 或文件路径和可选参数。如果File的值为-，则从标准输入读取命令。

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

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

在极少数情况下，您可能需要为开关参数提供布尔值。要为 File 参数值中的开关参数提供 Boolean 值，请使用通常紧跟冒号和布尔值的参数，如下所示： -文件.\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 代码。

同样，如果您想从批处理脚本执行相同的命令，则可以使用 %~dp0 而不是 .\ 或 $PSScriptRoot 表示当前执行目录：pwsh -File %~dp0test.ps1 -TestParam %windir%。如果您改用 .\test.ps1，PowerShell 会抛出错误，因为它找不到文字路径 .\test.ps1

笔记

File 参数不支持使用需要参数值数组的参数的脚本。不幸的是，这限制了本机命令获取参数值的方式。当您调用本机可执行文件（例如 powershell 或 pwsh）时，它不知道如何处理数组，因此它作为字符串传递。

如果File的值为-，则从标准输入读取命令。在不重定向标准输入的情况下运行 pwsh -File - 会启动常规会话。这与根本不指定 File 参数相同。从标准输入读取时，输入语句一次执行一个语句，就像在 PowerShell 命令提示符下键入它们一样。如果语句无法正确解析，则不会执行该语句。进程退出代码由输入中最后一个（执行的）命令的状态确定。正常终止时，退出代码始终为 0。当脚本文件通过 exit 命令终止时，进程退出代码将设置为与 exit 命令一起使用的数字参数。

与 -Command 类似，当发生脚本终止错误时，退出代码设置为 1。但是，与 -Command 不同，当使用 Ctrl+C 中断执行时，退出代码为 0。有关详细信息，请参阅 about_Automatic_Variables 中的 $LASTEXITCODE。

笔记

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

-命令| -c

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

仅当 Command 参数可以将传递给 Command 的值识别为 ScriptBlock 类型时，Command 参数才接受执行脚本块。这仅在从另一个 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"
'@ | pwsh -NoProfile -Command -

此示例产生以下输出：

in
hi there
out

从标准输入读取时，输入会被解析并一次执行一个语句，就像在 PowerShell 命令提示符下键入它们一样。如果输入代码无法正确解析，则不会执行该语句。除非您使用 -NoExit 参数，否则当没有更多输入可从标准输入读取时，PowerShell 会话将退出。

进程退出代码由输入中最后一个（执行的）命令的状态确定。当 $? 为 $true 时，退出代码为 0；当 $? 时，退出代码为 1 > 是$false。如果最后一个命令是显式设置除 0 或 1 之外的退出代码的外部程序或 PowerShell 脚本，则该退出代码将转换为 1 进程退出代码。同样，当发生脚本终止（运行空间终止）错误（例如 throw 或 -ErrorAction Stop）或使用 中断执行时，将返回值 1 kbd>Ctrl+C。

要保留特定的退出代码，请将 exit $LASTEXITCODE 添加到命令字符串或脚本块中。有关详细信息，请参阅 about_Automatic_Variables 中的 $LASTEXITCODE。

-CommandWithArgs | -cwa

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

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

第一个字符串是命令。由空格分隔的附加字符串是参数。

例如：

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

此示例产生以下输出：

arg: arg1
arg: arg2

笔记

如果从 cmd.exe 或 powershell.exe 运行，带引号的参数解析会导致示例失败。要摆脱这些，你可以使用

REM Quoting required when run from cmd.exe
pwsh -CommandWithArgs "$args | % { ""arg: $_"" }" arg1 arg2

# Quoting required when run from powershell.exe
pwsh -CommandWithArgs '"$args | % { ""arg: $_"" }"' arg1 arg2

-配置名称 | -配置

指定运行 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

-编码命令| -e | -ec

接受命令的 Base64 编码字符串版本。使用此参数将需要复杂嵌套引用的命令提交到 PowerShell。 Base64 表示形式必须是 UTF-16LE 编码的字符串。

例如：

$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand

-执行政策| -前| -ep

设置当前会话的默认执行策略并将其保存在 $env:PSExecutionPolicyPreference 环境变量中。该参数不会改变持久配置的执行策略。

该参数仅适用于 Windows 计算机。在非 Windows 平台上，忽略提供的参数和值。

-输入格式| -inp | -如果

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

-互动| -我

向用户呈现交互式提示。非交互参数的反函数。

-登录 | -l

在 Linux 和 macOS 上，启动 PowerShell 作为登录 shell，使用 /bin/sh 执行登录配置文件，例如 /etc/profile 和 ~/.profile。在 Windows 上，此开关不执行任何操作。

这很重要

此参数必须首先出现才能将 PowerShell 作为登录 shell 启动。如果在其他位置传递该参数，则该参数将被忽略。

要将 pwsh 设置为类 UNIX 操作系统上的登录 shell：

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

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

chsh -s /usr/bin/pwsh

警告

Windows Subsystem for Linux (WSL) 目前不支持将 pwsh 设置为登录 shell，尝试将 pwsh 设置为登录 shell 可能会导致无法启动WSL 交互式。

-MTA

使用多线程单元启动 PowerShell。此开关仅在 Windows 上可用。在非 Windows 平台上使用此参数会导致错误。

-没有退出| -诺埃

运行启动命令后不退出。

示例：pwsh -NoExit -Command Get-Date

-无标志| -无

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

-非交互式| -诺丽果

此开关用于创建不需要用户输入的会话。这对于在计划任务或 CI/CD 管道中运行的脚本非常有用。任何使用交互功能（例如 Read-Host 或确认提示）的尝试都会导致语句终止错误而不是挂起。

-没有个人资料| -nop

不加载 PowerShell 配置文件。

-NoProfileLoadTime

当加载时间超过 500 毫秒时，隐藏启动时显示的 PowerShell 配置文件加载时间文本。

-输出格式| -o | -的

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

示例：pwsh -o XML -c 获取日期

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

-设置文件| -设置

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

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

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

-SSH服务器模式| -sshs

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

-STA

使用单线程单元启动 PowerShell。这是默认设置。此开关仅在 Windows 平台上可用。在非 Windows 平台上使用此参数会导致错误。

-版本| -v

显示 PowerShell 的版本。附加参数将被忽略。

- 窗口样式 | -w

设置会话的窗口样式。有效值为正常、最小化、最大化和隐藏。该参数仅适用于Windows。在非 Windows 平台上使用此参数会导致错误。

-工作目录| -wd | -沃

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

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

-帮助， -？， /？

显示 pwsh 的帮助。如果您在 PowerShell 中键入 pwsh 命令，请在命令参数前面添加连字符 (-)，而不是正斜杠 (/)。