Partilhar via

about_Pwsh

  • Artigo

Breve descrição

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

Descrição longa

Para obter informações sobre as opções de entrada 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>] } ]
    [[-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 não diferenciam maiúsculas de minúsculas-i.

-File | -f

O valor de File pode ser - ou um filepath e parâmetros opcionais. Se o valor de File for -, os comandos serão lidos a partir da entrada padrão.

Este é 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 quaisquer parâmetros. Arquivo 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 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 Get-Script.ps1 script: -File .\Get-Script.ps1 -All

Em casos raros, talvez seja necessário fornecer um valor booleano 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 strings literais, após interpretação pelo 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 que recebe 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 da 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 a partir de um script em lote, você usaria %~dp0 em vez de .\ ou $PSScriptRoot para representar o diretório de execução atual: pwsh -File %~dp0test.ps1 -TestParam %windir%. Se você usar .\test.ps1 em vez disso, o PowerShell lançará um erro porque não consegue encontrar o caminho literal .\test.ps1

Nota

O parâmetro File não pode suportar 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, então ele é passado como uma cadeia de caracteres.

Se o valor de File for -, os comandos serão lidos 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. Ao ler a partir da entrada padrão, as instruções de entrada são executadas uma instrução de cada vez, como se tivessem sido digitadas no prompt de comando do PowerShell. Se uma instrução não for analisada corretamente, ela não será executada. O código de saída do processo é determinado pelo status do último comando (executado) dentro da entrada. Com terminação normal, o código de saída é sempre 0. 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.

Semelhante ao -Command, quando ocorre um erro de terminação de script, o código de saída é definido como 1. No entanto, ao contrário -Commanddo , quando a execução é interrompida com Ctrl+C , o código de saída é 0. Para obter mais informações, consulte $LASTEXITCODE em about_Automatic_Variables.

Nota

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

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 pode reconhecer o valor passado para Command como um tipo ScriptBlock . Isso só é possível quando executado pwsh a partir 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 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 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 deve ser o último parâmetro para pwsh, porque 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 -, os comandos serão lidos 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"
'@ | pwsh -NoProfile -Command -

Este exemplo produz a seguinte saída:

in
hi there
out

Ao ler a entrada padrão, a entrada é analisada e executada uma instrução de cada vez, como se tivesse sido digitada no prompt de comando do PowerShell. Se o código de entrada não for analisado corretamente, a instrução não será executada. A menos que você use o -NoExit parâmetro, a sessão do PowerShell é encerrada quando não há mais entrada para ler a partir da entrada padrão.

O código de saída do processo é determinado pelo status do último comando (executado) dentro da entrada. 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 para código de saída do 1 processo. Da mesma forma, o valor 1 é retornado quando ocorre um erro de terminação de script (terminação de espaço de execução), como a throw ou -ErrorAction Stop, ou quando a execução é interrompida com Ctrl+C.

Para preservar o código de saída específico, adicione exit $LASTEXITCODE à sua cadeia de comando ou bloco de script. Para obter mais informações, consulte $LASTEXITCODE em about_Automatic_Variables.

-CommandWithArgs | -cwa

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

Executa um comando do PowerShell com argumentos. Ao contrário -Commanddo , este parâmetro preenche a $args variável built-in que pode ser usada pelo comando.

A primeira cadeia de caracteres é o comando. Cadeias de caracteres adicionais delimitadas por espaço em branco são os argumentos.

Por exemplo:

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

Este exemplo produz a seguinte saída:

arg: arg1
arg: arg2

Nota

A análise de argumentos com aspas faz com que o exemplo falhe se executado de cmd.exe ou powershell.exe. Para fugir desses, 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. Isso pode ser qualquer ponto de extremidade registrado na máquina local, incluindo os pontos de extremidade de comunicação remota 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 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 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 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 $env:PSExecutionPolicyPreference variável de ambiente. Este parâmetro não altera as políticas de execução configuradas persistentemente.

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

    • Este 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 até pwsh a ú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

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

-MTA

Inicie o PowerShell usando um apartamento multi-threaded. Esta 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 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 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 cadeias de caracteres de saída bastante 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 powershell.config.json do sistema-wpara a sessão. Por padrão, as $PSHOME configurações do sistema-wide são lidas a powershell.config.json partir do diretório 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. Não se destina nem é suportado para qualquer outra utilização.

-STA

Inicie o PowerShell usando um apartamento de thread único. Esta é a predefinição. Esta 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 deste executável do PowerShell. Parâmetros adicionais são ignorados.

-WindowStyle | -w

Define o estilo da janela para a sessão. Os valores válidos são Normal, Minimizado, Maximizado e Oculto. Este parâmetro aplica-se apenas 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 ajuda para pwsho . Se você estiver digitando um comando pwsh no PowerShell, insira os parâmetros do comando com um hífen (-), não uma barra (/).