about_CommonParameters

Descrizione breve

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 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 Verbose parametro comune non ha alcun effetto.

I parametri comuni sono disponibili anche nelle funzioni avanzate che usano l'attributo CmdletBinding o l'attributo Parameter .

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.

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)
  • ProgressAction (proga)
  • 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. Ad esempio, questo parametro 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.

Il Debug parametro esegue l'override $DebugPreference del valore della 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 irreversibile dal comando . Questo parametro funziona solo quando il comando genera un errore non irreversibile, 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 del valore della $ErrorActionPreference variabile per il comando corrente. Poiché il valore predefinito della $ErrorActionPreference variabile è Continue, i messaggi di errore vengono visualizzati e 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 corretto di un comando.

  • Break Immette il debugger quando si verifica un errore o viene generata un'eccezione.
  • Continue visualizza il messaggio di errore e continua l'esecuzione del comando. Continue è l'impostazione predefinita.
  • 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.
  • Inquire visualizza il messaggio di errore e chiede conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.
  • SilentlyContinue elimina il messaggio di errore e continua l'esecuzione del comando.
  • Stop visualizza il messaggio di errore e interrompe l'esecuzione del comando.
  • Suspend è disponibile solo per i flussi di lavoro che non sono supportati in PowerShell 6 e versioni successive.

Nota

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

-ErrorVariable

I record di errore vengono archiviati automaticamente nella $Error variabile automatica. Per altre informazioni, vedere about_Automatic_Variables.

Quando si usa il parametro ErrorVariable in un comando, PowerShell archivia anche i record di errore generati dal comando nella variabile specificata dal parametro .

Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

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, inserire un segno più (+) prima del nome della variabile.

Ad esempio, il comando seguente crea la $a variabile e quindi archivia eventuali errori:

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 i messaggi di errore di comandi specifici e non influisce sul comportamento della $Error variabile automatica. La $Error variabile automatica contiene messaggi di errore di 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.

Nota

La variabile di errore personalizzata contiene tutti gli errori generati dal comando, inclusi gli errori delle chiamate a funzioni o script annidati.

-InformationAction

Introdotto in PowerShell 5.0. All'interno del comando o dello script in cui viene usata, il parametro comune InformationAction esegue l'override del valore della $InformationPreference variabile di 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.

Type: ActionPreference
Aliases: infa
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
  • Break Immette il debugger in corrispondenza di un'occorrenza del Write-Information comando.
  • Stop arresta un comando o uno script in corrispondenza di un'occorrenza del Write-Information comando.
  • Ignore elimina il messaggio informativo e continua a eseguire il comando. A differenza di SilentlyContinue, Ignora dimentica completamente il messaggio informativo, ma non aggiunge il messaggio informativo al flusso di informazioni.
  • Inquire visualizza il messaggio informativo specificato in un Write-Information comando, quindi chiede se si desidera continuare.
  • Continue visualizza il messaggio informativo e continua l'esecuzione.
  • Suspend non è supportato in PowerShell 6 e versioni successive perché è disponibile solo per i flussi di lavoro.
  • 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 di preferenza quando il parametro viene usato in un comando per eseguire uno script o una funzione.

-InformationVariable

Introdotto in PowerShell 5.0. Quando si usa il parametro comune InformationVariable , i record di informazioni vengono archiviati nella variabile specificata dal parametro . Il cmdlet di PowerShell può scrivere record di informazioni nel flusso di informazioni . È anche possibile usare il Write-Information cmdlet per scrivere record di informazioni.

I record di informazioni vengono visualizzati come messaggi nella console per impostazione predefinita. È possibile controllare la visualizzazione del record di informazioni usando il parametro comune InformationAction . È anche possibile modificare il comportamento usando la variabile di $InformationPreference preferenza. Per altre informazioni su $InformationPreference, vedere about_Preference_Variables.

Nota

La variabile di informazioni contiene tutti i messaggi informativi 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

Per impostazione predefinita, i nuovi record di informazioni sovrascrivono i valori già archiviati nella variabile. Per aggiungere il messaggio di errore al contenuto della variabile, inserire un segno più (+) prima del nome della variabile.

-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 elaborazione ForEach-Object che usano il Write-Host cmdlet . Le alternative di visualizzazione 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 in esso:

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 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 di pipeline successivo. Ciò semplifica l'uso di PipelineVariable rispetto a una variabile temporanea specifica, che potrebbe essere necessario assegnare in più posizioni.

A differenza di $_ o $PSItem, l'uso di 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 la pipeline. Ciò consente a un comando di eseguire il feedback dell'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, uguali a 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 cancellate 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 isn't 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

Name                           Value
----                           -----
temp

-ProgressAction

Determina il modo in cui PowerShell risponde agli aggiornamenti dello stato generati da uno script, un cmdlet o un provider, ad esempio le barre di stato generate dal cmdlet Write-Progress . Il Write-Progress cmdlet crea barre di stato che mostrano lo stato di un comando.

Il parametro ProgressAction accetta uno dei ActionPreference valori di enumerazione: SilentlyContinue, Stop, InquireSuspendContinueIgnoreo .Break

I valori validi sono i seguenti:

  • Break Immette il debugger in corrispondenza di un'occorrenza del Write-Progress comando.
  • Stop: non visualizza l'indicatore di stato. Visualizza invece un messaggio di errore e arresta l'esecuzione.
  • Inquire: non visualizza l'indicatore di stato. Richiede l'autorizzazione per continuare. Se si risponde con Y o A, viene visualizzata la barra di stato.
  • Continue: (impostazione predefinita) Visualizza la barra di stato e continua con l'esecuzione.
  • SilentlyContinue: esegue il comando , ma non visualizza l'indicatore di stato.
Type: ActionPreference
Aliases: proga
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

-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 $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 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 $WarningPreference del valore della 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 .

  • Break immette il debugger quando si verifica un avviso.
  • Continue visualizza i messaggi di avviso e continua l'esecuzione del comando. Continue è l'impostazione predefinita.
  • Inquire visualizza il messaggio di avviso e chiede conferma prima di continuare l'esecuzione. Questo valore viene usato raramente.
  • SilentlyContinue elimina il messaggio di avviso e continua l'esecuzione del comando.
  • Stop visualizza il messaggio di avviso e interrompe 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 i record di avviso 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 tutti gli avvisi in esso contenuti:

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.

  • $true ha lo stesso effetto di -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 da eseguire 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.

  • $true ha lo stesso effetto di -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:

Response Risultato
Yes (Y) Esegui l'azione.
Yes to All (A) Eseguire tutte le azioni ed eliminare le operazioni successive Confirm
query per questo comando.
No (N): Non eseguire l'azione.
No to All (L): Non eseguire alcuna azione e eliminare le 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 per 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 annidata e tornare alle Confirm opzioni per il comando originale, digitare "exit".

Nell'esempio seguente, l'opzione Suspend (S) viene usata 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 annidata 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

Vedi anche