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 $ErrorActionPreference , ma non sostituisce il valore della variabile 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

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.

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 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 a inviare l'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 al suo interno:

Get-Process PowerShell -OutVariable out

Il comando seguente aggiunge l'oggetto processo alla $out variabile :

Get-Process iexplore -OutVariable +out

Il comando seguente visualizza il contenuto della $out variabile:

$out

Nota

La variabile creata dal parametro OutVariable è .[System.Collections.ArrayList]

-PipelineVariable

PipelineVariable consente l'accesso al valore più recente passato nel 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 di pipeline successivo. In questo modo PipelineVariable risulta più semplice da usare rispetto a una variabile temporanea specifica, che potrebbe essere necessario assegnare 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) da comandi diversi dal comando immediatamente precedente. I comandi della pipeline possono accedere all'ultimo valore inviato tramite pipe durante l'elaborazione dell'elemento successivo passando attraverso la pipeline. In questo modo un comando può inviare il relativo output a un comando precedente (o a 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, solo i valori del primo blocco di script definito vengono assegnati 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, come per qualsiasi nome di variabile.

Attenzione

PipelineVariable ha come ambito la pipeline in cui viene richiamata. Le variabili esterne alla pipeline, che usano lo stesso nome, vengono rimosse prima dell'esecuzione della pipeline. PipelineVariable esce dall'ambito quando la pipeline termina. Se più comandi all'interno della pipeline specificano la stessa pipelineVariable , è presente una sola variabile condivisa. Tale variabile viene aggiornata con l'output pipe più recente del 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 finale inviato tramite pipe dal comando precedente quando viene usato in un comando dopo il comando di blocco.

Di seguito è riportato un esempio del 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 inviato tramite pipe al primo Foreach-Object comando, i cui risultati 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. Ad esempio, questo parametro 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 del valore della $VerbosePreference 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 la modalità di risposta del cmdlet a un avviso dal comando . Continue è il valore predefinito. Questo parametro funziona solo quando il comando genera un messaggio di avviso. Ad esempio, questo parametro 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 del valore della $WarningPreference variabile per il comando corrente. Poiché il valore predefinito della $WarningPreference variabile è Continue, gli avvisi vengono visualizzati e l'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 l'esecuzione del comando. Continue è l'impostazione predefinita.

-WarningAction:Inquire visualizza il messaggio di avviso e chiede conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.

-WarningAction:SilentlyContinue elimina il messaggio di avviso e continua l'esecuzione del comando.

-WarningAction:Stop visualizza il messaggio di avviso e arresta l'esecuzione del comando.

Nota

Il parametro WarningAction esegue l'override, ma non sostituisce il valore della $WarningAction variabile di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.

-WarningVariable

Archivia gli avvisi relativi al 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 al suo interno:

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 di 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 gli avvisi dalle 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 del valore della $WhatIfPreference 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 whatIf automatico che restituisce 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

Invece di rimuovere l'elemento, PowerShell elenca le operazioni che eseguirebbe 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 del valore della $ConfirmPreference 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

Vedi anche