about_CommonParameters

Aggiornamento: maggio 2014

Si applica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

Inserire l'introduzione qui.

ARGOMENTO

about_CommonParameters

DESCRIZIONE BREVE

Questo argomento descrive i parametri che è possibile usare con qualsiasi cmdlet.

DESCRIZIONE LUNGA

I parametri comuni costituiscono un set di parametri dei cmdlet che è possibile usare con qualsiasi cmdlet. Sono implementati da Windows PowerShell® (non dallo sviluppatore di cmdlet) e sono disponibili automaticamente per tutti i cmdlet.

È possibile usare i parametri comuni con qualsiasi cmdlet, ma è possibile che non influiscano su tutti i cmdlet. Ad esempio, se un cmdlet non genera alcun output dettagliato, l'uso del parametro comune Verbose non produce alcun effetto.

I parametri comuni sono disponibili anche nelle funzioni avanzate che usano l'attributo CmdletBinding oppure l'attributo Parameter e in tutti i flussi di lavoro.

Numerosi parametri comuni ignorano le impostazioni predefinite o le preferenze del sistema che sono state impostate usando le variabili di preferenza di Windows PowerShell. A differenza delle variabili di preferenza, i parametri comuni interessano solo i comandi in cui vengono usati.

In aggiunta ai parametri comuni, molti cmdlet comprendono i parametri di mitigazione dei rischi WhatIf e Confirm. In genere, i cmdlet che comportano rischi al sistema oppure ai dati dell'utente comprendono questi parametri.

Nell'elenco seguente vengono visualizzati i parametri comuni. I relativi alias sono riportati tra parentesi.

       -Debug (db)
       -ErrorAction (ea)
       -ErrorVariable (ev)
       -OutVariable (ov)
       -OutBuffer (ob)
       -PipelineVariable (pv)
       -Verbose (vb) 
       -WarningAction (wa)
       -WarningVariable (wv

I parametri di mitigazione dei rischi sono:

-WhatIf (wi)
       -Confirm (cf)

Per altre informazioni sulle variabili di preferenza, digitare:

help about_Preference_Variables

DESCRIZIONE DEI PARAMETRI COMUNI

-DEBUG[:{$TRUE | $FALSE}]

Alias: db

Visualizza un dettaglio a livello di programmatore relativo all'operazione eseguita dal comando. Il parametro funziona soltanto quando il comando genera un messaggio di debug. Ad esempio, il parametro funziona quando un comando include il cmdlet Write-Debug.

Il parametro Debug sostituisce il valore della variabile $DebugPreference per il comando corrente, impostando il valore di $DebugPreference su Inquire. Dal momento che il valore predefinito della variabile $DebugPreference è SilentlyContinue, i messaggi di debug non vengono visualizzati per impostazione predefinita.

Valori validi:

$true (-Debug:$true). Has the same effect as -Debug.

$false (-Debug:$false). Suppresses the display of debugging
            messages when the value of the $DebugPreference is not
            SilentlyContinue (the default).

-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]

Alias: ea

Determina in che modo il cmdlet risponde a un errore non fatale proveniente dal comando. Il parametro funziona soltanto quando il comando genera un errore non fatale, ad esempio quelli del cmdlet Write-Error.

Il parametro ErrorAction sostituisce il valore della variabile $ErrorActionPreference per il comando corrente. Dal momento che il valore predefinito della variabile $ErrorActionPreference è Continue, i messaggi di errori vengono visualizzati e l'operazione prosegue a meno che non si usi il parametro ErrorAction.

Il parametro ErrorAction non ha alcun effetto sugli errori di terminazione (ad esempio, la mancanza di dati, i parametri non validi o le autorizzazioni insufficienti) che impediscono il completamento di un comando.

Valori validi:

Continue. Visualizza il messaggio di errore e prosegue con l'esecuzione del comando. "Continue" è il valore predefinito.

Ignore. Elimina il messaggio di errore e prosegue con l'esecuzione del comando. A differenza di SilentlyContinue, il valore Ignore non aggiunge il messaggio di errore alla variabile automatica $Error. Il valore Ignore viene introdotto in Windows PowerShell 3.0.

Inquire. Visualizza il messaggio di errore e chiede all'utente una conferma prima di proseguire con l'esecuzione. Questo valore viene usato raramente.

SilentlyContinue. Elimina il messaggio di errore e prosegue con l'esecuzione del comando.

Stop. Visualizza il messaggio di errore e interrompe l'esecuzione del comando.

Suspend. Il valore è disponibile soltanto nei flussi di lavoro Windows PowerShell. Quando un flusso di lavoro rileva un errore di terminazione, questa preferenza per l'azione sospende automaticamente il processo al fine di eseguire un analisi del problema. Al termine di tale analisi, è possibile riprendere il flusso di lavoro.

-ERRORVARIABLE [+]<VARIABLE-NAME>

