about_Automatic_Variables

Breve descrizione

Vengono descritte le variabili che archiviano le informazioni sullo stato per e vengono create e gestite da PowerShell.

Descrizione lunga

Concettualmente, la maggior parte di queste variabili viene considerata di sola lettura. Anche se possono essere scritti, per garantire la compatibilità retroattiva, non dovrebbero essere scritti.

Ecco un elenco delle variabili automatiche in PowerShell:

• $$
• $?
• $^
• $_
• $args
• $ConsoleFileName
• $EnabledExperimentalFeatures
• $Error
• $Event
• $EventArgs
• $EventSubscriber
• $ExecutionContext
• $false
• $foreach
• $HOME
• $Host
• $input
• $IsCoreCLR
• $IsLinux
• $IsMacOS
• $IsWindows
• $LASTEXITCODE
• $Matches
• $MyInvocation
• $NestedPromptLevel
• $null
• $PID
• $PROFILE
• $PSBoundParameters
• $PSCmdlet
• $PSCommandPath
• $PSCulture
• $PSDebugContext
• $PSEdition
• $PSHOME
• $PSItem
• $PSScriptRoot
• $PSSenderInfo
• $PSUICulture
• $PSVersionTable
• $PWD
• $Sender
• $ShellId
• $StackTrace
• $switch
• $this
• $true

$$

Contiene l'ultimo token nell'ultima riga ricevuta dalla sessione.

$?

Contiene lo stato di esecuzione dell'ultimo comando. Contiene true se l'ultimo comando ha avuto esito positivo e False se non è riuscito. Gli errori di analisi non comportano l'esecuzione, quindi non influiscono sul valore di $?.

Per i cmdlet e le funzioni avanzate eseguite in più fasi di una pipeline, ad esempio nei blocchi process e end, chiamando rispettivamente this.WriteError() o $PSCmdlet.WriteError() in qualsiasi punto, si imposta $? su False, così come accade con this.ThrowTerminatingError() e $PSCmdlet.ThrowTerminatingError().

Il cmdlet Write-Error imposta sempre $? su False immediatamente dopo l'esecuzione, ma non imposta $? su False per una funzione che la chiama:

function Test-WriteError
{
    Write-Error "Bad"
    "The `$? variable is: $?"
}

Test-WriteError
"Now the `$? variable is: $?"

Test-WriteError:
Line |
   7 |  Test-WriteError
     |  ~~~~~~~~~~~~~~~
     | Bad
The $? variable is: False
Now the $? variable is: True

Per quest'ultimo scopo, è consigliabile usare $PSCmdlet.WriteError().

Per i comandi nativi (eseguibili), $? è impostato su True quando $LASTEXITCODE è 0 e impostato su False quando $LASTEXITCODE è qualsiasi altro valore.

$^

Contiene il primo token nell'ultima riga ricevuta dalla sessione.

$_

Uguale a $PSItem. Contiene l'oggetto corrente all'interno dell'oggetto della pipeline. È possibile usare questa variabile nei comandi che eseguono un'azione su ogni oggetto in una pipeline.

Per altre informazioni, vedere about_PSItem.

$args

Contiene una matrice di valori per i parametri non dichiarati passati a una funzione, uno script o uno scriptblock. Quando si crea una funzione, è possibile dichiarare i parametri con la parola chiave param o aggiungendo un elenco delimitato da virgole di parametri tra parentesi dopo il nome della funzione.

In un'azione evento, la variabile $args contiene oggetti che rappresentano gli argomenti dell'evento in fase di elaborazione. Questa variabile viene popolata solo all'interno del blocco Action di un comando di registrazione eventi. Il valore di questa variabile è disponibile anche nella proprietà SourceArgs di dell'oggetto PSEventArgs che restituisce Get-Event.

$ConsoleFileName

