about_PowerShell_exe

  • Artigo

Breve descrição

Explica como usar a interface de linha de powershell.exe 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 para o PowerShell 7, consulte about_Pwsh.

SINTAXE

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

-Comando

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 pode reconhecer o valor passado para Command como um tipo ScriptBlock . Isso só é possível quando executado powershell.exe 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 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 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:

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

Este exemplo produz a seguinte saída:

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

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.

-Cadeia de caracteres ConfigurationName <>

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.

-EncodedArguments <Base64EncodedArguments>

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

-EncodedCommand <Base64EncodedCommand>

Aceita uma versão de cadeia de caracteres codificada em base 64 de um comando. Use esse parâmetro para enviar comandos ao PowerShell que exijam aspas complexas ou chaves curvas. 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 $env:PSExecutionPolicyPreference variável de ambiente. Esse parâmetro não altera a política de execução do PowerShell definida no Registro. Para obter informações sobre políticas de execução do PowerShell, incluindo uma lista de valores válidos, consulte about_Execution_Policies.

-Arquivo - | <filePath><Args>

Se o valor de File 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 de script e quaisquer parâmetros. Arquivo 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 strings literais, após interpretação pelo 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 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 , uma vez que lá ele será 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: 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 encontrar 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 do 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).

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.

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 terminação normal, o código de saída é sempre 0.

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

-InputFormat {Texto | XML}

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

-MTA

Inicia o PowerShell usando um apartamento multi-threaded. Esse parâmetro é introduzido no PowerShell 3.0. No PowerShell 2.0, o apartamento multi-threaded (MTA) é o padrão. No PowerShell 3.0, o apartamento de thread único (STA) é o padrão.

-NãoSaída

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

-Não interativo

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.

Oculta o banner de direitos autorais na inicialização.

-NoProfile

Não carrega o perfil do PowerShell.

-OutputFormat {Texto | XML}

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

-PSConsoleFile <FilePath>

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

-Sta

Inicia o PowerShell usando um apartamento de thread único. No Windows PowerShell 2.0, o apartamento multi-threaded (MTA) é o padrão. No Windows PowerShell 3.0, o apartamento de thread único (STA) é 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 especificada deve ser 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 mais informações, consulte Instalar o PowerShell.

-WindowStyle <estilo de janela>

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

-Ajuda-?/?

Exibe ajuda para PowerShell.exeo . 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 barra no cmd.exe.

COMENTÁRIOS

Nota de solução de problemas: No PowerShell 2.0, iniciar alguns programas a partir 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