about_Pwsh

Breve descrizione

Viene illustrato come usare il comando pwsh-linterfaccia ine. Visualizza il comando-lparametri ine e descrive la sintassi.

Descrizione lunga

Per informazioni sul comando-lopzioni ine per Windows PowerShell 5.1, vedere about_PowerShell_exe.

Sintassi

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <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 | -? | /?

Parametri

Tutti i parametri sono case-insensitive.

-File | -f

Il valore di File può essere - o un percorso file e parametri facoltativi. Se il valore di File è -, i comandi vengono letti dall'input standard.

Questo è il parametro predefinito se non sono presenti parametri, ma i valori sono presenti nella riga di comando. Lo script specificato viene eseguito nell'ambito locale ("dot-sourced") della nuova sessione, in modo che le funzioni e le variabili create dallo script siano disponibili in in una nuova sessione. Immettere il percorso file script e tutti i parametri. Il file deve essere l'ultimo parametro nel comando, perché tutti i caratteri digitati dopo il nome del parametro File vengono interpretati come il percorso file script seguito dai parametri dello script.

In genere, i parametri switch di uno script vengono inclusi o omessi. Ad esempio, il comando seguente usa il parametro All del file script Get-Script.ps1: -File .\Get-Script.ps1 -All

In rari casi, potrebbe essere necessario specificare un valore booleano per un parametro switch. Per fornire un valore booleano per un parametro switch nel valore del parametro file, usare normalmente il parametro seguito immediatamente da due punti e dal valore booleano, ad esempio il seguente: -File .\Get-Script.ps1 -All:$false.

I parametri passati allo script vengono passati come stringhe letterali, dopo l'interpretazione dalla shell corrente. Ad esempio, se ci si trova in cmd.exe e si vuole passare un valore di variabile di ambiente, usare la sintassi cmd.exe: pwsh -File .\test.ps1 -TestParam %windir%

Al contrario, l'esecuzione di pwsh -File .\test.ps1 -TestParam $Env:windir in cmd.exe comporta la ricezione della stringa letterale $Env:windir perché non ha alcun significato speciale per la shell cmd.exe corrente. Lo stile di riferimento $Env:windir della variabile di ambiente può essere usato all'interno di un parametro Command, poiché è interpretato come codice di PowerShell.

Analogamente, se si vuole eseguire lo stesso comando da uno script batch , usare %~dp0 anziché .\ o $PSScriptRoot per rappresentare la directory di esecuzione corrente: pwsh -File %~dp0test.ps1 -TestParam %windir%. Se invece si usa .\test.ps1, PowerShell genera un errore perché non riesce a trovare il percorso letterale .\test.ps1

Nota

Il parametro file non può supportare gli script usando un parametro che prevede una matrice di valori di argomento. Questo, purtroppo, è una limitazione del modo in cui un comando nativo ottiene i valori degli argomenti. Quando si chiama un eseguibile nativo ( ad esempio powershell o pwsh), non sa cosa fare con una matrice, quindi viene passato come stringa.

Se il valore di File è -, i comandi vengono letti dall'input standard. L'esecuzione di pwsh -File - senza input standard reindirizzato avvia una normale sessione. Equivale a non specificare affatto il parametro File. Quando si legge dall'input standard, le istruzioni di input vengono eseguite un'istruzione alla volta come se fossero state digitate al prompt dei comandi di PowerShell. Se un'istruzione non analizza correttamente, l'istruzione non viene eseguita. Il codice di uscita del processo è determinato dallo stato dell'ultimo comando (eseguito) all'interno dell'input. Con la terminazione normale, il codice di uscita è sempre 0. Quando il file di script termina con un comando exit, il codice di uscita del processo viene impostato sull'argomento numerico usato con il comando exit.

Analogamente a -Command, quando si verifica un errore di terminazione dello script, il codice di uscita viene impostato su 1. Tuttavia, a differenza di -Command, quando l'esecuzione viene interrotta con CTRL+C il codice di uscita è 0. Per altre informazioni, vedere $LASTEXITCODE in about_Automatic_Variables.

Nota

A partire da PowerShell 7.2, il parametro file accetta solo file .ps1 in Windows. Se viene generato un altro tipo di file, viene generato un errore. Questo comportamento è specifico di Windows. In altre piattaforme PowerShell tenta di eseguire altri tipi di file.

-Command | -c

Il valore di Command può essere -, uno scriptblock o una stringa. Se il valore di Command è -, il testo del comando viene letto dall'input standard.

Il parametro Command accetta solo uno scriptblock per l'esecuzione quando è in grado di riconoscere il valore passato a Command come tipo ScriptBlock . Questo è possibile solo durante l'esecuzione di pwsh da un altro host di PowerShell. Il tipo ScriptBlock può essere contenuto in una variabile esistente, restituita da un'espressione o analizzata dall'host di PowerShell come blocco di script letterale racchiuso tra parentesi graffe ({}), prima di essere passato a pwsh.

pwsh -Command {Get-WinEvent -LogName Security}