Contiene il percorso del file della console (.psc1) usato più di recente nella sessione. Questa variabile viene popolata quando si avvia PowerShell con il parametro PSConsoleFile o quando si usa il cmdlet Export-Console per esportare i nomi degli snap-in in un file della console.

Quando si usa il cmdlet Export-Console senza parametri, aggiorna automaticamente il file della console usato più di recente nella sessione. È possibile usare questa variabile automatica per determinare il file da aggiornare.

$EnabledExperimentalFeatures

Contiene un elenco di nomi delle funzionalità sperimentali abilitate.

$Error

Contiene una matrice di oggetti errore che rappresentano gli errori più recenti. L'errore più recente è il primo oggetto di errore dell'array $Error[0].

Per impedire l'aggiunta di un errore alla matrice di $Error, utilizzare il parametro comune ErrorAction con un valore di Ignore. Per altre informazioni, vedere about_CommonParameters.

$Event

Contiene un oggetto PSEventArgs che rappresenta l'evento da elaborare. Questa variabile viene popolata solo all'interno del blocco Action di un comando di registrazione eventi, ad esempio Register-ObjectEvent. Il valore di questa variabile è lo stesso oggetto restituito dal cmdlet Get-Event. È possibile usare le proprietà della Event variabile, ad esempio $Event.TimeGenerated, in un Action blocco script.

$EventArgs

Contiene un oggetto che rappresenta il primo argomento evento che deriva da EventArgs dell'evento in fase di elaborazione. Questa variabile viene popolata solo all'interno del blocco Action di un comando di registrazione eventi. Il valore di questa variabile è disponibile anche nella proprietà SourceEventArgs dell'oggetto restituito .

$EventSubscriber

Contiene un oggetto PSEventSubscriber che rappresenta il sottoscrittore dell'evento in fase di elaborazione. Questa variabile viene popolata solo all'interno del blocco Action di un comando di registrazione eventi. Il valore di questa variabile è lo stesso oggetto restituito dal cmdlet Get-EventSubscriber.

$ExecutionContext

Contiene un oggetto EngineIntrinsics che rappresenta il contesto di esecuzione dell'host di PowerShell. È possibile usare questa variabile per trovare gli oggetti di esecuzione disponibili per i cmdlet.

$false

Contiene False. È possibile usare questa variabile per rappresentare false nei comandi e negli script anziché usare la stringa "false". La stringa può essere interpretata come True se viene convertita in una stringa non vuota o in un numero intero diverso da zero.

$foreach

Contiene l'enumeratore (non i valori risultanti) di un ciclo foreach. La variabile $foreach esiste solo durante l'esecuzione del ciclo foreach; viene eliminato dopo il completamento del ciclo.

Gli enumeratori contengono proprietà e metodi che è possibile usare per recuperare i valori del ciclo e modificare l'iterazione del ciclo corrente. Per altre informazioni, vedere Using Enumerators.

$HOME

Contiene il percorso completo della home directory dell'utente. In Windows questa variabile usa il valore della variabile di ambiente "$Env:USERPROFILE" Windows, in genere C:\Users\<UserName>. In Unix questa variabile usa il valore della variabile di ambiente HOME.

$Host

Contiene un oggetto che rappresenta l'applicazione host corrente per PowerShell. È possibile usare questa variabile per rappresentare l'host corrente nei comandi o per visualizzare o modificare le proprietà dell'host, ad esempio $Host.Version o $Host.CurrentCultureo $Host.UI.RawUI.BackGroundColor = "Red".

$input

Contiene un enumeratore che enumera tutti gli input passati a una funzione. La $input variabile è disponibile solo per funzioni, scriptblock (funzioni senza nome) e file di script (che sono scriptblock salvati).

• In una funzione senza un blocco begin, processo end, la variabile $input enumera la raccolta di tutti gli input per la funzione.

• Nel blocco begin la variabile $input non contiene dati.

• Nel blocco process la variabile $input contiene l'oggetto corrente nella pipeline.

