about_PowerShell_exe

Descrição breve

Explica como usar a powershell.exe interface de linha de comando. Exibe os parâmetros de linha de comando e descreve a sintaxe.

Descrição longa

Para obter informações sobre as opções de linha de comando do PowerShell 7, consulte about_Pwsh.

SYNTAX

PowerShell[.exe]
    [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo]
    [-NoExit]
    [-Sta]
    [-Mta]
    [-NoProfile]
    [-NonInteractive]
    [-InputFormat {Text | XML}]
    [-OutputFormat {Text | XML}]
    [-WindowStyle <style>]
    [-EncodedArguments <Base64EncodedArguments>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-File - | <filePath> <args>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-Command - | { <script-block> [-args <arg-array>] }
                | { <string> [<CommandParameters>] } ]

PowerShell[.exe] -Help | -? | /?

Parâmetros

Todos os parâmetros não diferenciam maiúsculas de minúsculas.

-Arquivo - | <caminho do>< arquivoargumentos>

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

Se o valor de File for um caminho de arquivo, o script será 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 nessa nova sessão. Insira o caminho do arquivo de script e todos os parâmetros. File deve ser o último parâmetro no comando. Todos os valores digitados após o parâmetro File são interpretados como o caminho do arquivo de script e os parâmetros passados para esse script. Por exemplo: -File .\Get-Script.ps1 -Domain Central

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 booliano para um parâmetro. Não é possível passar um valor booliano explícito para um parâmetro switch ao executar um script dessa maneira. Essa limitação foi removida no PowerShell 6 (pwsh.exe).

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: powershell.exe -File .\test.ps1 -TestParam %windir%

Por outro lado, a execução powershell.exe -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ê usar .\test.ps1 em vez disso, o PowerShell gerará 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.

Se o valor de Arquivo for -, os comandos serão lidos a partir da entrada padrão. A execução powershell -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 entrada padrão, as instruções de entrada são executadas uma instrução por vez, como se tivessem sido digitadas no prompt de comando do PowerShell. Se uma instrução não for analisada corretamente, a instrução não será executada. O código de saída do processo é determinado pelo status do último comando (executado). Com a execução bem-sucedida, 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 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 Para obter mais informações, consulte $LASTEXITCODE em about_Automatic_Variables.

-Command

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 powershell.exe 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 powershell.exe.

powershell -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:

powershell.exe -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 -, 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 entrada padrão. Por exemplo:

@'
"in"

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

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

Esse exemplo gera a saída a seguir:

in
hi there
out

Ao ler a entrada padrão, a entrada é analisada e executada uma instrução por vez, como se tivessem sido digitadas 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 será encerrada quando não houver mais entrada para ler da entrada padrão.

O código de saída do processo é determinado pelo status do último comando (executado) na 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 1 código de saída do processo. 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.

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.

-Cadeia de caracteres ConfigurationName <>

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.

-Argumentos codificados <Base64Argumentos codificados>

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

-Comando <Codificado Base64Comando Codificado>

Aceita uma versão de cadeia de caracteres com codificação de base 64 de um comando. Use esse parâmetro para enviar comandos ao PowerShell que exigem aspas ou chaves complexas. A cadeia de caracteres deve ser formatada usando a codificação de caracteres UTF-16LE.

-ExecutionPolicy <ExecutionPolicy>

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 a política de execução do PowerShell definida no registro. Para saber mais sobre as políticas de execução do PowerShell, inclusive uma lista de valores válidos, confira about_Execution_Policies.

-InputFormat {Text | XML}

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

-Mta

Inicia o PowerShell usando um multi-threaded apartment. Este parâmetro é introduzido no PowerShell 3.0. No PowerShell 2.0, o MTA (Multi-Threaded Apartment) é o padrão. No PowerShell 3.0, o STA (Single-Threaded Apartment) é o padrão.

-NoExit

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

-NonInteractive

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.

-NoLogo

Oculta a faixa de direitos autorais na inicialização.

-NoProfile

Não carrega o perfil do PowerShell.

-OutputFormat {Text | XML}

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

-PSConsoleFile <Caminho do arquivo>

Carrega o arquivo de console do PowerShell especificado. Insira o caminho e o nome do arquivo de console. Para criar um arquivo de console, use o cmdlet Export-Console no PowerShell.

-Sta

Inicia o PowerShell usando um single-threaded apartment. No Windows PowerShell 2.0, o MTA (Multi-Threaded Apartment) é o padrão. No Windows PowerShell 3.0, o STA (Single-Threaded Apartment) é o padrão.

-Versão <Versão do PowerShell>

Inicia a versão especificada do PowerShell. Os valores válidos são 2.0 e 3.0. A versão que você especificar deve estar instalada no sistema. Se o Windows PowerShell 3.0 estiver instalado no computador, "3.0" será a versão padrão. Caso contrário, "2.0" é a versão padrão. Para obter mais informações, consulte Instalar o PowerShell.

-WindowStyle <Estilo da janela>

Define o estilo da janela da sessão. Os valores válidos são Normal, Minimized, Maximized e Hidden.

-Help, -?, /?

Exibe ajuda para PowerShell.exe. Se você estiver digitando um PowerShell.exe comando em uma sessão do PowerShell, anexe os parâmetros de comando com um hífen (-), não uma barra (/). Você pode usar um hífen ou uma barra em cmd.exe.

COMENTÁRIOS

Observação de solução de problemas: no PowerShell 2.0, a inicialização de alguns programas no console do PowerShell falha com um LastExitCode de 0xc0000142.

EXEMPLOS

# Create a new PowerShell session and load a saved console file
PowerShell -PSConsoleFile sqlsnapin.psc1

# Create a new PowerShell V2 session with text input, XML output, and no logo
PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML

# Execute a PowerShell Command in a session
PowerShell -Command "Get-EventLog -LogName security"

# Run a script block in a session
PowerShell -Command {Get-EventLog -LogName security}

# An alternate way to run a command in a new session
PowerShell -Command "& {Get-EventLog -LogName security}"

# To use the -EncodedCommand parameter:
$command = "dir 'c:\program files' "
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
powershell.exe -encodedCommand $encodedCommand