Compartilhar via

about_Pwsh

  • Artigo

Descrição breve

Explica como usar o pwsh comando-line interface. Exibe os parâmetros do comando-line e descreve a sintaxe.

Descrição longa

Para obter informações sobre as opções de comando-line para Windows PowerShell 5.1, consulte about_PowerShell_exe.

Sintaxe

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 | -? | /?

Parâmetros

Todos os parâmetros diferenciam maiúsculas de minúsculas-i.

-File | -f

Se o valor de for -, o texto do File comando será lido a partir da entrada padrão. A execução pwsh -File - sem entrada padrão redirecionada inicia uma sessão regular. Isso é o mesmo que não especificar o File parâmetro.

Esse é o parâmetro padrão se nenhum parâmetro estiver presente, mas os valores estiverem presentes na linha de comando. O script especificado é executado no escopo local ("dot-sourced") da nova sessão, para que as funções e variáveis que o script cria estejam disponíveis na nova sessão. Insira o caminho do arquivo de script e todos os parâmetros. File deve ser o último parâmetro no comando, pois todos os caracteres digitados após o nome do parâmetro File são interpretados como o caminho do arquivo de script seguido pelos parâmetros de script.

Normalmente, os parâmetros de opção de um script são incluídos ou omitidos. Por exemplo, o comando a seguir usa o parâmetro All do arquivo de script Get-Script.ps1: -File .\Get-Script.ps1 -All

Em casos raros, talvez seja necessário fornecer um valor booliano para um parâmetro switch. Para fornecer um valor booleano para um parâmetro switch no valor do parâmetro File , use o parâmetro normalmente seguido imediatamente por dois-pontos e o valor booleano, como o seguinte: -File .\Get-Script.ps1 -All:$False.

Os parâmetros passados para o script são passados como cadeias de caracteres literais (após a interpretação do shell atual). Por exemplo, se você estiver dentro cmd.exe e quiser passar um valor de variável de ambiente, use a cmd.exe sintaxe: pwsh -File .\test.ps1 -TestParam %windir%

Por outro lado, a execução pwsh -File .\test.ps1 -TestParam $env:windir resulta no cmd.exe script recebendo a cadeia de caracteres $env:windir literal porque ela não tem nenhum significado especial para o shell atual cmd.exe . O $env:windir estilo de referência de variável de ambiente pode ser usado dentro de um parâmetro Command , pois ele é interpretado como código do PowerShell.

Da mesma forma, se você quiser executar o mesmo comando de um script do Lote, use %~dp0 em vez de ou $PSScriptRoot para representar o diretório de .\ execução atual: pwsh -File %~dp0test.ps1 -TestParam %windir%. Se você usasse .\test.ps1, o PowerShell geraria um erro porque não consegue encontrar o caminho literal .\test.ps1

Observação

O parâmetro File não pode dar suporte a scripts que usam um parâmetro que espera uma matriz de valores de argumento. Isso, infelizmente, é uma limitação de como um comando nativo obtém valores de argumento. Quando você chama um executável nativo (como powershell ou pwsh), ele não sabe o que fazer com uma matriz, portanto, é passado como uma string.

Quando o arquivo de script termina com um exit comando, o código de saída do processo é definido como o argumento numérico usado com o exit comando. Com a terminação normal, o código de saída é sempre 0.

Para obter mais informações, consulte $LASTEXITCODE em about_Automatic_Variables.

Semelhante ao -Command, quando ocorre um erro de encerramento de script, o código de saída é definido como 1. No entanto, ao contrário -Commandde , quando a execução é interrompida com Ctrl+C, o código de saída é .0

Observação

A partir do PowerShell 7.2, o parâmetro File só aceita .ps1 arquivos no Windows. Se outro tipo de arquivo for fornecido, um erro será gerado. Esse comportamento é específico do Windows. Em outras plataformas, o PowerShell tenta executar outros tipos de arquivo.

-Command | -c

Executa os comandos especificados (e todos os parâmetros) como se eles tivessem sido digitados no prompt de comando do PowerShell e, em seguida, sai, a menos que o NoExit parâmetro seja especificado.

O valor de Command pode ser -, um bloco de script ou uma string. Se o valor de Command for -, o texto do comando será lido da entrada padrão.

O parâmetro Command só aceita um bloco de script para execução quando pode reconhecer o valor passado para Command como um tipo ScriptBlock . Isso só é possível ao executar pwsh em outro host do PowerShell. O tipo ScriptBlock pode estar contido em uma variável existente, retornado de uma expressão ou analisado pelo host do PowerShell como um bloco de script literal entre chaves ({}), antes de ser passado para pwsh.