In cmd.exenon esiste un elemento come scriptblock (o tipo ScriptBlock ), quindi il valore passato a Command è sempre una stringa. È possibile scrivere un blocco di script all'interno della stringa, ma invece di eseguirlo si comporta esattamente come se fosse stato digitato in un tipico prompt di PowerShell, stampando il contenuto del blocco di script all'utente.

Una stringa passata a Command viene comunque eseguita come codice di PowerShell, pertanto le parentesi graffe di scriptblock non sono spesso necessarie al primo posto quando si esegue da cmd.exe. Per eseguire uno scriptblock inline definito all'interno di una stringa, è possibile usare l'operatore &di chiamata:

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

Se il valore di Command è una stringa, Command deve essere l'ultimo parametro per pwsh, perché tutti gli argomenti che seguono vengono interpretati come parte del comando da eseguire.

Quando viene chiamato dall'interno di una sessione di PowerShell esistente, i risultati vengono restituiti alla shell padre come oggetti XML deserializzati, non oggetti attivi. Per altre shell, i risultati vengono restituiti come stringhe.

Se il valore di Command è -, i comandi vengono letti dall'input standard. È necessario reindirizzare l'input standard quando si usa il parametro comando con input standard. Per esempio:

@'
"in"

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

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

In questo esempio viene generato l'output seguente:

in
hi there
out

Durante la lettura dall'input standard, l'input viene analizzato ed eseguito un'istruzione alla volta, come se fossero stati digitati al prompt dei comandi di PowerShell. Se il codice di input non viene analizzato correttamente, l'istruzione non viene eseguita. A meno che non si usi il parametro -NoExit, la sessione di PowerShell viene chiusa quando non è disponibile alcun input da leggere dall'input standard.

Il codice di uscita del processo è determinato dallo stato dell'ultimo comando (eseguito) all'interno dell'input. Il codice di uscita viene 0 quando $? è $true o 1 quando $? è $false. Se l'ultimo comando è un programma esterno o uno script di PowerShell che imposta in modo esplicito un codice di uscita diverso da 0 o 1, tale codice di uscita viene convertito in 1 per il codice di uscita del processo. Analogamente, il valore 1 viene restituito quando si verifica un errore di terminazione dello script (terminazione dello spazio di esecuzione), ad esempio un throw o un -ErrorAction Stop, si verifica o quando l'esecuzione viene interrotta con CTRL+C.

Per mantenere il codice di uscita specifico, aggiungere exit $LASTEXITCODE alla stringa di comando o scriptblock. Per altre informazioni, vedere $LASTEXITCODE in about_Automatic_Variables.

-CommandWithArgs | -cwa

Si tratta di una funzionalità sperimentale aggiunta nella versione 7.4 e diventata mainstream in PowerShell 7.5-preview.5.

Esegue un comando di PowerShell con argomenti. A differenza di -Command, questo parametro popola la $args compilata-ivariabile n che può essere usata dal comando .

La prima stringa è il comando . Le stringhe aggiuntive delimitate da spazi vuoti sono gli argomenti.

Per esempio:

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

In questo esempio viene generato l'output seguente:

arg: arg1
arg: arg2

Nota

l'analisi degli argomenti con virgolette fa sì che l'esempio abbia esito negativo se viene eseguito da cmd.exe o powershell.exe. Per eseguirli da questi, è possibile usare

REM Quoting required when run from cmd.exe
pwsh -CommandWithArgs "$args | % { ""arg: $_"" }" arg1 arg2

# Quoting required when run from powershell.exe
pwsh -CommandWithArgs '"$args | % { ""arg: $_"" }"' arg1 arg2

-ConfigurationName | -config

Specifica un endpoint di configurazione in cui viene eseguito PowerShell. Può trattarsi di qualsiasi endpoint registrato nel computer locale, inclusi gli endpoint remoti predefiniti di PowerShell o un endpoint personalizzato con funzionalità specifiche del ruolo utente.

Esempio: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

Specifica un percorso del file di configurazione della sessione (.pssc). La configurazione contenuta nel file di configurazione verrà applicata alla sessione di PowerShell.

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

-CustomPipeName

Specifica il nome da usare per un server IPC aggiuntivo (named pipe) utilizzato per il debug e altre comunicazioni tra processi. Questo offre un meccanismo prevedibile per la connessione ad altre istanze di PowerShell. In genere usato con il parametro CustomPipeName in Enter-PSHostProcess.

Questo parametro è stato introdotto in PowerShell 6.2.

Per esempio:

# PowerShell instance 1
pwsh -CustomPipeName MyDebugPipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName MyDebugPipe

-EncodedCommand | -e | -ec

Accetta una versione stringa di base64-encoded di un comando. Usare questo parametro per inviare comandi a PowerShell che richiedono virgolette complesse e annidate. La rappresentazione Base64 deve essere una stringa con codifica UTF-16LE.

Per esempio:

$command = 'dir "C:\Program Files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -EncodedCommand $encodedCommand

-ExecutionPolicy | -ex | -ep

