about_Automatic_Variables

Articolo
11/06/2024

Descrizione breve

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

Concettualmente, la maggior parte di queste variabili viene considerata di sola lettura. Anche se possono essere scritti in, per la compatibilità con le versioni precedenti non devono essere scritti in .

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

Descrizione lunga

$$

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 in entrambi process i blocchi, end chiamando this.WriteError() o $PSCmdlet.WriteError() rispettivamente in qualsiasi punto imposta $? su False, come e this.ThrowTerminatingError() $PSCmdlet.ThrowTerminatingError().

Il Write-Error cmdlet imposta $? sempre su False immediatamente dopo l'esecuzione, ma non viene impostato 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, $PSCmdlet.WriteError() è consigliabile usare invece .

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

Nota

Fino a PowerShell 7, il wrapping di un'istruzione tra parentesi (...), la sintassi $(...)di sottoespressione o un'espressione @(...) di matrice sempre reset$? su True. Ad esempio, (Write-Error) viene visualizzato $? come True. Questo comportamento è cambiato in PowerShell 7, in modo che $? rifletta sempre l'esito effettivo dell'ultima esecuzione del comando in queste espressioni.

$^

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

$_

Uguale a $PSItem. Contiene l'oggetto current nell'oggetto 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 un blocco di script. Quando si crea una funzione, è possibile dichiarare i parametri con la param parola chiave o aggiungendo un elenco delimitato da virgole di parametri tra parentesi dopo il nome della funzione.

In un'azione evento la $args variabile contiene oggetti che rappresentano gli argomenti dell'evento in fase di elaborazione. Questa variabile viene popolata solo all'interno del Action blocco di un comando di registrazione eventi. Il valore di questa variabile è disponibile anche nella proprietà SourceArgs dell'oggetto PSEventArgs restituito 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 Export-Console cmdlet per esportare i nomi snap-in in in un file della console.

Quando si usa il Export-Console cmdlet 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 errore nella matrice $Error[0].

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

$Event

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

$EventSubscriber

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

$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 intero diverso da zero.

$foreach

Contiene l'enumeratore (non i valori risultanti) di un ciclo ForEach . La $ForEach variabile esiste solo durante l'esecuzione del ForEach ciclo, che viene eliminata al termine del ciclo.

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

$HOME

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

Importante

Windows può reindirizzare la posizione del profilo dell'utente. Ciò significa che $HOME potrebbe non avere lo stesso valore di "$env:HOMEDRIVE$env:HOMEPATH".

$Host

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

Nota

Le impostazioni dei colori in $Host.PrivateData sono state sostituite dalla $PSStyle variabile di preferenza. Per altre informazioni, vedere about_ANSI_Terminals.

$input

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

In una funzione senza un beginblocco , processo end la $input variabile enumera la raccolta di tutti gli input per la funzione.
begin Nel blocco la $input variabile non contiene dati.
process Nel blocco la $input variabile contiene l'oggetto current nella pipeline.
end Nel blocco la $input variabile 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 blocco di script.

Poiché $input è un enumeratore, l'accesso a una delle relative proprietà non $input è più disponibile. È possibile archiviare $input in un'altra variabile per riutilizzare le $input proprietà.

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

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

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

$IsCoreCLR

Contiene $true se la current sessione è in esecuzione nel runtime di .NET Core (CoreCLR). In caso contrario, contiene $false.

$IsLinux

Contiene $true se la current sessione è in esecuzione in un sistema operativo Linux. In caso contrario, contiene $false.

$IsMacOS

Contiene $true se la current sessione è in esecuzione in un sistema operativo MacOS. In caso contrario, contiene $false.

$IsWindows

Contiene $true se la current sessione è in esecuzione in un sistema operativo Windows. In caso contrario, 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 la exit parola chiave sia stata usata:

Quando uno script usa la exit parola chiave :

$LASTEXITCODE è impostato sul valore specificato dalla exit parola chiave . 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 exit parola chiave
- Lo script chiama un comando nativo
- Lo script usa la exit parola chiave
Quando uno script viene chiamato con pwsh usando il parametro File , $LASTEXITCODE è impostato su:
- 1 se lo script è terminato a causa di un'eccezione
- Valore specificato dalla exit parola chiave , se usato nello script
- 0 se lo script è stato completato correttamente
Quando viene chiamato uno script con pwsh usando il parametro Command , $LASTEXITCODE è impostato su:
- 1se lo script è terminato a causa di un'eccezione o se il risultato dell'ultimo comando impostato su $?$false
- 0se lo script è stato completato correttamente e il risultato dell'ultimo set di comandi su $?$true

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