• Nel blocco end la variabile $input enumera la raccolta di tutti gli input per la funzione.

  Nota

  Non è possibile usare la $input variabile all'interno del process blocco e del end blocco nella stessa funzione o scriptblock.

Poiché $input è un enumeratore, l'accesso a una delle relative proprietà determina la mancata disponibilità di $input. È possibile archiviare $input in un'altra variabile per riutilizzare le proprietà $input.

Gli enumeratori contengono proprietà e metodi che è possibile usare per recuperare i valori del ciclo e modificare l'iterazione del ciclo corrente. Per altre informazioni, vedere Using Enumerators.

La variabile $input è disponibile anche per il comando specificato dal parametro -Command di pwsh quando viene richiamato dalla riga di comando. L'esempio seguente viene eseguito dalla shell dei comandi di Windows.

echo Hello | pwsh -Command """$input World!"""

$IsCoreCLR

Contiene $true se la sessione corrente è in esecuzione nel runtime di .NET Core (CoreCLR). Altrimenti contiene $false.

$IsLinux

Contiene $true se la sessione corrente è in esecuzione in un sistema operativo Linux. Altrimenti contiene $false.

$IsMacOS

Contiene $true se la sessione corrente è in esecuzione in un sistema operativo macOS. Altrimenti contiene $false.

$IsWindows

Contiene $true se la sessione corrente è in esecuzione in un sistema operativo Windows. Altrimenti contiene $false.

$LASTEXITCODE

Contiene il codice di uscita dell'ultimo programma nativo o dello script di PowerShell eseguito.

Per gli script di PowerShell, il valore di $LASTEXITCODE dipende dal modo in cui è stato chiamato lo script e dal fatto che sia stata usata la parola chiave exit:

• Quando uno script usa la parola chiave exit:

  $LASTEXITCODE è impostato sul valore specificato dalla parola chiave exit. Per altre informazioni, vedere about_Language_Keywords.

• Quando uno script viene chiamato direttamente, ad esempio ./Test.ps1o con l'operatore di chiamata (&) come & ./Test.ps1:

  Il valore di $LASTEXITCODE non viene modificato a meno che:

  • Lo script chiama un altro script che usa la parola chiave exit
  • Lo script chiama un comando nativo
  • Lo script usa la parola chiave exit

• Quando viene chiamato uno script con usando il parametro file , è impostato su:

  • 1 se lo script è terminato a causa di un'eccezione
  • Valore specificato dalla parola chiave exit, se utilizzata nello script
  • 0 se lo script è stato completato correttamente

• Quando viene chiamato uno script con usando il parametro Command , è impostato su:

  • 1 se lo script è terminato per un'eccezione o se il risultato dell'ultimo comando ha impostato $? a $false
  • 0 se lo script è stato completato correttamente e il risultato dell'ultimo comando imposta $? a $true

Per altre informazioni sui parametri di File e Command, vedere about_Pwsh.

$Matches

La variabile $Matches funziona con gli operatori -match e -notmatch. Quando si invia input scalare all'operatore -match o -notmatch e uno rileva una corrispondenza, restituisce un valore booleano e popola la variabile automatica $Matches con una tabella hash di tutti i valori stringa corrispondenti. La tabella hash $Matches può essere popolata anche con acquisizioni quando si usano espressioni regolari con l'operatore -match.

Per altre informazioni sull'operatore -match, vedere informazioni sugli operatori di confronto. Per altre informazioni sulle espressioni regolari, vedere about_Regular_Expressions.

La variabile $Matches funziona anche in un'istruzione switch con il parametro -Regex. Viene popolato allo stesso modo degli operatori -match e -notmatch. Per ulteriori dettagli sull'istruzione switch, consultare about_Switch.

$MyInvocation

Contiene informazioni sul comando corrente, ad esempio il nome, i parametri, i valori dei parametri e informazioni sul modo in cui il comando è stato avviato, chiamato o richiamato, ad esempio il nome dello script che ha chiamato il comando corrente.

