about_PowerShell_exe

  • Artigo

Descrição breve

Explica como usar a interface de powershell.exe 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

-Command

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 powershell.exe 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 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 será uma cadeia de caracteres. Você pode escrever um bloco de script dentro da cadeia de caracteres, mas em vez de ser executado, ele se comportará exatamente como se tivesse sido digitado em um prompt comum do PowerShell, imprimindo o conteúdo do bloco de script 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:

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

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.

-EncodedArguments <Base64EncodedArguments>

Aceita um comando de versão de cadeia de caracteres codificado em Base64. Use esse parâmetro para enviar argumentos que exijam cotações complexas e aninhadas. A representação Base64 deve ser uma cadeia de caracteres codificada em UTF-16LE.

-EncodedCommand <Base64EncodedCommand>

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

-Arquivo - | <filePath><Args>

Se o valor de Arquivo for -, o texto do comando será lido 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 parâmetro File .

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 criadas pelo script estejam disponíveis nessa nova sessão. Insira o caminho do arquivo do script e quaisquer 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 do script e os parâmetros passados para esse script.

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 em cmd.exe e quiser passar um valor de variável de ambiente, use a sintaxe cmd.exe:powershell.exe -File .\test.ps1 -TestParam %windir%

Por outro lado, a execução powershell.exe -File .\test.ps1 -TestParam $env:windir em cmd.exe resulta no script recebendo a cadeia de caracteres $env:windir literal porque ela não tem nenhum significado especial para o shell cmd.exe atual. 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 será 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: powershell.exe -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

Quando o valor de File é um caminho de arquivo, Filedeve 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.

Você pode incluir os parâmetros e valores de script no valor do parâmetro File . 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 booleano para um parâmetro. Não é possível passar um valor booleano explícito para um parâmetro switch ao executar um script dessa maneira. Essa limitação foi removida no PowerShell 6 (pwsh.exe).

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.

-InputFormat {Text | XML}

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).

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

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 (cadeias de caracteres de texto) ou XML (formato CLIXML serializado).

-PSConsoleFile <FilePath>

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 <PowerShell Versão>

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" é a versão padrão. Caso contrário, "2.0" é a versão padrão. Para obter mais informações, consulte Instalar o PowerShell.

-Estilo de janela WindowStyle <>

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

-Help, -?, /?

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

COMENTÁRIOS

Observação de solução de problemas: no PowerShell 2.0, a inicialização de alguns programas do 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