about_Pwsh

  • Artigo

Descrição breve

Explica como usar o pwsh comando-line interface. Exibe o comando-line parameters e descreve a sintaxe.

Descrição longa

Para obter informações sobre as opções de ine de comando-lpara o Windows PowerShell 5.1, consulte about_PowerShell_exe.

Sintaxe

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <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 criadas pelo script estejam disponíveis na nova sessão. Insira o caminho do arquivo do script e quaisquer parâmetros. File deve ser o último parâmetro no comando, porque todos os caracteres digitados após o nome do parâmetro File são interpretados como o caminho de arquivo do script seguido pelos parâmetros do 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 booleano para um parâmetro de opção. Para fornecer um valor booleano para um parâmetro de opção 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 e cmd.exe 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 , já que lá ele é interpretado como código do PowerShell.

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

Observação

O parâmetro File não pode oferecer suporte a scripts usando 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 cadeia de caracteres.

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 do , -Commandquando 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á lançado. Esse comportamento é específico do Windows. Em outras plataformas, o PowerShell tenta executar outros tipos de arquivo.

-Command | -c

Executa os comandos especificados (e quaisquer parâmetros) como se 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 cadeia de caracteres. Se o valor de Command for -, o texto do comando será lido a partir da entrada padrão.

O parâmetro Command só aceita um bloco de script para execução quando ele pode reconhecer o valor passado para Command como um tipo ScriptBlock . Isso só é possível ao executar a partir pwsh de 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 incluído em 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 digitasse 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 de bloco de script geralmente não são necessárias em primeiro lugar ao executar a partir do cmd.exe. Para executar um bloco de script embutido definido em uma cadeia de caracteres, o operador de chamada& pode ser usado:

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

Se o valor de Command for uma cadeia de caracteres, Command deverá ser o último parâmetro para pwsh, pois todos os argumentos a seguir 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 cadeias de caracteres.

Se o valor de Command for -, o texto do comando será lido a partir da entrada padrão. Você deve redirecionar a entrada padrão ao usar o parâmetro Command com a 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 defina explicitamente um código de saída diferente de 0 ou 1, esse código de saída será convertido em 1 para o código de saída do processo. Para preservar o código de saída específico, adicione exit $LASTEXITCODE à sua cadeia de caracteres de comando ou 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 (término de espaço de execução), como um ou , ou quando a throw execução é interrompida com Ctrl+C.-ErrorAction Stop

-ConfigurationName | -config

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

Exemplo: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

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 em 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 Base64-ede um comando. Use esse parâmetro para enviar comandos ao PowerShell que exijam cotações 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 diretiva de execução padrão para a sessão atual e a salva na $env:PSExecutionPolicyPreference variável de ambiente. Esse parâmetro não altera as diretivas de execução configuradas persistentemente.

Esse parâmetro só se aplica a computadores Windows. Em plataformas que não sejam 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 NonInteractive.

-Login | -l

No Linux e macOS, inicia o PowerShell como um shell de login, usando /bin/sh para executar perfis de login 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. Esse parâmetro será 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, esta entrada será adicionada automaticamente no momento da instalação
    • Se pwsh não estiver presente no /etc/shells, use um editor para anexar o caminho à pwsh última linha. Isso requer privilégios elevados para editar.

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

    chsh -s /usr/bin/pwsh

Aviso

A configuração pwsh como shell de login não é suportada atualmente no Windows Subsystem for Linux (WSL) e a tentativa de definir pwsh como o shell de login lá pode levar à impossibilidade de iniciar o WSL interativamente.

-MTA

Inicie o PowerShell usando um apartamento multi-thread. Essa opção só está disponível no Windows. Usar esse parâmetro em plataformas que não sejam 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 de sessões interativas.

-NonInteractive | -noni

Essa opção é usada para criar sessões que não devem exigir a 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 ou 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 de 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 de saída em vez de cadeias de caracteres simples. Quando chamada de outros shells, a saída é dados de cadeia de caracteres 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 configurações do ide do sistema-wsão lidas a $PSHOME partir do powershell.config.json no 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 é suportado para qualquer outro uso.

-STA

Inicie o PowerShell usando um apartamento de thread único. Esse é o padrão. Essa opção só está disponível na plataforma Windows. Usar esse parâmetro em plataformas que não sejam 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 só se aplica ao Windows. Usar esse parâmetro em plataformas que não sejam Windows resulta em um erro.

-WorkingDirectory | -wd-w|o

Define o diretório de trabalho inicial executando na inicialização. Qualquer caminho de arquivo válido do PowerShell é suportado.

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

-Help, -?, /?

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