about_PowerShell_exe

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

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

-Arquivo - | <filePath><Args>

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.

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

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

-Comando

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

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 -, 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"
'@ | powershell -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.

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

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

-NoLogo

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