$MyInvocation viene popolato solo per script, funzioni e scriptblock. È possibile utilizzare le informazioni contenute nell'oggetto System.Management.Automation.InvocationInfo, che $MyInvocation restituisce nello script corrente, come il nome di una funzione ($MyInvocation.MyCommand.Name), per identificare il comando attuale. Ciò è utile per trovare il nome dello script corrente.

A partire da PowerShell 3.0, MyInvocation include le nuove proprietà seguenti.

• PSScriptRoot : contiene il percorso completo dello script che ha richiamato il comando corrente. Il valore di questa proprietà viene popolato solo quando il chiamante è uno script.
• PSCommandPath : contiene il percorso completo e il nome file dello script che ha richiamato il comando corrente. Il valore di questa proprietà viene popolato solo quando il chiamante è uno script.

A differenza delle variabili automatiche $PSScriptRoot e $PSCommandPath, le proprietà PSScriptRoot e PSCommandPath della variabile automatica $MyInvocation contengono informazioni sul invoker o sullo script chiamante, non sullo script corrente.

$NestedPromptLevel

Contiene il livello di richiesta corrente. Un valore di 0 indica il livello di prompt originale. Il valore viene incrementato quando si immette un livello annidato e decrementato quando se ne esce.

Ad esempio, PowerShell presenta un prompt dei comandi annidato quando si usa il metodo $Host.EnterNestedPrompt. PowerShell presenta anche un prompt dei comandi annidato quando si raggiunge un punto di interruzione nel debugger di PowerShell.

Quando si immette un prompt annidato, PowerShell sospende il comando corrente, salva il contesto di esecuzione e incrementa il valore della variabile $NestedPromptLevel. Per creare altri prompt dei comandi annidati (fino a 128 livelli) o per tornare al prompt dei comandi originale, completare il comando o digitare exit.

La variabile $NestedPromptLevel consente di tenere traccia del livello di richiesta. È possibile creare un prompt dei comandi di PowerShell alternativo che includa questo valore in modo che sia sempre visibile.

$null

è una variabile automatica che contiene un null o un valore vuoto. È possibile usare questa variabile per rappresentare un valore assente o non definito nei comandi e negli script.

PowerShell considera $null come oggetto con un valore o un segnaposto, in modo da poter usare $null per rappresentare un valore vuoto in una raccolta di valori.

Ad esempio, quando $null è incluso in una raccolta, viene conteggiato come uno degli oggetti .

$a = "one", $null, "three"
$a.Count

3

Se si invia tramite pipe la variabile $null al cmdlet ForEach-Object, viene generato un valore per $null, come avviene per gli altri oggetti

"one", $null, "three" | ForEach-Object {"Hello " + $_}

Hello one
Hello
Hello three

Di conseguenza, non è possibile usare $null per indicare nessun valore di parametro. Un valore del parametro di $null sostituisce il valore del parametro predefinito.

Tuttavia, poiché PowerShell considera la variabile $null come segnaposto, è possibile usarla in script come quello seguente, che non funzionerebbe se $null siano stati ignorati.

$calendar = @($null, $null, "Meeting", $null, $null, "Team Lunch", $null)
$days = "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
        "Friday", "Saturday"
$currentDay = 0
foreach($day in $calendar)
{
    if($day -ne $null)
    {
        "Appointment on $($days[$currentDay]): $day"
    }

    $currentDay++
}

Appointment on Tuesday: Meeting
Appointment on Friday: Team lunch

$PID

Contiene l'identificatore del processo (PID) del processo che ospita la sessione corrente di PowerShell.

$PROFILE

Contiene il percorso completo del profilo di PowerShell per l'utente corrente e l'applicazione host corrente. È possibile usare questa variabile per rappresentare il profilo nei comandi. Ad esempio, è possibile usarlo in un comando per determinare se è stato creato un profilo:

