Compartilhar via

about_Pwsh

  • Artigo

Descrição breve

Explica como usar a interface de entrada de pwsh comando-l. Exibe os parâmetros de entrada de comando-le descreve a sintaxe.

Descrição longa

Para obter informações sobre as opções de entrada de comando-lpara 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 são case-insensitive.

-File | -f

Se o valor de File for -, o texto do comando será lido 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, de modo que as funções e variáveis que o script cria estejam disponíveis em em uma nova sessão. Insira o caminho do arquivo de script e todos os parâmetros. O arquivo 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 seguinte comando 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 booliano para um parâmetro switch no valor do parâmetro File , use o parâmetro normalmente seguido imediatamente por dois-pontos e o valor booliano, 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, usará a cmd.exe sintaxe : pwsh -File .\test.ps1 -TestParam %windir%

Por outro lado, a execução pwsh -File .\test.ps1 -TestParam $env:windir em cmd.exe resulta no script que recebe a cadeia de caracteres literal $env:windir porque 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ê usou .\test.ps1, o PowerShell gerará um erro porque ele não pode encontrar o caminho literal .\test.ps1

Observação

O parâmetro File não pode dar 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, ele é 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 o encerramento normal, o código de saída é sempre 0.

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

Semelhante a -Command, quando ocorre um erro de encerramento de script, o código de saída é definido como 1. No entanto, ao contrário de , -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 aceita .ps1 apenas 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 quaisquer parâmetros) como se fossem digitados no prompt de comando do PowerShell e, em seguida, é encerrado, 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 da entrada padrão.

O parâmetro Command aceita apenas 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 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 do bloco de script geralmente não são necessárias em primeiro lugar ao executar do 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 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 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 por 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 0 de ou 1, esse código de saída será convertido 1 para 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 um erro de terminação de script (runspace-terminating), como um throw ou -ErrorAction Stop, ocorre ou quando a execução é interrompida com Ctrl+C.

-ConfigurationName | -config

Especifica um ponto de extremidade de configuração no qual o PowerShell é executado. Esse 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 funcionalidades de função de usuário específicas.

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 outra comunicação 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 ncode de 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.

Esse parâmetro só se aplica a computadores Windows. Em plataformas não Windows, o parâmetro e o valor fornecido 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 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. Esse parâmetro será ignorado se ele for passado em outra posição.

Para configurar pwsh como o shell de logon 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 edição.

  • 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 tentar definir pwsh como o shell de logon pode levar a não conseguir iniciar o WSL interativamente.

-MTA

Inicie o PowerShell usando um apartment multi-threaded. Essa opção só está disponível 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 a faixa na inicialização de 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 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.

-NoProfileLoadTime

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 dentro de uma sessão do PowerShell, você obtém objetos desserializados como saída, em vez de cadeias de caracteres simples. Quando chamado de outros shells, a saída são dados de cadeia de caracteres formatados como texto CLIXML.

-SettingsFile | -settings

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

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 em sshd_config para executar o PowerShell como um subsistema SSH. Ele não é pretendido nem tem suporte para qualquer outro uso.

-STA

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

-WorkingDirectory | -wd-w|o

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 no diretório base, use: pwsh -WorkingDirectory ~

-Help, -?, /?

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