$Matches

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

Per altre informazioni sull'operatore -match , vedere about_Comparison_Operators. Per altre informazioni sulle espressioni regolari, vedere about_Regular_Expressions.

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

Nota

Quando $Matches viene popolato in una sessione, mantiene il valore corrispondente fino a quando non viene sovrascritto da un'altra corrispondenza. Se -match viene usato di nuovo e non viene trovata alcuna corrispondenza, non reset$Matches viene trovata in $null. Il valore corrispondente in precedenza viene mantenuto in $Matches finché non viene trovata un'altra corrispondenza.

$MyInvocation

Contiene informazioni sul current comando, ad esempio il nome, i parametri, i valori dei parametri e le informazioni su come il comando è stato avviato, chiamato o richiamato, ad esempio il nome dello script che ha chiamato il current comando.

$MyInvocation viene popolato solo per script, funzioni e blocchi di script. È possibile usare le informazioni nell'oggetto System.Management.Automation.InvocationInfo restituito $MyInvocation nello current script, ad esempio il nome di una funzione ($MyInvocation.MyCommand.Name) per identificare il current comando. Ciò è utile per trovare il nome dello current script.

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

PSScriptRoot : contiene il percorso completo dello script che ha richiamato il current comando. 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 current comando. Il valore di questa proprietà viene popolato solo quando il chiamante è uno script.

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

$NestedPromptLevel

Contiene il current livello di richiesta. Il valore 0 indica il livello di richiesta originale. Il valore viene incrementato quando si immette un livello annidato e decrementato quando lo si esce.

Ad esempio, PowerShell presenta un prompt dei comandi annidato quando si usa il $Host.EnterNestedPrompt metodo . 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 current comando, salva il contesto di esecuzione e incrementa il valore della $NestedPromptLevel variabile. Per creare prompt dei comandi annidati aggiuntivi (fino a 128 livelli) o per tornare al prompt dei comandi originale, completare il comando o digitare exit.

La $NestedPromptLevel variabile 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

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

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

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

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

Se si invia tramite pipe la $null variabile al ForEach-Object cmdlet , 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 alcun valore di parametro. Un valore di parametro di $null esegue l'override del valore del parametro predefinito.

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

$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 current sessione di PowerShell.

$PROFILE

Contiene il percorso completo del profilo di PowerShell per l'utente current e l'applicazione current host. È 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 i relativi current valori. 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 current valori dei parametri o per passare i valori dei parametri a un altro script o funzione.

In questo esempio la funzione Test2 passa alla $PSBoundParameters funzione Test1. Vengono $PSBoundParameters visualizzati nel formato Chiave e Valore.

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 utilizzato e il metodo ShouldProcess aggiunge i parametri WhatIf e Confirm al cmdlet in modo dinamico.

Per altre informazioni sulla $PSCmdlet variabile automatica, 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 di current PowerShell (sessione). Se le impostazioni cultura vengono modificate in uno spazio di esecuzione di PowerShell, il $PSCulture valore per tale spazio di esecuzione viene aggiornato.

Le impostazioni cultura determinano il formato di visualizzazione degli elementi, ad esempio numeri, valuta e date, e vengono archiviati in un oggetto System.Globalization.CultureInfo . Utilizzare Get-Culture per visualizzare le impostazioni cultura del computer. $PSCulture contiene il valore della proprietà Name .

$PSDebugContext

Durante il debug, questa variabile contiene informazioni sull'ambiente di debug. In caso contrario, contiene un valore Null . Di conseguenza, è possibile usarlo per determinare se il debugger dispone di controllo. Se popolato, contiene un oggetto PsDebugContext con 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 è in corso il debug.

$PSEdition

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

$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 current nell'oggetto 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 padre 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 $PSSenderInfo variabile include una proprietà configurabile dall'utente, ApplicationArguments, che per impostazione predefinita contiene solo l'oggetto $PSVersionTable della sessione di origine. Per aggiungere dati alla proprietà ApplicationArguments , utilizzare il parametro ApplicationArguments del New-PSSessionOption cmdlet .

$PSUICulture

Contiene il nome delle impostazioni cultura dell'interfaccia utente configurate nel sistema operativo. Le impostazioni cultura dell'interfaccia utente determinano quali stringhe di testo vengono usate per gli elementi dell'interfaccia utente, ad esempio 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 Get-UICulture cmdlet .

$PSVersionTable