Imposta i criteri di esecuzione predefiniti per la sessione corrente e lo salva nella variabile di ambiente $Env:PSExecutionPolicyPreference. Questo parametro non modifica i criteri di esecuzione configurati in modo permanente.

Questo parametro si applica solo ai computer Windows. Nelle piattaforme non Windows il parametro e il valore forniti vengono ignorati.

-InputFormat | -inp | -if

Descrive il formato dei dati inviati a PowerShell. I valori validi sono "Text" (stringhe di testo) o "XML" (formato CLIXML serializzato).

-Interactive | -i

Presentare un prompt interattivo all'utente. Inversa per il parametro NonInteractive.

-Login | -l

In Linux e macOS, avvia PowerShell come shell di accesso, usando /bin/sh per eseguire profili di accesso come /etc/profile e ~/.profile. In Windows questa opzione non esegue alcuna operazione.

Importante

Questo parametro deve venire prima di tutto per avviare PowerShell come shell di accesso. Questo parametro viene ignorato se viene passato in un'altra posizione.

Per configurare pwsh come shell di accesso nei sistemi operativi Unix-like:

• Verificare che il percorso assoluto completo per pwsh sia elencato in /etc/shells

  • Questo percorso è in genere simile a /usr/bin/pwsh in Linux o /usr/local/bin/pwsh in macOS
  • Con alcuni metodi di installazione, questa voce verrà aggiunta automaticamente al momento dell'installazione
  • Se pwsh non è presente in /etc/shells, usare un editor per aggiungere il percorso a pwsh nell'ultima riga. Questo richiede privilegi elevati da modificare.

• Usare l'utilità chsh per impostare la shell dell'utente corrente su pwsh:

  chsh -s /usr/bin/pwsh
  

Avvertimento

L'impostazione di pwsh perché la shell di accesso non è attualmente supportata in Sottosistema Windows per Linux (WSL) e il tentativo di impostare pwsh come shell di accesso potrebbe causare l'impossibilità di avviare WSL in modo interattivo.

-MTA

Avviare PowerShell usando un apartment multithread. Questa opzione è disponibile solo in Windows. L'uso di questo parametro su piattaforme non Windows genera un errore.

-NoExit | -noe

Non viene chiuso dopo l'esecuzione dei comandi di avvio.

Esempio: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Nasconde il banner all'avvio di sessioni interattive.

-NonInteractive | -noni

Questa opzione viene usata per creare sessioni che non devono richiedere l'input dell'utente. Ciò è utile per gli script eseguiti nelle attività pianificate o nelle pipeline CI/CD. Qualsiasi tentativo di usare funzionalità interattive, ad esempio Read-Host o richieste di conferma, comporta errori di terminazione dell'istruzione anziché sporsi.

-NoProfile | -nop

Non carica i profili di PowerShell.

-NoProfileLoadTime

Nasconde il testo del tempo di caricamento del profilo di PowerShell visualizzato all'avvio quando il tempo di caricamento supera i 500 millisecondi.

-OutputFormat | -o | -of

Determina la formattazione dell'output da PowerShell. I valori validi sono "Text" (stringhe di testo) o "XML" (formato CLIXML serializzato).

Esempio: pwsh -o XML -c Get-Date

Quando viene chiamato all'interno di una sessione di PowerShell, si ottengono oggetti deserializzati come stringhe di output piuttosto semplici. Quando viene chiamato da altre shell, l'output è costituito da dati stringa formattati come testo CLIXML.

-SettingsFile | -settings

Esegue l'override del file di impostazioni-w-w per la sessione. Per impostazione predefinita, le impostazioni dell'ide di-wdi sistema vengono lette dalla powershell.config.json nella directory $PSHOME.

Si noti che queste impostazioni non vengono usate dall'endpoint specificato dall'argomento -ConfigurationName.

Esempio: pwsh -SettingsFile C:\myproject\powershell.config.json

-SSHServerMode | -sshs

Usato in sshd_config per l'esecuzione di PowerShell come sottosistema SSH. Non è progettato o supportato per altri usi.

-STA

Avviare PowerShell usando un apartment a thread singolo. Si tratta dell'impostazione predefinita. Questa opzione è disponibile solo nella piattaforma Windows. L'uso di questo parametro su piattaforme non Windows genera un errore.

-Version | -v

Visualizza la versione di questo eseguibile di PowerShell. I parametri aggiuntivi vengono ignorati.

-WindowStyle | -w

Imposta lo stile della finestra per la sessione. I valori validi sono Normal, Minimized, Maximized e Hidden. Questo parametro si applica solo a Windows. L'uso di questo parametro su piattaforme non Windows genera un errore.

-WorkingDirectory | -wd | -wo

Imposta la directory di lavoro iniziale eseguendo all'avvio. È supportato qualsiasi percorso di file di PowerShell valido.

Per avviare PowerShell nella home directory, usare: pwsh -WorkingDirectory ~

-Help, -?, /?

Visualizza la Guida per pwsh. Se si digita un comando pwsh in PowerShell, anteporre i parametri di comando con un trattino (-), non una barra (/).