about_Pwsh

  • Artigo

Breve descrição

Explica como utilizar a interface ine do pwsh comando-l. Apresenta os parâmetros de ine do comando-le descreve a sintaxe.

Descrição longa

Sintaxe

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <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 são insensíveis às maiúsculas-ie minúsculas.

-File | -f

Se o valor de File for -, o texto do comando é lido a partir da entrada padrão. A execução pwsh -File - sem entrada padrão redirecionada inicia uma sessão normal. É o mesmo que não especificar o File parâmetro.

Este é o parâmetro predefinido se não existirem parâmetros, mas os valores estiverem presentes na linha de comandos. O script especificado é executado no âmbito local ("com origem em pontos"), para que as funções e variáveis criadas pelo script estejam disponíveis na sessão atual. Introduza o caminho do ficheiro de script e quaisquer parâmetros. O ficheiro tem de ser o último parâmetro no comando, porque todos os carateres escritos após o nome do parâmetro Ficheiro são interpretados como o caminho do ficheiro de script seguido dos parâmetros do script.

Normalmente, os parâmetros de comutador de um script são incluídos ou omitidos. Por exemplo, o seguinte comando utiliza o parâmetro Todos do ficheiro de script Get-Script.ps1: -File .\Get-Script.ps1 -All

Em casos raros, poderá ter de fornecer um valor Booleano para um parâmetro switch. Para fornecer um valor Booleano para um parâmetro de comutador no valor do parâmetro Ficheiro , utilize o parâmetro normalmente seguido imediatamente por dois pontos e o valor booleano, tal como o seguinte: -File .\Get-Script.ps1 -All:$False.

Os parâmetros transmitidos para o script são transmitidos como cadeias literais, após interpretação pela shell atual. Por exemplo, se estiver no cmd.exe e quiser transmitir um valor de variável de ambiente, utilizaria a cmd.exe sintaxe: pwsh -File .\test.ps1 -TestParam %windir%

Por outro lado, a execução pwsh -File .\test.ps1 -TestParam $env:windir nos cmd.exe resultados no script recebe a cadeia $env:windir literal porque não tem um significado especial para a shell atual cmd.exe . O $env:windir estilo de referência de variável de ambiente pode ser utilizado dentro de um parâmetro de Comando , uma vez que é interpretado como código do PowerShell.

Da mesma forma, se quiser executar o mesmo comando a partir de um script do Batch, utilizaria %~dp0 em vez de ou $PSScriptRoot para representar o diretório de .\ execução atual: . pwsh -File %~dp0test.ps1 -TestParam %windir% Se, em vez disso, utilizou .\test.ps1, o PowerShell geraria um erro porque não consegue encontrar o caminho literal .\test.ps1

Nota

O parâmetro Ficheiro não consegue suportar scripts com um parâmetro que espera uma matriz de valores de argumentos. Infelizmente, esta é uma limitação da forma como um comando nativo obtém valores de argumentos. Quando chama um executável nativo (como powershell ou pwsh), não sabe o que fazer com uma matriz, pelo que é transmitido como uma cadeia.

Quando o ficheiro de script termina com um exit comando, o código de saída do processo é definido como o argumento numérico utilizado 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.

Semelhante a -Command, quando ocorre um erro de terminação do 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.

Nota

A partir do PowerShell 7.2, o parâmetro Ficheiro só aceita ficheiros .ps1 no Windows. Se for fornecido outro tipo de ficheiro, é gerado um erro. Este comportamento é específico do Windows. Noutras plataformas, o PowerShell tenta executar outros tipos de ficheiro.

-Command | -c

Executa os comandos especificados (e quaisquer parâmetros) como se tivessem sido escritos na linha de comandos do PowerShell e, em seguida, sai, a menos que o NoExit parâmetro seja especificado.

O valor de Comando pode ser -, um bloco de script ou uma cadeia. Se o valor de Comando for -, o texto do comando é lido a partir da entrada padrão.

O parâmetro Comando só aceita um bloco de script para execução quando consegue reconhecer o valor transmitido para Comando como um tipo scriptBlock . Isto só é possível ao executar a pwsh partir de outro anfitrião do PowerShell. O tipo ScriptBlock pode estar contido numa variável existente, devolvido a partir de uma expressão ou analisado pelo anfitrião do PowerShell como um bloco de script literal entre chavetas ({}), antes de ser transmitido para pwsh.

pwsh -Command {Get-WinEvent -LogName security}

No cmd.exe, não existe tal coisa como um bloco de scripts (ou tipo ScriptBlock ), pelo que o valor transmitido para Comando é sempre uma cadeia. Pode escrever um bloco de script dentro da cadeia, mas em vez de ser executado, comporta-se exatamente como se o tenha escrito numa linha de comandos típica do PowerShell, imprimindo-lhe novamente os conteúdos do bloco de scripts.

Uma cadeia de carateres transmitida para o Comando ainda é executada como código do PowerShell, pelo que as chavetas do bloco de script não são, muitas vezes, necessárias quando são executadas a partir de cmd.exe. Para executar um bloco de script inline definido dentro de uma cadeia, o operador& de chamada pode ser utilizado:

pwsh -Command "& {Get-WinEvent -LogName security}"

Se o valor de Comando for uma cadeia, Comando tem de ser o último parâmetro para pwsh, porque todos os argumentos que o seguem são interpretados como parte do comando a executar.

Quando chamados a partir de uma sessão do PowerShell existente, os resultados são devolvidos à shell principal como objetos XML desseriais e não objetos dinâmicos. Para outras shells, os resultados são devolvidos como cadeias.