pwsh -Command {Get-WinEvent -LogName security}

No cmd.exe, não existe um bloco de script (ou tipo ScriptBlock ), portanto, o valor passado para Command é sempre uma cadeia de caracteres. Você pode escrever um bloco de script dentro da cadeia de caracteres, mas em vez de ser executado, ele se comporta exatamente como se você o tivesse digitado em um prompt típico do PowerShell, imprimindo o conteúdo do bloco de script de volta para você.

Uma cadeia de caracteres passada para Command ainda é executada como código do PowerShell, portanto, as chaves do bloco de script geralmente não são necessárias em primeiro lugar ao executar a partir de cmd.exe. Para executar um bloco de script embutido definido dentro de uma cadeia de caracteres, o operador & de chamada pode ser usado:

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

Se o valor de Command for uma string, Command deverá ser o último parâmetro para pwsh, pois todos os argumentos que o seguem são interpretados como parte do comando a ser executado.

Quando chamados de dentro de uma sessão existente do PowerShell, os resultados são retornados ao shell pai como objetos XML desserializados, não objetos dinâmicos. Para outros shells, os resultados são retornados como strings.

Se o valor de Command for -, o texto do comando será lido da entrada padrão. Você deve redirecionar a entrada padrão ao usar o parâmetro Command com entrada padrão. Por exemplo:

@'
"in"

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

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

Esse exemplo gera a saída a seguir:

in
hi there
out

O código de saída do processo é determinado pelo status do último comando (executado) dentro do bloco de script. O código de saída é 0 quando $? é $true ou 1 quando $? é $false. Se o último comando for um programa externo ou um script do PowerShell que define explicitamente um código de saída diferente de 0 ou 1, esse código de saída será convertido em 1 código de saída do processo. Para preservar o código de saída específico, adicione exit $LASTEXITCODE à cadeia de caracteres de comando ou ao bloco de script.

Para obter mais informações, consulte $LASTEXITCODE em about_Automatic_Variables.

Da mesma forma, o valor 1 é retornado quando ocorre um erro de encerramento de script (encerramento de runspace), como um throw ou -ErrorAction Stop, ou quando a execução é interrompida com Ctrl+C.

-CommandWithArgs | -cwa

Este é um recurso experimental adicionado na versão 7.4.

Executa um comando do PowerShell com argumentos. Ao contrário -Commanddo , esse parâmetro preenche a $args variável n construída-ique pode ser usada pelo comando.

A primeira string é o comando. Strings adicionais delimitadas por espaços em branco são os argumentos.

Por exemplo:

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

Esse exemplo gera a saída a seguir:

arg: arg1
arg: arg2

Observação

A análise de argumentos com aspas faz com que o exemplo falhe se executado de cmd.exe ou powershell.exe. Para fugir deles, você pode usar

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

-ConfigurationName | -config

Especifica um ponto de extremidade de configuração no qual o PowerShell é executado. Pode ser qualquer ponto de extremidade registrado no computador local, incluindo os pontos de extremidade de comunicação remota padrão do PowerShell ou um ponto de extremidade personalizado com recursos de função de usuário específicos.

Exemplo: pwsh -ConfigurationName AdminRoles

-Arquivo de configuração

Especifica um caminho de arquivo de configuração de sessão (.pssc). A configuração contida no arquivo de configuração será aplicada à sessão do PowerShell.

Exemplo: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

Especifica o nome a ser usado para um servidor IPC adicional (pipe nomeado) usado para depuração e outras comunicações entre processos. Isso oferece um mecanismo previsível para se conectar a outras instâncias do PowerShell. Normalmente usado com o parâmetro CustomPipeName no Enter-PSHostProcess.

Esse parâmetro foi introduzido no PowerShell 6.2.

Por exemplo:

# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe

-EncodedCommand | -e | -ec

Aceita uma versão de cadeia de caracteres codificada em Base64-ede um comando. Use esse parâmetro para enviar comandos ao PowerShell que exigem aspas complexas e aninhadas. A representação Base64 deve ser uma cadeia de caracteres codificada em UTF-16LE.

Por exemplo:

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

-ExecutionPolicy | -ex | -ep

Define a política de execução padrão para a sessão atual e a salva na variável de $env:PSExecutionPolicyPreference ambiente. Esse parâmetro não altera as políticas de execução configuradas persistentemente.

Este parâmetro se aplica apenas a computadores Windows. Em plataformas não Windows, o parâmetro e o valor fornecidos são ignorados.