Alias: ev

Archivia i messaggi di errore sul comando nella variabile specificata e nella variabile automatica $Error. 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 che sono già memorizzati 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 variabile $a e vi archivia tutti gli errori:

Get-Process -Id 6 -ErrorVariable a

Il seguente comando aggiunge eventuali messaggi di errore alla variabile $a:

Get-Process -Id 2 -ErrorVariable +a

Il comando seguente consente di visualizzare il contenuto di $a:

$a

È possibile usare questo parametro per creare una variabile che contiene soltanto i messaggi di errore da comandi specifici. La variabile automatica $Error contiene messaggi di errore da tutti i comandi della sessione. È possibile usare la notazione, ad esempio, $a[0] o $error[1,2] per fare riferimento ad errori specifici archiviati nelle variabili.

-OUTBUFFER <INT32>

Alias: ob

Determina il numero di oggetti da accumulare in un buffer prima che tutti gli oggetti vengano inviati attraverso la pipeline. Se si omette questo parametro, gli oggetti vengono inviati come vengono generati.

Questo parametro di gestione delle risorse è progettato per utenti avanzati. Quando si usa questo parametro, Windows PowerShell non chiama il cmdlet successivo della pipeline finché il numero di oggetti generati equivale a OutBuffer + 1. Successivamente, invia tutti gli oggetti come sono generati.

-OUTVARIABLE [+]<VARIABLE-NAME>

Alias: ov

Archivia gli oggetti di output dal comando nella variabile specificata e la visualizza nella riga di comando.

Per aggiungere l'output alla variabile, invece di sostituire eventuali output che potrebbero essere già archiviati, digitare un segno più (+) prima del nome della variabile.

Ad esempio, il comando seguente consente di creare la variabile $out e di archiviarvi l'oggetto processo:

Get-Process PowerShell -OutVariable out

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

Get-Process iexplore -OutVariable +out

Il comando seguente visualizza il contenuto della variabile $out:

$out

-PIPELINEVARIABLE <STRING>

Alias: pv

PipelineVariable consente di archiviare il valore relativo all'elemento della pipeline corrente come variabile per qualsiasi comando denominato, man mano che avanza nella pipeline.

I valori validi sono stringhe, così come i nomi di variabile.

Di seguito è riportato un esempio su come funziona PipelineVariable. In questo esempio, il parametro PipelineVariable viene aggiunto a un comando Foreach-Object al fine di archiviare i risultati del comando in variabili. Un intervallo di numeri da 1 a 10 viene inviato al primo comando Foreach-Object, i cui risultati vengono archiviati in una variabile denominata Left.

I risultati del primo comando Foreach-Object vengono inviati in un secondo comando Foreach-Object, che filtra gli oggetti restituiti dal primo comando Foreach-Object. I risultati del secondo comando vengono archiviati in una variabile denominata Right.

Nel terzo comando Foreach-Object, i risultati dei primi due comandi Foreach-Object inoltrati tramite pipe, rappresentati dalle variabili Left e Right, vengono elaborati tramite un operatore di moltiplicazione. Il comando indica gli oggetti archiviati nelle variabili Left e Right da moltiplicare e specifica che i risultati devono essere visualizzati come "Left range member * Right range member = product".

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

-VERBOSE[:{$TRUE | $FALSE}]

Alias: vb

Visualizza informazioni dettagliate sull'operazione eseguita dal comando. Tali informazioni sono simili a quelle presenti nella traccia o nel log delle transazioni. Il parametro funziona soltanto quando il comando genera un messaggio dettagliato. Ad esempio, il parametro funziona quando un comando include il cmdlet Write-Verbose.

Il parametro Verbose sostituisce il valore della variabile $VerbosePreference per il comando corrente. Dal momento che il valore predefinito della variabile $VerbosePreference è SilentlyContinue, i messaggi dettagliati non vengono visualizzati per impostazione predefinita.

Valori validi:

$true (-Verbose:$true) has the same effect as -Verbose.

$false (-Verbose:$false) suppresses the display of verbose
            messages. Use this parameter when the value of $VerbosePreference
            is not SilentlyContinue (the default).

-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]

Alias: wa

Determina il modo in cui il cmdlet risponde a un avviso proveniente dal comando. "Continue" è il valore predefinito. Il parametro funziona soltanto quando il comando genera un messaggio di avviso. Ad esempio, il parametro funziona quando un comando include il cmdlet Write-Warning.

Il parametro WarningAction sostituisce il valore della variabile $WarningPreference per il comando corrente. Dal momento che il valore predefinito della variabile $WarningPreference equivale a Continue, gli avvisi vengono visualizzati e l'esecuzione continua a meno che non venga usato il parametro WarningAction.

Valori validi:

Continue. Visualizza il messaggio di avviso e prosegue con l'esecuzione del comando. "Continue" è il valore predefinito.