Se o valor de Comando for -, o texto do comando é lido a partir da entrada padrão. Tem de redirecionar a entrada padrão ao utilizar o parâmetro Comando com entrada padrão. Por exemplo:

@'
"in"

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

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

Este exemplo produz o seguinte resultado:

in
hi there
out

O código de saída do processo é determinado pelo estado do último comando (executado) no bloco de scripts. 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 é convertido para 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 comandos ou bloco de script.

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

Da mesma forma, o valor 1 é devolvido quando um erro de terminação de script (terminação de espaço de execução), como um throw ou -ErrorAction Stop, ocorre ou quando a execução é interrompida com Ctrl+C.

-ConfigurationName | -config

Especifica um ponto final de configuração no qual o PowerShell é executado. Pode ser qualquer ponto final registado no computador local, incluindo os pontos finais de comunicação remota predefinidos do PowerShell ou um ponto final personalizado com capacidades de função de utilizador específicas.

Exemplo: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

Especifica um caminho de ficheiro de configuração de sessão (.pssc). A configuração contida no ficheiro de configuração será aplicada à sessão do PowerShell.

Exemplo: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

Especifica o nome a utilizar para um servidor IPC adicional (pipe nomeado) utilizado para depuração e outras comunicações entre processos. Isto oferece um mecanismo previsível para ligar a outras instâncias do PowerShell. Normalmente utilizado com o parâmetro CustomPipeName em Enter-PSHostProcess.

Este 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 ncoded Base64-ede um comando. Utilize este parâmetro para submeter comandos para o PowerShell que requerem citações complexas e aninhadas. A representação Base64 tem de ser uma cadeia 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 predefinida para a sessão atual e guarda-a na variável de $env:PSExecutionPolicyPreference ambiente. Este parâmetro não altera as políticas de execução configuradas persistentemente.

Este parâmetro aplica-se apenas a computadores Windows. A $env:PSExecutionPolicyPreference variável de ambiente não existe em plataformas que não são do Windows.

-InputFormat | -inp | -if

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

-Interactive | -i

Apresentar um pedido interativo ao utilizador. Inverso para o parâmetro NonInteractive.

-Login | -l

No Linux e macOS, inicia o PowerShell como uma shell de início de sessão, utilizando /bin/sh para executar perfis de início de sessão, como /etc/profile e ~/.profile. No Windows, este comutador não faz nada.

Importante

Este parâmetro tem de ser o primeiro a iniciar o PowerShell como uma shell de início de sessão. A transmissão deste parâmetro noutra posição será ignorada.

Para configurar pwsh como shell de início de sessão em sistemas operativos ike UNIX-l:

  • Verifique se o caminho absoluto completo para pwsh está listado em /etc/shells

    • Normalmente, este caminho é 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, utilize um editor para acrescentar o caminho à pwsh última linha. Isto requer privilégios elevados para edição.

  • Utilize o utilitário chsh para definir a shell do utilizador atual como pwsh:

    chsh -s /usr/bin/pwsh

Aviso

Definir pwsh como a shell de início de sessão não é atualmente suportada no Subsistema Windows para Linux (WSL) e tentar definir pwsh como shell de início de sessão pode levar a que não seja possível iniciar o WSL interativamente.

-MTA

Inicie o PowerShell com um apartamento multi-threads. Este comutador só está disponível no Windows.

-NoExit | -noe

Não sai depois de executar comandos de arranque.

Exemplo: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Oculta a faixa no arranque de sessões interativas.

-NonInteractive | -noni

Este comutador é utilizado para criar sessões que não devem exigir a entrada do utilizador. Isto é útil para scripts que são executados em tarefas agendadas ou pipelines ci/CD. Quaisquer tentativas de utilização de funcionalidades interativas, como Read-Host ou pedidos de confirmação, resultam em erros de terminação da instrução em vez de pendentes.

-NoProfile | -nop

Não carrega os perfis do PowerShell.

-NoProfileLoadTime

Oculta o texto do tempo de carregamento do perfil do PowerShell apresentado no arranque quando o tempo de carregamento excede os 500 milissegundos.

-OutputFormat | -o | -of

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

Exemplo: pwsh -o XML -c Get-Date

Quando é chamado numa sessão do PowerShell, obtém objetos serializados deserializados como cadeias de saída bastante simples. Quando chamado a partir de outras shells, o resultado é dados de cadeia formatados como texto CLIXML.

-SettingsFile | -settings

Substitui o ficheiro de definições de ide powershell.config.json do sistema-wpara a sessão. Por predefinição, as definições do ide do sistema-wsão lidas a powershell.config.json$PSHOME partir do no diretório.

Tenha em atenção que estas definições não são utilizadas pelo ponto final especificado pelo -ConfigurationName argumento .

Exemplo: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

Utilizado 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 com um apartamento de thread único. Esta é a predefinição. Este comutador só está disponível na plataforma do Windows.

-Version | -v

Apresenta a versão do PowerShell. Os 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.

-WorkingDirectory | -wd

Define o diretório de trabalho inicial ao executar no arranque. Qualquer caminho de ficheiro válido do PowerShell é suportado.

Para iniciar o PowerShell no diretório raiz, utilize: pwsh -WorkingDirectory ~

-Help, -?, /?

Apresenta ajuda para pwsh. Se estiver a escrever um comando pwsh no PowerShell, prepare os parâmetros de comando com um hífen (-) e não uma barra (/).