-InputFormat | -inp | -if

Descreve o formato dos dados enviados ao PowerShell. Os valores válidos são "Text" (cadeias de caracteres de texto) ou "XML" (formato CLIXML serializado).

-Interactive | -i

Apresente um prompt interativo ao usuário. Inverso para o parâmetro NonInteraction.

-Login | -l

No Linux e no macOS, inicia o PowerShell como um shell de logon, usando /bin/sh para executar perfis de logon, como /etc/profile e ~/.profile. No Windows, essa opção não faz nada.

Importante

Esse parâmetro deve vir primeiro para iniciar o PowerShell como um shell de logon. Este parâmetro é ignorado se for passado em outra posição.

Para configurar pwsh como o shell de login em sistemas operacionais UNIX-like:

  • Verifique se o caminho absoluto completo para pwsh está listado em /etc/shells

    • Esse caminho geralmente é algo como /usr/bin/pwsh no Linux ou /usr/local/bin/pwsh no macOS
    • Com alguns métodos de instalação, essa entrada será adicionada automaticamente no momento da instalação
    • Se pwsh não estiver presente no /etc/shells, use um editor para acrescentar o caminho para pwsh na última linha. Isso requer privilégios elevados para editar.

  • Use o utilitário chsh para definir o shell do usuário atual como pwsh:

    chsh -s /usr/bin/pwsh

Aviso

No momento, não há suporte para a configuração pwsh como o shell de logon no WSL (Subsistema do Windows para Linux) e a tentativa de definir pwsh como o shell de logon pode levar à impossibilidade de iniciar o WSL interativamente.

-MTA

Inicie o PowerShell usando um apartamento multithread. Essa opção está disponível apenas no Windows. Usar esse parâmetro em plataformas não Windows resulta em um erro.

-NoExit | -noe

Não sai depois de executar comandos de inicialização.

Exemplo: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Oculta o banner na inicialização das sessões interativas.

-NonInteractive | -noni

Essa opção é usada para criar sessões que não devem exigir entrada do usuário. Isso é útil para scripts executados em tarefas agendadas ou pipelines de CI/CD. Qualquer tentativa de usar recursos interativos, como Read-Host prompts de confirmação, resulta em erros de encerramento de instrução em vez de travamento.

-NoProfile | -nop

Não carrega os perfis do PowerShell.

-NoProfileTempo de carregamento

Oculta o texto do tempo de carregamento do perfil do PowerShell mostrado na inicialização quando o tempo de carregamento excede 500 milissegundos.

-OutputFormat | -o | -of

Determina como a saída do PowerShell é formatada. Os valores válidos são "Text" (cadeias de caracteres de texto) ou "XML" (formato CLIXML serializado).

Exemplo: pwsh -o XML -c Get-Date

Quando chamado em uma sessão do PowerShell, você obtém objetos desserializados como cadeias de caracteres simples de saída. Quando chamada de outros shells, a saída é dados de sequência formatados como texto CLIXML.

-SettingsFile | -settings

Substitui o arquivo de configurações do ide do powershell.config.json sistema-wpara a sessão. Por padrão, as powershell.config.json configurações do ide do sistema-wsão lidas no $PSHOME diretório.

Observe que essas configurações não são usadas pelo ponto de extremidade especificado pelo -ConfigurationName argumento.

Exemplo: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

Usado no sshd_config para executar o PowerShell como um subsistema SSH. Ele não se destina ou tem suporte para nenhum outro uso.

-STA

Inicie o PowerShell usando um apartamento de thread único. Esse é o padrão. Essa opção está disponível apenas na plataforma Windows. Usar esse parâmetro em plataformas não Windows resulta em um erro.

-Version | -v

Exibe a versão do PowerShell. Parâmetros adicionais são ignorados.

-WindowStyle | -w

Define o estilo da janela da sessão. Os valores válidos são Normal, Minimized, Maximized e Hidden. Esse parâmetro se aplica apenas ao Windows. Usar esse parâmetro em plataformas não Windows resulta em um erro.

-WorkingDirectory | -wd | -wo

Define o diretório de trabalho inicial executando na inicialização. Há suporte para qualquer caminho de arquivo válido do PowerShell.

Para iniciar o PowerShell em seu diretório base, use: pwsh -WorkingDirectory ~

-Help, -?, /?

Exibe ajuda para pwsh. Se você estiver digitando um comando pwsh no PowerShell, anexe os parâmetros de comando com um hífen (-), não uma barra (/).