Test-Path $PROFILE

In alternativa, è possibile usarlo in un comando per creare un profilo:

New-Item -ItemType File -Path $PROFILE -Force

È possibile usarlo in un comando per aprire il profilo in notepad.exe:

notepad.exe $PROFILE

$PSBoundParameters

Contiene un dizionario dei parametri passati a uno script o a una funzione e ai relativi valori correnti. Questa variabile ha un valore solo in un ambito in cui vengono dichiarati i parametri, ad esempio uno script o una funzione. È possibile usarlo per visualizzare o modificare i valori correnti dei parametri o per passare i valori dei parametri a un altro script o funzione.

In questo esempio, la funzione Test2 passa il $PSBoundParameters alla funzione Test1. I vengono visualizzati nel formato Chiave di e Valoredi .

function Test1 {
   param($a, $b)

   # Display the parameters in dictionary format.
   $PSBoundParameters
}

function Test2 {
   param($a, $b)

   # Run the Test1 function with $a and $b.
   Test1 @PSBoundParameters
}

Test2 -a Power -b Shell

Key   Value
---   -----
a     Power
b     Shell

$PSCmdlet

Contiene un oggetto che rappresenta il cmdlet o la funzione avanzata in esecuzione.

È possibile utilizzare le proprietà e i metodi dell'oggetto nel cmdlet o nel codice della funzione per rispondere alle condizioni di utilizzo. Ad esempio, la proprietà ParameterSetName contiene il nome del set di parametri in uso e il metodo ShouldProcess aggiunge i parametri WhatIf e Confirm al cmdlet in modo dinamico.

Per altre informazioni sulla variabile automatica $PSCmdlet, vedere about_Functions_CmdletBindingAttribute e about_Functions_Advanced.

$PSCommandPath

Contiene il percorso completo e il nome file dello script in esecuzione. Questa variabile è valida in tutti gli script.

$PSCulture

A partire da PowerShell 7, $PSCulture riflette le impostazioni cultura dello spazio di esecuzione corrente di PowerShell (sessione). Se la cultura viene cambiata in uno spazio di esecuzione di PowerShell, il valore $PSCulture per quello spazio di esecuzione viene aggiornato.

La cultura determina il formato di visualizzazione degli elementi, ad esempio numeri, valuta e date, e viene archiviata in un oggetto System.Globalization.CultureInfo. Usare Get-Culture per visualizzare le impostazioni culturali del computer. $PSCulture contiene il valore della proprietà Nome .

$PSDebugContext

Durante il debug, questa variabile contiene informazioni sull'ambiente di debug. In caso contrario, contiene un valore di null . Di conseguenza, è possibile usarlo per determinare se il debugger dispone di controllo. Quando è popolato, contiene un oggetto PsDebugContext che ha le proprietà Breakpoints e InvocationInfo. La proprietà InvocationInfo include diverse proprietà utili, tra cui la proprietà Location. La proprietà Location indica il percorso dello script di cui viene eseguito il debug.

$PSEdition

Contiene lo stesso valore in $PSVersionTable.PSEdition. Questa variabile è disponibile per l'uso nei file manifesto del modulo, mentre $PSVersionTable non è .

$PSHOME

Contiene il percorso completo della directory di installazione per PowerShell, in genere C:\Program Files\PowerShell\7 nei sistemi Windows. È possibile usare questa variabile nei percorsi dei file di PowerShell. Ad esempio, il comando seguente cerca negli argomenti della Guida concettuale la parola Guida:

Select-String -Pattern Help -Path $PSHOME\en-US\*.txt

$PSItem

Uguale a $_. Contiene l'oggetto corrente all'interno dell'oggetto della pipeline. È possibile usare questa variabile nei comandi che eseguono un'azione su ogni oggetto in una pipeline.

Per altre informazioni, vedere about_PSItem.

$PSScriptRoot

