about_CommonParameters
Breve descrizione
Descrive i parametri che possono essere usati con qualsiasi cmdlet.
Descrizione lunga
I parametri comuni sono un set di parametri di cmdlet che è possibile usare con qualsiasi cmdlet. Vengono implementati da PowerShell, non dallo sviluppatore del cmdlet e sono automaticamente disponibili per qualsiasi cmdlet.
È possibile usare i parametri comuni con qualsiasi cmdlet, ma potrebbero non avere effetto su tutti i cmdlet. Ad esempio, se un cmdlet non genera alcun output dettagliato, l'uso del Verbose parametro comune non ha alcun effetto.
I parametri comuni sono disponibili anche in funzioni avanzate che usano l'attributo CmdletBinding o l'attributo Parameter .
Diversi parametri comuni eseguono l'override delle impostazioni predefinite o delle preferenze di sistema impostate usando le variabili di preferenza di PowerShell. A differenza delle variabili di preferenza, i parametri comuni influiscono solo sui comandi in cui vengono usati.
Per altre informazioni, vedere about_Preference_Variables.
Nell'elenco seguente vengono visualizzati i parametri comuni. Gli alias sono elencati tra parentesi.
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
I parametri Action sono valori di tipo ActionPreference . ActionPreference è un'enumerazione con i valori seguenti:
| Nome | Valore |
|---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
È possibile usare il nome o il valore con il parametro .
Oltre ai parametri comuni, molti cmdlet offrono parametri di mitigazione dei rischi. I cmdlet che comportano il rischio per il sistema o per i dati utente in genere offrono questi parametri.
I parametri di mitigazione dei rischi sono:
- WhatIf (wi)
- Confirm (cf)
Descrizioni dei parametri comuni
-Debug
Visualizza i dettagli a livello di programmatore sull'operazione eseguita dal comando. Questo parametro funziona solo quando il comando genera un messaggio di debug. Questo parametro, ad esempio, funziona quando un comando contiene il Write-Debug cmdlet.
Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Per impostazione predefinita, i messaggi di debug non vengono visualizzati perché il valore della $DebugPreference variabile è SilentlyContinue.
In modalità interattiva, il Debug parametro esegue l'override del valore della $DebugPreference variabile per il comando corrente, impostando il valore di $DebugPreference su Inquire.
In modalità non interattiva, il Debug parametro esegue l'override del valore della $DebugPreference variabile per il comando corrente, impostando il valore di $DebugPreference su Continua.
-Debug:$true ha lo stesso effetto di -Debug. Usare -Debug:$false per eliminare la visualizzazione dei messaggi di debug quando $DebugPreference non è SilentlyContinue, ovvero l'impostazione predefinita.
-ErrorAction
Determina il modo in cui il cmdlet risponde a un errore non terminante dal comando.
Questo parametro funziona solo quando il comando genera un errore non terminante, ad esempio quelli del Write-Error cmdlet.
Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Il parametro ErrorAction esegue l'override $ErrorActionPreference del valore della variabile per il comando corrente. Poiché il valore predefinito della $ErrorActionPreference variabile è Continua, i messaggi di errore vengono visualizzati ed l'esecuzione continua a meno che non si usi il parametro ErrorAction .
Il parametro ErrorAction non ha alcun effetto sugli errori di terminazione ,ad esempio dati mancanti, parametri non validi o autorizzazioni insufficienti, che impediscono il completamento di un comando.
-ErrorAction:Break Immette il debugger quando si verifica un errore o viene generata un'eccezione.
-ErrorAction:Continue visualizza il messaggio di errore e continua a eseguire il comando. Continue è l'impostazione predefinita.
-ErrorAction:Ignore elimina il messaggio di errore e continua a eseguire il comando. A differenza di SilentlyContinue, Ignore non aggiunge il messaggio di errore alla $Error variabile automatica. Il valore Ignore viene introdotto in PowerShell 3.0.
-ErrorAction:Inquire visualizza il messaggio di errore e richiede la conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.
-ErrorAction:SilentlyContinue elimina il messaggio di errore e continua a eseguire il comando.
-ErrorAction:Stop visualizza il messaggio di errore e arresta l'esecuzione del comando.
-ErrorAction:Suspend è disponibile solo per i flussi di lavoro che non sono supportati in PowerShell 6 e oltre.
Nota
Il parametro ErrorAction esegue l'override $ErrorAction , ma non sostituisce il valore della variabile di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.
-ErrorVariable
ErrorVariable archivia i messaggi di errore relativi al comando nella variabile specificata e nella $Error variabile automatica. Per altre informazioni, vedere about_Automatic_Variables
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Per impostazione predefinita, nuovi messaggi di errore sovrascrivono i messaggi di errore già archiviati nella variabile. Per aggiungere il messaggio di errore al contenuto della variabile, digitare un segno più (+) prima del nome della variabile.
Ad esempio, il comando seguente crea la $a variabile e quindi archivia eventuali errori in esso:
Get-Process -Id 6 -ErrorVariable a
Il comando seguente aggiunge eventuali messaggi di errore alla $a variabile:
Get-Process -Id 2 -ErrorVariable +a
Il comando seguente visualizza il contenuto di $a:
$a
È possibile usare questo parametro per creare una variabile che contiene solo messaggi di errore da comandi specifici e non influisce sul comportamento della $Error variabile automatica. La $Error variabile automatica contiene messaggi di errore da tutti i comandi della sessione. È possibile usare la notazione della matrice, ad esempio $a[0] o $error[1,2] per fare riferimento a errori specifici archiviati nelle variabili.
Nota
La variabile di errore personalizzata contiene tutti gli errori generati dal comando, inclusi gli errori dalle chiamate a funzioni o script annidati.
-InformationAction
Introdotto in PowerShell 5.0. All'interno del comando o dello script in cui viene usato, il parametro comune InformationAction esegue l'override del valore della $InformationPreference variabile di preferenza, che per impostazione predefinita è impostata su SilentlyContinue. Quando si usa Write-Information in uno script con InformationAction, Write-Information i valori vengono visualizzati a seconda del valore del parametro InformationAction . Per altre informazioni su $InformationPreference, vedere about_Preference_Variables.
Type: ActionPreference
Aliases: ia
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
-InformationAction:Break Immette il debugger in un'occorrenza del Write-Information comando.
-InformationAction:Stop arresta un comando o uno script in un'occorrenza del Write-Information comando.
-InformationAction:Ignore elimina il messaggio informativo e continua a eseguire il comando. A differenza di SilentlyContinue, ignora completamente il messaggio informativo; non aggiunge il messaggio informativo al flusso di informazioni.
-InformationAction:Inquire visualizza il messaggio informativo specificato in un Write-Information comando, quindi chiede se continuare.
-InformationAction:Continue visualizza il messaggio informativo e continua l'esecuzione.
-InformationAction:Suspend non è supportato in PowerShell 6 e versioni successive perché è disponibile solo per i flussi di lavoro.
-InformationAction:SilentlyContinue nessun effetto perché il messaggio informativo non viene visualizzato (Impostazione predefinita) e lo script continua senza interruzioni.
Nota
Il parametro InformationAction esegue l'override $InformationAction , ma non sostituisce il valore della variabile di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.
-InformationVariable
Introdotto in PowerShell 5.0. All'interno del comando o dello script in cui viene usato, il parametro comune InformationVariable archivia in una variabile una stringa specificata aggiungendo il Write-Information comando. Write-Information i valori vengono visualizzati a seconda del valore del parametro comune InformationAction ; se non si aggiunge il parametro comune InformationAction , Write-Information le stringhe vengono visualizzate a seconda del valore della $InformationPreference variabile di preferenza. Per altre informazioni su $InformationPreference, vedere about_Preference_Variables.
Nota
La variabile di informazioni contiene tutti i messaggi di informazioni generati dal comando, inclusi i messaggi informativi dalle chiamate a funzioni o script annidati.
Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutBuffer
Determina il numero di oggetti da accumulare in un buffer prima che tutti gli oggetti vengano inviati tramite la pipeline. Se si omette questo parametro, gli oggetti vengono inviati man mano che vengono generati.
Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Questo parametro di gestione delle risorse è progettato per gli utenti avanzati. Quando si usa questo parametro, PowerShell invia i dati al cmdlet successivo in batch di OutBuffer + 1.
Nell'esempio seguente vengono visualizzate alternative tra i blocchi di ForEach-Object elaborazione che usano il Write-Host cmdlet. Visualizzazione alternativa in batch di 2 o OutBuffer + 1.
1..4 | ForEach-Object {
Write-Host "$($_): First"; $_
} -OutBuffer 1 | ForEach-Object {
Write-Host "$($_): Second" }
1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second
-OutVariable
Archivia gli oggetti di output dal comando nella variabile specificata oltre all'invio dell'output lungo la pipeline.
Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Per aggiungere l'output alla variabile, anziché sostituire qualsiasi output che potrebbe essere già archiviato, digitare un segno più (+) prima del nome della variabile.
Ad esempio, il comando seguente crea la $out variabile e archivia l'oggetto processo in esso:
Get-Process PowerShell -OutVariable out
Il comando seguente aggiunge l'oggetto $out process alla variabile:
Get-Process iexplore -OutVariable +out
Il comando seguente visualizza il contenuto della $out variabile:
$out
Nota
La variabile creata dal parametro OutVariable è un [System.Collections.ArrayList]oggetto .
-PipelineVariable
PipelineVariable consente l'accesso al valore più recente passato al segmento di pipeline successivo dal comando che usa questo parametro. Qualsiasi comando nella pipeline può accedere al valore usando il nome PipelineVariable. Il valore viene assegnato alla variabile quando viene passato al segmento della pipeline successivo. Ciò semplifica l'uso di PipelineVariable rispetto a una variabile temporanea specifica, che potrebbe essere assegnata in più posizioni.
A differenza $_ di o $PSItem, l'uso di un oggetto PipelineVariable consente a qualsiasi comando della pipeline di accedere ai valori della pipeline passati (e salvati) dai comandi diversi dal comando immediatamente precedente. I comandi della pipeline possono accedere all'ultimo valore piped da durante l'elaborazione dell'elemento successivo passando la pipeline. In questo modo un comando consente di eseguire il feed di output in un comando precedente (o se stesso).
Nota
Le funzioni avanzate possono avere fino a tre blocchi di script: begin, processe end. Quando si usa il parametro PipelineVariable con funzioni avanzate, vengono assegnati solo valori dal primo blocco di script definito alla variabile durante l'esecuzione della funzione. Per altre informazioni, vedere Funzioni avanzate. PowerShell 7.2 corregge questo comportamento.
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
I valori validi sono stringhe, uguali a per qualsiasi nome di variabile.
Attenzione
PipelineVariable è con ambito nella pipeline in cui viene richiamata. Le variabili all'esterno della pipeline, che usano lo stesso nome, vengono rimosse prima dell'esecuzione della pipeline. PipelineVariable esce dall'ambito al termine della pipeline. Se più comandi all'interno della pipeline specificano la stessa pipelineVariable , esiste solo una variabile condivisa. Tale variabile viene aggiornata con l'output pipe più recente dal comando che specifica la variabile.
Alcuni comandi di blocco raccolgono tutti gli elementi della pipeline prima di produrre qualsiasi output, ad esempio Sort-Object o Select-Object -Last. Qualsiasi pipelineVariable assegnata in un comando prima di tale comando di blocco contiene sempre l'elemento piped finale dal comando precedente quando usato in un comando dopo il comando di blocco.
Di seguito è riportato un esempio di funzionamento di PipelineVariable . In questo esempio il parametro PipelineVariable viene aggiunto a un Foreach-Object comando per archiviare i risultati del comando nelle variabili. Un intervallo di numeri, da 1 a 5, viene eseguito il pipe nel primo Foreach-Object comando, i risultati dei quali vengono archiviati in una variabile denominata $temp.
I risultati del primo Foreach-Object comando vengono inviati tramite pipe in un secondo Foreach-Object comando, che visualizza i valori correnti di $temp e $_.
# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created is not available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
Write-Output $_
} | ForEach-Object {
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp
Name Value
---- -----
temp 8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
Step2[PROCESS]:$temp=5 - $_=5
Get-Variable: Cannot find a variable with the name 'temp'.
-Verbose
Visualizza informazioni dettagliate sull'operazione eseguita dal comando. Queste informazioni sono simili alle informazioni contenute in una traccia o in un log delle transazioni. Questo parametro funziona solo quando il comando genera un messaggio dettagliato. Questo parametro, ad esempio, funziona quando un comando contiene il Write-Verbose cmdlet.
Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Il Verbose parametro esegue l'override $VerbosePreference del valore della variabile per il comando corrente. Poiché il valore predefinito della $VerbosePreference variabile è SilentlyContinue, i messaggi dettagliati non vengono visualizzati per impostazione predefinita.
-Verbose:$true ha lo stesso effetto di -Verbose
-Verbose:$false elimina la visualizzazione dei messaggi dettagliati. Usare questo parametro quando il valore di $VerbosePreference non è SilentlyContinue (impostazione predefinita).
-WarningAction
Determina il modo in cui il cmdlet risponde a un avviso dal comando. Continua è il valore predefinito. Questo parametro funziona solo quando il comando genera un messaggio di avviso. Questo parametro, ad esempio, funziona quando un comando contiene il Write-Warning cmdlet.
Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Il parametro WarningAction esegue l'override $WarningPreference del valore della variabile per il comando corrente. Poiché il valore predefinito della $WarningPreference variabile è Continua, vengono visualizzati avvisi ed esecuzione continua a meno che non si usi il parametro WarningAction .
-WarningAction:Break immette il debugger quando si verifica un avviso.
-WarningAction:Continue visualizza i messaggi di avviso e continua a eseguire il comando. Continue è l'impostazione predefinita.
-WarningAction:Inquire visualizza il messaggio di avviso e richiede la conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.
-WarningAction:SilentlyContinue elimina il messaggio di avviso e continua a eseguire il comando.
-WarningAction:Stop visualizza il messaggio di avviso e arresta l'esecuzione del comando.
Nota
Il parametro WarningAction esegue l'override $WarningAction , ma non sostituisce il valore della variabile di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.
-WarningVariable
Archivia avvisi sul comando nella variabile specificata.
Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Tutti gli avvisi generati vengono salvati nella variabile anche se gli avvisi non vengono visualizzati all'utente.
Per aggiungere gli avvisi al contenuto della variabile, anziché sostituire eventuali avvisi che potrebbero essere già archiviati, digitare un segno più (+) prima del nome della variabile.
Ad esempio, il comando seguente crea la $a variabile e quindi archivia eventuali avvisi in esso:
Get-Process -Id 6 -WarningVariable a
Il comando seguente aggiunge eventuali avvisi alla $a variabile:
Get-Process -Id 2 -WarningVariable +a
Il comando seguente visualizza il contenuto di $a:
$a
È possibile usare questo parametro per creare una variabile contenente solo avvisi da comandi specifici. È possibile usare la notazione matrice, ad esempio $a[0] o $warning[1,2] per fare riferimento a avvisi specifici archiviati nella variabile.
Nota
La variabile di avviso contiene tutti gli avvisi generati dal comando, inclusi avvisi da chiamate a funzioni o script annidati.
Descrizioni dei parametri di gestione dei rischi
-WhatIf
Visualizza un messaggio che descrive l'effetto del comando, anziché eseguire il comando.
Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Il parametro WhatIf esegue l'override $WhatIfPreference del valore della variabile per il comando corrente. Poiché il valore predefinito della $WhatIfPreference variabile è 0 (disabilitato), il comportamento WhatIf non viene eseguito senza il parametro WhatIf . Per altre informazioni, vedere about_Preference_Variables
-WhatIf:$true ha lo stesso effetto di -WhatIf.
-WhatIf:$false elimina il comportamento di WhatIf automatico che genera quando il valore della $WhatIfPreference variabile è 1.
Ad esempio, il comando seguente usa il -WhatIf parametro in un Remove-Item comando:
Remove-Item Date.csv -WhatIf
Anziché rimuovere l'elemento, PowerShell elenca le operazioni eseguite e gli elementi interessati. Questo comando produce l'output seguente:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-Confirm
Richiede la conferma dell'utente prima dell'esecuzione del comando.
Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Il Confirm parametro esegue l'override $ConfirmPreference del valore della variabile per il comando corrente. Il valore predefinito è true. Per altre informazioni, vedere about_Preference_Variables
-Confirm:$true ha lo stesso effetto di -Confirm.
-Confirm:$false elimina la conferma automatica, che si verifica quando il valore di $ConfirmPreference è minore o uguale al rischio stimato del cmdlet.
Ad esempio, il comando seguente usa il Confirm parametro con un Remove-Item comando . Prima di rimuovere l'elemento, PowerShell elenca le operazioni da eseguire e gli elementi interessati e richiede l'approvazione.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend
[?] Help (default is "Y"):
Le opzioni di Confirm risposta sono le seguenti:
| Risposta | Risultato |
|---|---|
Yes (Y) |
Eseguire l'azione. |
Yes to All (A) |
Eseguire tutte le azioni ed eliminare le query successive Confirm |
| per questo comando. | |
No (N): |
Non eseguire l'azione. |
No to All (L): |
Non eseguire alcuna azione ed eliminare le azioni successive Confirm |
| query per questo comando. | |
Suspend (S): |
Sospendere il comando e creare una sessione temporanea. |
Help (?) |
Visualizzare la Guida per queste opzioni. |
L'opzione Sospendi posiziona il comando in attesa e crea una sessione nidificata temporanea in cui è possibile lavorare fino a quando non si è pronti a scegliere un'opzione Confirm . Il prompt dei comandi per la sessione nidificata include due punti di inserimento aggiuntivi (>>) per indicare che si tratta di un'operazione figlio del comando padre originale. È possibile eseguire comandi e script nella sessione nidificata. Per terminare la sessione nidificata e tornare alle Confirm opzioni per il comando originale, digitare "exit".
Nell'esempio seguente viene usata l'opzione Suspend (S) per interrompere temporaneamente un comando mentre l'utente controlla la guida per un parametro di comando. Dopo aver ottenuto le informazioni necessarie, l'utente digita "exit" per terminare la richiesta nidificata e quindi seleziona la risposta Sì (y) alla Confirm query.
PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination:
C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default
is "Y"): s
PS C:\ps-test> Get-Help New-Item -Parameter ItemType
-ItemType <string>
Specifies the provider-specified type of the new item.
Required? false
Position? named
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false
PS C:\ps-test> exit
Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test
.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (defau
lt is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
Parole chiave
about_Common_Parameters