Contiene una tabella hash di sola lettura che visualizza i dettagli sulla versione di PowerShell in esecuzione nella current sessione. 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 e 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 : ID commit dei file di origine, in GitHub,
Sistema operativo : Descrizione del sistema operativo in cui è in esecuzione PowerShell.
Piattaforma : piattaforma in cui è in esecuzione il sistema operativo. Il valore in Linux e macOS è Unix. Controllare $IsMacOs e $IsLinux.
PSCompatibleVersions - Versioni di PowerShell compatibili con la current versione
PSRemotingProtocolVersion : versione del protocollo di gestione remota di PowerShell.
SerializationVersion : versione del metodo di serializzazione
WSManStackVersion : numero di versione dello stack WS-Management

$PWD

Contiene un oggetto path che rappresenta il percorso completo del percorso della current directory per lo current spazio di esecuzione di PowerShell.

Nota

PowerShell supporta più spazi di esecuzione per processo. Ogni spazio di esecuzione ha una propria current directory. Non è uguale alla current directory del processo: [System.Environment]::CurrentDirectory.

$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 è disponibile anche nella proprietà Sender dell'oggetto PSEventArgs restituito Get-Event .

$ShellId

Contiene l'identificatore della current shell.

$StackTrace

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

$switch

Contiene l'enumeratore non i valori risultanti di un'istruzione Switch . La $switch variabile esiste solo quando l'istruzione Switch è in esecuzione, viene eliminata al termine dell'esecuzione dell'istruzione switch . 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 current ciclo. Per altre informazioni, vedere Uso di enumeratori.

$this

La $this variabile viene usata nei blocchi di script 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 blocchi di script. In un blocco di script che definisce una proprietà script o un metodo script, la $this variabile fa riferimento a un'istanza di 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 PowerShell, la $this variabile 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 blocchi di script come delegati per il gestore eventi. In questo scenario rappresenta $this 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 $inputvariabili , $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 reset iterare o recuperare i valori di iterazione. La modifica diretta degli enumeratori non è considerata una procedura consigliata.

All'interno di cicli, le parole chiave del controllo di flusso interrompono e continuano devono essere preferite.
All'interno di funzioni che accettano l'input della pipeline, è consigliabile usare i parametri con gli attributi ValueFromPipeline o ValueFromPipelineByPropertyName .

Per altre informazioni, vedere about_Functions_Advanced_Parameters.

MoveNext

Il metodo MoveNext sposta l'enumeratore all'elemento successivo della raccolta. MoveNext restituisce True se l'enumeratore è stato avanzato correttamente, False se l'enumeratore ha superato la fine della raccolta.

Nota

Il valore booleano restituito da MoveNext viene inviato al flusso di output. È possibile eliminare l'output digitandolo [void] o inviandolo tramite pipe a Out-Null.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

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

Current

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

La Current proprietà continua a restituire la stessa proprietà finché non viene chiamato MoveNext .

Esempi

Esempio 1: Uso della variabile $input

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

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 sposta automaticamente la $input variabile 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 $input variabile rappresenta tutti i valori inviati tramite pipe alla funzione.

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

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 del $input.Current proprietà

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

La Current proprietà non viene mai popolata a meno che non si chiami in modo esplicito MoveNext. È Current possibile accedere alla proprietà 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 $input variabile, la $foreach variabile rappresenta sempre tutti gli elementi della raccolta quando si accede direttamente. Utilizzare la Current proprietà per accedere all'elemento current della raccolta e i Reset metodi MoveNext per modificarne il valore.

Nota

Ogni iterazione del foreach ciclo chiama automaticamente il metodo MoveNext .

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 la raccolta ($Num).

$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 Reset metodo reimposta l'elemento current nella raccolta. Nell'esempio seguente vengono scorrere i primi due elementi due volte perché viene chiamato il Reset metodo . Dopo i primi due cicli, l'istruzione if ha esito negativo e il ciclo scorre normalmente tutti e tre gli elementi.

Importante

Ciò potrebbe comportare un ciclo infinito.

$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 $switch variabile ha le stesse regole della $foreach variabile. Nell'esempio seguente vengono illustrati tutti i concetti dell'enumeratore.

Nota

Si noti che il caso NotEvaluated non viene mai eseguito, anche se non è presente alcuna break istruzione dopo il metodo MoveNext .

$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

Condividi tramite

about_Automatic_Variables

Descrizione breve

Descrizione lunga

$$

$?

$^

$_

$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

Uso di enumeratori

MoveNext

Reset

Current

Esempi

Esempio 1: Uso della variabile $input

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

Esempio 3: uso del $input.Current proprietà

Esempio 4: Uso della variabile $foreach

Esempio 5: Uso della variabile $switch

Vedi anche

Risorse aggiuntive