Contiene il percorso completo della directory madre dello script in esecuzione.

In PowerShell 2.0 questa variabile è valida solo nei moduli di script (.psm1). A partire da PowerShell 3.0, è valido in tutti gli script.

$PSSenderInfo

Contiene informazioni sull'utente che ha avviato la sessione PSSession, inclusi l'identità utente e il fuso orario del computer di origine. Questa variabile è disponibile solo in PSSessions.

La variabile $PSSenderInfo include una proprietà configurabile dall'utente, ApplicationArguments, che per impostazione predefinita contiene solo il $PSVersionTable dalla sessione di origine. Per aggiungere dati alla proprietà ApplicationArguments , utilizzare il parametro ApplicationArguments del cmdlet New-PSSessionOption.

$PSUICulture

Contiene il nome della cultura dell'interfaccia utente configurata nel sistema operativo. La cultura dell'interfaccia utente determina quali stringhe di testo vengono utilizzate per gli elementi dell'interfaccia utente, come menu e messaggi. Si tratta del valore della proprietà System.Globalization.CultureInfo.CurrentUICulture.Name del sistema. Per ottenere l'oggetto System.Globalization.CultureInfo per il sistema, utilizzare il cmdlet .

$PSVersionTable

Contiene una tabella hash di sola lettura che visualizza i dettagli sulla versione di PowerShell in esecuzione nella sessione corrente. La tabella include gli elementi seguenti:

• PSVersion - Numero di versione di PowerShell
• PSEdition Questa proprietà ha il valore di "Desktop" per PowerShell 4 e versioni successive, nonché di PowerShell 5.1 nelle edizioni di Windows complete. Questa proprietà ha il valore di Core per PowerShell 6 e versioni successive, nonché di Windows PowerShell 5.1 in edizioni con footprint ridotto, ad esempio Windows Nano Server o Windows IoT.
• GitCommitId - L'ID del commit dei file di origine su GitHub,
• OS - Descrizione del sistema operativo su cui è in esecuzione PowerShell.
• Platform : piattaforma in cui è in esecuzione il sistema operativo. Il valore in Linux e macOS è Unix. Vedere $IsMacOS e $IsLinux.
• PSCompatibleVersions - Versioni di PowerShell compatibili con la versione corrente
• PSRemotingProtocolVersion: versione del protocollo di gestione remota di PowerShell.
• SerializationVersion : versione del metodo di serializzazione
• WSManStackVersion - Numero di versione dello stack di WS-Management

$PWD

Contiene un oggetto path che rappresenta il percorso completo della directory per l'ambiente di esecuzione corrente di PowerShell.

$Sender

Contiene l'oggetto che ha generato questo evento. Questa variabile viene popolata solo all'interno del blocco Azione di un comando di registrazione eventi. Il valore di questa variabile può essere trovato anche nella proprietà Sender dell'oggetto PSEventArgs che Get-Event restituisce.

$ShellId

Contiene l'identificatore della shell corrente.

$StackTrace

Contiene un'analisi dello stack per l'errore più recente.

$switch

Contiene l'enumeratore non i valori risultanti di un'istruzione switch. La variabile $switch esiste solo quando l'istruzione switch è in esecuzione; viene eliminato quando l'istruzione switch completa l'esecuzione. Per altre informazioni, vedere about_Switch.

Gli enumeratori contengono proprietà e metodi che è possibile usare per recuperare i valori del ciclo e modificare l'iterazione del ciclo corrente. Per altre informazioni, vedere Using Enumerators.

$this

La $this variabile viene usata in scriptblock che estendono le classi per fare riferimento all'istanza della classe stessa.

Il sistema ETS (Extensible Type System) di PowerShell consente di aggiungere proprietà alle classi usando scriptblock. In uno scriptblock che definisce una proprietà script o un metodo di script, la $this variabile fa riferimento a un'istanza dell'oggetto della classe che viene estesa. Ad esempio, PowerShell usa ETS per aggiungere la proprietà BaseName alla classe FileInfo .

