about_Pwsh

  • Статья

Краткое описание

Объясняет, как использовать pwsh интерфейс ine команды-l. Отображает команду-line и описывает синтаксис.

Подробное описание

Сведения о параметрах команд-line для 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 | -? | /?

Параметры

Все параметры являются нечувствительными к регистру-i.

-File | -f

Если значение равно-, текст команды считывается из стандартных File входных данных. Выполнение pwsh -File - без перенаправленных стандартных входных данных запускает обычный сеанс. Это то же самое, что и не указание File параметра вообще.

Это параметр по умолчанию, если параметры отсутствуют, но значения присутствуют в командной строке. Указанный скрипт выполняется в локальном область ("dot-sourced") нового сеанса, чтобы функции и переменные, создаваемые скриптом, были доступны в новом сеансе. Введите путь к файлу скрипта и все параметры. Файл должен быть последним параметром в команде, так как все символы, введенные после имени параметра файла, интерпретируются как файловый путь скрипта, за которым следуют параметры скрипта.

Обычно параметры-переключатели сценария включаются или опускаются. Например, следующая команда использует параметр All файла скрипта Get-Script.ps1: -File .\Get-Script.ps1 -All

В редких случаях может потребоваться указать логическое значение параметра switch. Чтобы указать логическое значение для параметра switch в значении параметра File, используйте параметр, который обычно следует за двоеточием и логическим значением, например следующим: -File .\Get-Script.ps1 -All:$False

Передаваемые в скрипт параметры имеют вид строк литералов (после интерпретации текущей оболочкой). Например, если вы находитесь cmd.exe и хотите передать значение переменной среды, используйте cmd.exe синтаксис: pwsh -File .\test.ps1 -TestParam %windir%

В отличие от этого, выполнение pwsh -File .\test.ps1 -TestParam $env:windircmd.exe в результате в скрипте получает литеральную строку $env:windir , так как она не имеет особого значения для текущей cmd.exe оболочки. Стиль $env:windir ссылки на переменную среды можно использовать внутри параметра Command , так как он интерпретируется как код PowerShell.

Аналогичным образом, если вы хотите выполнить ту же команду из скрипта пакетной службы, вы будете использовать %~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 параметр File принимает .ps1 только файлы в Windows. Если указан другой тип файла, возникает ошибка. Это поведение зависит от Windows. На других платформах PowerShell пытается запустить другие типы файлов.

-Command | -c

Выполняет указанные команды (и все параметры), как будто они были вводимы в командной строке PowerShell, а затем завершает работу, если NoExit параметр не указан.

Значение команды может быть-, блок скрипта или строка. Если значение команды равно -, текст команды считывается из стандартных входных данных.

Параметр Command принимает только блок скрипта для выполнения, если он может распознать значение, переданное команде в качестве типа ScriptBlock . Это возможно только при запуске pwsh из другого узла PowerShell. Тип ScriptBlock может содержаться в существующей переменной, возвращаемой из выражения, или анализироваться узлом PowerShell как блок литерального скрипта, заключенный в фигурные скобки ({}), перед передачей в pwsh.

pwsh -Command {Get-WinEvent -LogName security}

В cmd.exeней отсутствует такая вещь, как блок скрипта (или тип ScriptBlock), поэтому значение, переданное команде, всегда является строкой. Вы можете написать блок скрипта внутри строки, но вместо выполнения он ведет себя точно так же, как если бы вы ввели его в типичном запросе PowerShell, распечатав содержимое блока скрипта обратно.

Строка, передаваемая команде , по-прежнему выполняется как код PowerShell, поэтому блок скрипта фигурные скобки часто не требуются в первую очередь при запуске из cmd.exe. Для выполнения встроенного блока сценария, определенного внутри строки, можно использовать оператор вызова&.

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

Если значение команды является строкой, команда должна быть последним параметром pwsh, так как все аргументы после него интерпретируются как часть выполняемой команды.

При вызове из существующего сеанса PowerShell результаты возвращаются в родительскую оболочку как десериализированные XML-объекты, а не динамические объекты. Для других оболочки результаты возвращаются в виде строк.

Если значение команды равно -, текст команды считывается из стандартных входных данных. При использовании параметра command с стандартными входными данными необходимо перенаправить стандартные входные данные. Например:

@'
"in"

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

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

В примере получается следующий вывод.

in
hi there
out

Код выхода процесса определяется состоянием последней (выполненной) команды в блоке скрипта. Код выхода находится 0 в том случае, если $? это $true или 1 когда $? есть $false. Если последняя команда является внешней программой или скриптом PowerShell, который явно задает код выхода, отличный 0 от или 1, этот код выхода преобразуется в 1 код выхода процесса. Чтобы сохранить конкретный код выхода, добавьте exit $LASTEXITCODE в командную строку или блок скрипта.

Дополнительные сведения см $LASTEXITCODE . в about_Automatic_Variables.

Аналогичным образом, значение 1 возвращается при ошибке завершения скрипта (завершающегося пространством выполнения), например или throw-ErrorAction Stopпри прерывании выполнения с помощью CTRL+C.

-CommandWithArgs | -cWa

Это экспериментальная функция, добавленная в версии 7.4.

Выполняет команду PowerShell с аргументами. В отличие от -Commandэтого параметра, этот параметр заполняет встроенную $args-iпеременную n, которую можно использовать командой.

Первая строка — это команда. Дополнительные строки, разделенные пробелами, являются аргументами.

Например:

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. Обычно используется с параметром CustomPipeName в Enter-PSHostProcess.

Этот параметр появился в 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 в качестве оболочки входа, используя /bin/sh для выполнения профилей входа, таких как /etc/profile и ~/.profile. В Windows этот переключатель ничего не делает.

Внимание

Этот параметр должен быть первым, чтобы запустить PowerShell в качестве оболочки входа. Этот параметр игнорируется, если он передается в другой позиции.

Чтобы настроить pwsh в качестве оболочки входа в операционных системах ike UNIX-l:

  • Убедитесь, что полный абсолютный путь pwsh указан в списке /etc/shells

    • Обычно этот путь похож /usr/bin/pwsh на Linux или /usr/local/bin/pwsh macOS
    • При использовании некоторых методов установки эта запись будет добавлена автоматически во время установки.
    • Если pwsh в ней нет /etc/shells, используйте редактор, чтобы добавить путь к pwsh последней строке. Для этого требуются повышенные привилегии для редактирования.

  • Используйте служебную программу chsh , чтобы задать для текущего пользователя значение pwsh:

    chsh -s /usr/bin/pwsh

Предупреждение

Если pwsh в настоящее время оболочка входа не поддерживается в подсистема Windows для Linux (WSL), и попытка задать pwsh ее в качестве оболочки входа может привести к тому, что не удается запустить WSL в интерактивном режиме.

-MTA

Запустите PowerShell с помощью многопоточных квартир. Этот параметр доступен только в Windows. Использование этого параметра на платформах, отличных от Windows, приводит к ошибке.

-NoExit | -noe

Не завершает работу после выполнения команд запуска.

Пример: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Скрывает баннер при запуске интерактивных сеансов.

-NonInteractive | -noni

Этот параметр используется для создания сеансов, которые не должны требовать ввода пользователем. Это полезно для сценариев, выполняемых в запланированных задачах или конвейерах CI/CD. Любые попытки использовать интерактивные функции, такие как Read-Host или запросы подтверждения, приводят к прекращению ошибок инструкции, а не зависания.

-NoProfile | -nop

Не загружает профили PowerShell.

-NoProfileLoadTime

Скрывает текст времени загрузки профиля PowerShell, отображаемый при запуске, когда время загрузки превышает 500 миллисекунда.

-OutputFormat | -o | -of

Определяет формат выходных данных PowerShell. Допустимые значения: "Text" (текстовые строки) или "XML" (сериализованный формат CLIXML).

Пример: pwsh -o XML -c Get-Date

При вызове в сеансе PowerShell вы получаете десериализированные объекты в виде выходных данных, а не простых строк. При вызове из других оболочки выходные данные форматируются как текст CLIXML.

-SettingsFile | -settings

Переопределяет файл параметров ide powershell.config.json системы-wдля сеанса. По умолчанию параметры интегрированной среды-wразработки системы считываются из $PSHOMEpowershell.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 Если вы вводите команду pwsh в PowerShell, предустановите параметры команды с дефисом (-), а не косой чертой (/).