Informazioni su CommonParameters
DESCRIZIONE BREVE
Descrive i parametri che possono essere usati con qualsiasi cmdlet.
DESCRIZIONE LUNGA
I parametri comuni sono un set di parametri cmdlet che è possibile usare con qualsiasi cmdlet. Vengono implementati da PowerShell, non dallo sviluppatore di cmdlet e sono automaticamente disponibili per qualsiasi cmdlet.
È possibile usare i parametri comuni con qualsiasi cmdlet, ma potrebbero non avere alcun effetto su tutti i cmdlet. Ad esempio, se un cmdlet non genera alcun output dettagliato, l'uso del parametro comune Verbose non ha alcun effetto.
I parametri comuni sono disponibili anche in funzioni avanzate che usano l'attributo CmdletBinding o l'attributo Parameter e in tutti i flussi di lavoro.
Diversi parametri comuni sostituiscono le impostazioni predefinite o le 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.
Oltre ai parametri comuni, molti cmdlet offrono i parametri WhatIf e Confirm di mitigazione dei rischi. I cmdlet che comportano rischi per il sistema o per i dati utente in genere offrono questi parametri.
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)
- Dettagliato (vb)
- WarningAction (wa)
- WarningVariable (wv)
I parametri di mitigazione dei rischi sono:
- WhatIf (wi)
- Conferma (cf)
Per altre informazioni, vedere about_Preference_Variables.
DESCRIZIONI DEI PARAMETRI COMUNI
Debug
L'alias per Debug è db.
Visualizza i dettagli a livello di programmatore sull'operazione eseguita dal comando . Questo parametro funziona solo quando il comando genera un messaggio di debug. Ad esempio, questo parametro funziona quando un comando contiene il Write-Debug cmdlet .
Il parametro Debug esegue l'override del valore della $DebugPreference variabile per il comando corrente, impostando il valore di $DebugPreference su Continua. Poiché il valore predefinito della $DebugPreference variabile è SilentlyContinue, il debug dei messaggi non viene visualizzato per impostazione predefinita.
-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
L'alias per ErrorAction è ea.
Determina il modo in cui il cmdlet risponde a un errore non irreversibile dal comando .
Questo parametro funziona solo quando il comando genera un errore non irreversibile, ad esempio quelli del Write-Error cmdlet .
Il parametro ErrorAction esegue l'override del valore della $ErrorActionPreference variabile per il comando corrente. Poiché il valore predefinito della $ErrorActionPreference variabile è Continue, vengono visualizzati i messaggi di errore e l'esecuzione continua a meno che non si usi il parametro ErrorAction .
Il parametro ErrorAction non ha alcun effetto sugli errori irreversibili (ad esempio dati mancanti, parametri non validi o autorizzazioni insufficienti) che impediscono il completamento corretto di un comando.
-ErrorAction:Continue visualizzare il messaggio di errore e continuare a eseguire il comando. Continue è l'impostazione predefinita.
-ErrorAction:Ignore elimina il messaggio di errore e continua l'esecuzione del 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 chiede conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.
-ErrorAction:SilentlyContinue elimina il messaggio di errore e continua l'esecuzione del comando.
-ErrorAction:Stop visualizza il messaggio di errore e interrompe l'esecuzione del comando.
-ErrorAction:Suspend non è supportato in PowerShell Core perché è disponibile solo per i flussi di lavoro.
Nota
Il parametro ErrorAction esegue l'override, ma non sostituisce il valore della $ErrorAction variabile di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.
ErrorVariable
L'alias per ErrorVariable è ev.
ErrorVariable archivia i messaggi di errore relativi al comando nella variabile specificata e nella $Error variabile automatica. Per altre informazioni, digitare il comando seguente:
Get-Help about_Automatic_Variables
Per impostazione predefinita, i 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 contenuti:
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 contenente solo messaggi di errore da comandi specifici. La $Error variabile automatica contiene messaggi di errore da tutti i comandi della sessione. È possibile usare la notazione di matrice, ad esempio $a[0] o $error[1,2] per fare riferimento a errori specifici archiviati nelle variabili.
InformationAction
L'alias per InformationAction è ia.
Introdotta 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 preferenza, che per impostazione predefinita è impostato 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.
-InformationAction:Stop arresta un comando o uno script in corrispondenza di 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 si desidera continuare.
-InformationAction:Continue visualizza il messaggio informativo e continua l'esecuzione.
-InformationAction:Suspend non è supportato in PowerShell Core 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, ma non sostituisce il valore della $InformationAction variabile preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.
InformazioniVariable
L'alias per InformationVariable è iv.
Introdotta 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.
OutBuffer
L'alias per OutBuffer è ob e accetta un valore System.Int32 .
Determina il numero di oggetti da accumulare in un buffer prima che gli oggetti vengano inviati tramite la pipeline. Se si omette questo parametro, gli oggetti vengono inviati man mano che vengono generati.
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
L'alias per OutVariable è ov.
Archivia gli oggetti di output dal comando nella variabile specificata oltre all'invio dell'output lungo la pipeline.
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
L'alias per PipelineVariable è pv e accetta un valore stringa .
PipelineVariable archivia il valore dell'elemento della pipeline corrente come variabile, per qualsiasi comando denominato che scorre attraverso la pipeline.
I valori validi sono stringhe, uguali a per qualsiasi nome di variabile.
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 10, viene eseguito il pipe nel primo Foreach-Object comando, i risultati dei quali vengono archiviati in una variabile denominata Left.
I risultati del primo Foreach-Object comando vengono inviati in pipe in un secondo Foreach-Object comando, che filtra gli oggetti restituiti dal primo Foreach-Object comando. I risultati del secondo comando vengono archiviati in una variabile denominata Right.
Nel terzo Foreach-Object comando i risultati dei primi due Foreach-Object comandi pipe, rappresentati dalle variabili Left e Right, vengono elaborati usando un operatore di moltiplicazione. Il comando indica agli oggetti archiviati nelle variabili a sinistra e destra di essere moltiplicate e specifica che i risultati devono essere visualizzati come "Membro intervallo sinistro * Membro intervallo destro = prodotto".
1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
Foreach-Object -PV Right -Process { 1..10 } |
Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) }
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
...
Dettagliato
L'alias per Verbose è vb.
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.
Il parametro Verbose 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
L'alias per WarningAction è wa.
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.
Il parametro WarningAction esegue l'override $WarningPreference del valore della variabile per il comando corrente. Poiché il valore predefinito della $WarningPreference variabile è Continua, gli avvisi vengono visualizzati ed l'esecuzione continua a meno che non si usi il parametro WarningAction .
-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
L'alias per WarningVariable è wv.
Archivia avvisi sul comando nella variabile specificata.
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
Il parametro WarningVariable non acquisisce avvisi da chiamate annidate in funzioni o script.
Descrizioni dei parametri di gestione dei rischi
WhatIf
Alias per WhatIf è wi.
Visualizza un messaggio che descrive l'effetto del comando, anziché eseguire il comando.
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, digitare il comando seguente:
Get-Help 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
L'alias per Confirm è cf.
Richiede la conferma dell'utente prima dell'esecuzione del comando.
Il parametro Confirm esegue l'override $ConfirmPreference del valore della variabile per il comando corrente. Il valore predefinito è true. Per altre informazioni, digitare il comando seguente:
Get-Help 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 parametro Confirm con un Remove-Item comando. Prima di rimuovere l'elemento, PowerShell elenca le operazioni eseguite e gli elementi interessati e chiede 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 Conferma risposta sono le seguenti:
| Risposta | Risultato |
|---|---|
| Sì (Y) | Eseguire l'azione. |
| Sì a tutti (A) | Eseguire tutte le azioni e eliminare le query conferma successive |
| per questo comando. | |
| No (N): | Non eseguire l'azione. |
| No to All (L): | Non eseguire alcuna azione e eliminare la conferma successiva |
| query per questo comando. | |
| Sospensione (S): | Sospendere il comando e creare una sessione temporanea. |
| Guida (?) | Visualizzare la Guida per queste opzioni. |
L'opzione Sospensione inserisce il comando in attesa e crea una sessione nidificata temporanea in cui è possibile lavorare fino a quando non si è pronti per scegliere un'opzione Conferma . Il prompt dei comandi per la sessione nidificata ha due caret aggiuntive (>>) per indicare che è un'operazione figlio del comando padre originale. È possibile eseguire comandi e script nella sessione annidata. Per terminare la sessione annidata e tornare alle opzioni Conferma per il comando originale, digitare "exit".
Nell'esempio seguente viene usata l'opzione Suspend (S) per arrestare 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 il prompt annidato e quindi seleziona la risposta Sì (y) alla query Conferma.
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 CHIAVI
about_Common_Parameters