PS> Get-ChildItem .\README.md | Get-Member BaseName | Format-List

TypeName   : System.IO.FileInfo
Name       : BaseName
MemberType : ScriptProperty
Definition : System.Object BaseName {get=if ($this.Extension.Length -gt 0)
             {$this.Name.Remove($this.Name.Length - $this.Extension.Length
             )}else{$this.Name};}

Per altre informazioni, vedere about_Types.ps1xml.

In una classe Di PowerShell, la variabile $this fa riferimento all'oggetto istanza della classe stessa, consentendo l'accesso alle proprietà e ai metodi definiti nella classe . Per altre informazioni, vedere about_Classes.

La $this variabile viene usata anche dalle classi di evento .NET che accettano scriptblock come delegati per il gestore eventi. In questo scenario, $this rappresenta l'oggetto che ha origine l'evento, noto come mittente dell'evento.

$true

Contiene true. È possibile usare questa variabile per rappresentare True nei comandi e negli script.

Uso di enumeratori

Le variabili $input, $foreache $switch sono tutti enumeratori usati per scorrere i valori elaborati dal blocco di codice contenitore.

Un enumeratore contiene proprietà e metodi che è possibile usare per avanzare o reimpostare l'iterazione o recuperare i valori di iterazione. La modifica diretta degli enumeratori non è considerata una procedura consigliata.

• All'interno dei cicli, le parole chiave del controllo di flusso break e continue sono preferite.

• All'interno di funzioni che accettano l'input della pipeline, è consigliabile usare parametri con gli attributi ValueFromPipeline o ValueFromPipelineByPropertyName.

  Per altre informazioni, vedere about_Functions_Advanced_Parameters.

VaiAvanti

Il metodo MoveNext sposta l'enumeratore all'elemento successivo della raccolta. MoveNext restituisce True se l'enumeratore è avanzato con successo, False se l'enumeratore ha oltrepassato la fine della raccolta.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

Il metodo Reset imposta l'enumeratore sulla posizione iniziale, che viene prima di il primo elemento della raccolta.

Current

La proprietà Current ottiene l'elemento nella raccolta o nella pipeline, nella posizione corrente dell'enumeratore.

La proprietà Current continua a restituire la stessa proprietà finché non viene invocato il metodo MoveNext.

Esempi

Esempio 1: Uso della variabile $input

Nell'esempio seguente, l'accesso alla variabile $input cancella la variabile fino alla successiva esecuzione del blocco di processo. L'uso del metodo Reset reimposta la variabile $input sul valore della pipeline corrente.

function Test
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tInput: $input"
        "`tAccess Again: $input"
        $input.Reset()
        "`tAfter Reset: $input"
    }
}

"one","two" | Test

Iteration: 0
    Input: one
    Access Again:
    After Reset: one
Iteration: 1
    Input: two
    Access Again:
    After Reset: two

Il blocco di processo avanza automaticamente la variabile $input anche se non si accede.

$skip = $true
function Skip
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        if ($skip)
        {
            "`tSkipping"
            $skip = $false
        }
        else
        {
            "`tInput: $input"
        }
    }
}

"one","two" | Skip

Iteration: 0
    Skipping
Iteration: 1
    Input: two

Esempio 2: Uso di $input all'esterno del blocco di processo

All'esterno del blocco del processo, la variabile $input rappresenta tutti i valori inviati tramite pipe alla funzione.

• L'accesso alla variabile $input cancella tutti i valori.
• Il metodo Reset reimposta l'intera raccolta.
• La proprietà Current non viene mai popolata.
• Il metodo MoveNext restituisce false perché la raccolta non può essere avanzata.
  • La chiamata a MoveNext cancella la variabile $input.

Function All
{
    "All Values: $input"
    "Access Again: $input"
    $input.Reset()
    "After Reset: $input"
    $input.MoveNext() | Out-Null
    "After MoveNext: $input"
}

"one","two","three" | All

All Values: one two three
Access Again:
After Reset: one two three
After MoveNext:

Esempio 3: uso della proprietà $input.Current

Con la proprietà Current, è possibile accedere più volte al valore della pipeline corrente senza usare il metodo Reset. Il blocco di processo non chiama automaticamente il metodo MoveNext .

La proprietà Current non viene mai popolata a meno che non venga chiamata esplicitamente MoveNext. È possibile accedere alla proprietà Current più volte all'interno del blocco di processo senza cancellarne il valore.

function Current
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tBefore MoveNext: $($input.Current)"
        $input.MoveNext() | Out-Null
        "`tAfter MoveNext: $($input.Current)"
        "`tAccess Again: $($input.Current)"
    }
}

"one","two" | Current

Iteration: 0
    Before MoveNext:
    After MoveNext: one
    Access Again: one
Iteration: 1
    Before MoveNext:
    After MoveNext: two
    Access Again: two

Esempio 4: Uso della variabile $foreach

A differenza della variabile $input, la variabile $foreach rappresenta sempre tutti gli elementi della raccolta quando si accede direttamente. Utilizzare la proprietà Current per accedere all'elemento della raccolta corrente e i metodi Reset e MoveNext per modificarne il valore.

Il ciclo seguente viene eseguito solo due volte. Nella seconda iterazione, la raccolta viene spostata nel terzo elemento prima del completamento dell'iterazione. Dopo la seconda iterazione, non sono ora disponibili altri valori per l'iterazione e il ciclo termina.

La proprietà MoveNext non influisce sulla variabile scelta per scorrere l'insieme ().

$i = 0
foreach ($num in ("one","two","three"))
{
    "Iteration: $i"
    $i++
    "`tNum: $num"
    "`tCurrent: $($foreach.Current)"

    if ($foreach.Current -eq "two")
    {
        "Before MoveNext (Current): $($foreach.Current)"
        $foreach.MoveNext() | Out-Null
        "After MoveNext (Current): $($foreach.Current)"
        "Num hasn't changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num hasn't changed: two

L'utilizzo del metodo Reset reimposta l'elemento corrente nella raccolta. Nell'esempio seguente vengono attraversati i primi due elementi due volte poiché viene chiamato il metodo Reset. Dopo i primi due cicli, l'istruzione if fallisce e il ciclo scorre normalmente attraverso tutti e tre gli elementi.

$stopLoop = 0
foreach ($num in ("one","two", "three"))
{
    ("`t" * $stopLoop) + "Current: $($foreach.Current)"

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset()
        ("`t" * $stopLoop) + "Reset Loop: $stopLoop"
        $stopLoop++
    }
}

Current: one
Current: two
Reset Loop: 0
        Current: one
        Current: two
        Reset Loop: 1
                Current: one
                Current: two
                Current: three

Esempio 5: Uso della variabile $switch

La variabile $switch ha le stesse regole della variabile $foreach. Nell'esempio seguente vengono illustrati tutti i concetti dell'enumeratore.

$values = "Start", "MoveNext", "NotEvaluated", "Reset", "End"
$stopInfinite = $false
switch ($values)
{
    "MoveNext" {
        "`tMoveNext"
        $switch.MoveNext() | Out-Null
        "`tAfter MoveNext: $($switch.Current)"
    }
    # This case is never evaluated.
    "NotEvaluated" {
        "`tAfterMoveNext: $($switch.Current)"
    }

    "Reset" {
        if (!$stopInfinite)
        {
            "`tReset"
            $switch.Reset()
            $stopInfinite = $true
        }
    }

    default {
        "Default (Current): $($switch.Current)"
    }
}

Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
    Reset
Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
Default (Current): End

Vedere anche

• informazioni_sulle_Funzioni
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_OutputTypeAttribute
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Splatting
• about_Variables