Inquire. Visualizza il messaggio di avviso e chiede all'utente una conferma prima di proseguire con l'esecuzione. Questo valore viene usato raramente.

SilentlyContinue. Elimina il messaggio di avviso e prosegue con l'esecuzione del comando.

Stop. Visualizza il messaggio di avviso e interrompe l'esecuzione del comando.

NOTA: Il parametro WarningAction non sostituisce il valore della variabile di preferenza $WarningAction quando il parametro viene usato in un comando al fine di eseguire uno script o una funzionalità.

-WARNINGVARIABLE [+]<VARIABLE-NAME>

Alias: wv

Archivia gli avvisi sul comando nella variabile specificata.

Tutti gli avvisi generati vengono salvati nella variabile anche se tali avvisi non sono visibili per l'utente.

Per aggiungere gli avvisi al contenuto della variabile, invece di sostituire eventuali avvisi che potrebbero essere già archiviati, digitare un segno più (+) prima del nome della variabile.

Ad esempio, il comando seguente crea la variabile $a e vi archivia tutti gli avvisi:

Get-Process -Id 6 -WarningVariable a

Il comando seguente aggiunge tutti gli avvisi alla variabile $a:

Get-Process -Id 2 -WarningVariable +a

Il comando seguente consente di visualizzare il contenuto di $a:

$a

È possibile usare questo parametro per creare una variabile che contiene soltanto gli avvisi da comandi specifici. È possibile usare la notazione, ad esempio, $a[0] o $warning[1,2] per fare riferimento ad avvisi specifici archiviati nelle variabili.

NOTA: Il parametro WarningVariable non acquisisce gli avvisi dalle chiamate nidificate di funzioni o script.

DESCRIZIONE RELATIVA AI PARAMETRI DI GESTIONE DEI RISCHI

-WHATIF[:{$TRUE | $FALSE}]

Alias: wi

Visualizza un messaggio che descrive l'effetto del comando, anziché eseguirlo.

Il parametro ErrorAction sostituisce il valore della variabile $WhatIfPreference per il comando corrente. Dal momento che il valore predefinito della variabile $WhatIfPreference è 0 (disabilitato), il comportamento WhatIf non viene eseguito senza il parametro WhatIf. Per altre informazioni, digitare il comando seguente:

Get-Help about_Preference_Variables

Valori validi:

$true (-WhatIf:$true). Has the same effect as -WhatIf.

$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
            that results when the value of the $WhatIfPreference variable 
            is 1.

Ad esempio, il comando seguente usa il parametro WhatIf nel comando Remove-Item:

PS> Remove-Item Date.csv -WhatIf

Invece di rimuovere l'elemento, Windows PowerShell elenca le operazioni che eseguirebbe e gli elementi interessati da tali operazioni. Il comando produce l'output seguente:

What if: Performing operation "Remove File" on 
            Target "C:\ps-test\date.csv".

-CONFIRM[:{$TRUE | $FALSE}]

Alias: cf

Chiede una conferma prima di eseguire il comando.

Il parametro Confirm sostituisce il valore della variabile $ConfirmPreference per il comando corrente. Il valore predefinito è High. Per altre informazioni, digitare il comando seguente:

Get-Help about_Preference_Variables

Valori validi:

$true (-Confirm:$true). Has the same effect as -Confirm.

$false(-Confirm:$false). Suppresses automatic confirmation,
            which occurs when the value of $ConfirmPreference is less than
            or equal to the estimated risk of the cmdlet.

Ad esempio, il comando seguente usa il parametro Confirm nel comando Remove-Item: Prima di rimuovere l'elemento Windows PowerShell elenca le operazioni che verrebbero eseguite e gli elementi che sarebbero interessati da tale operazione; infine, richiede l'approvazione.

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

Il comando produce l'output seguente:

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 opzione di risposta Confirm sono le seguenti:

Yes (Y)         Perform the action.
            Yes to All (A)  Perform all actions and suppress subsequent
                            Confirm queries for this command.
            No (N):         Do not perform the action.
            No to All (L):  Do not perform any actions and suppress subsequent
                            Confirm queries for this command.
            Suspend (S):    Pause the command and create a temporary session.
            Help (?)        Display help for these options.

L'opzione Suspend sospende il comando e creare una sessione nidificata temporanea nella quale è possibile eseguire operazione finché non si seleziona l'opzione Confirm. Il prompt dei comandi della sessione nidificata dispone di due accenti circonflessi (>>) al fine di 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 opzione Confirm del comando originale, digitare "exit".

Nell'esempio seguente, l'opzione Suspend (S) viene usata per interrompere un comando temporaneamente mentre l'utente controlla la Guida del parametro del comando. Dopo aver ottenuto le informazioni necessarie, l'utente digita "exit" per terminare il prompt nidificato, quindi seleziona Yes (y) per confermare la query Confirm.

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 (default 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

VEDERE ANCHE

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose