Informationen zu automatischen Variablen

Kurze Beschreibung

Beschreibt Variablen, die Zustandsinformationen für PowerShell speichern. Diese Variablen werden von PowerShell erstellt und verwaltet.

Lange Beschreibung

Vom Konzept her gelten diese Variablen als schreibgeschützt. Obwohl sie in geschrieben werden können , sollten sie aus Gründen der Abwärtskompatibilität nicht in geschrieben werden.

Hier ist eine Liste der automatischen Variablen in PowerShell:

$$

Enthält das letzte Token in der letzten Zeile, die von der Sitzung empfangen wurde.

$?

Enthält die Ausführung status des letzten Befehls. Es enthält True , wenn der letzte Befehl erfolgreich war, und False , wenn er fehlgeschlagen ist.

Für Cmdlets und erweiterte Funktionen, die in mehreren Phasen in einer Pipeline ausgeführt werden, z. B. in beiden process Blöcken und end , wird der Aufruf this.WriteError() bzw$PSCmdlet.WriteError(). zu einem beliebigen Zeitpunkt auf False festgelegt$?, ebenso wie this.ThrowTerminatingError() und $PSCmdlet.ThrowTerminatingError().

Das Write-Error Cmdlet legt $? immer sofort nach der Ausführung auf False fest, wird aber für eine Funktion, die es aufruft, nicht auf False festgelegt$?:

function Test-WriteError
{
    Write-Error "Bad"
    $? # $false
}

Test-WriteError
$? # $true

Zu letzterem Zweck sollte stattdessen $PSCmdlet.WriteError() verwendet werden.

Für native Befehle (ausführbare Dateien) $? ist auf True festgelegt, wenn $LASTEXITCODE 0 ist, und auf False festgelegt, wenn $LASTEXITCODE ein anderer Wert ist.

Hinweis

Bis PowerShell 7, die eine Anweisung in Klammern (...)enthält, wird die Teilausdruckssyntax $(...) oder der Arrayausdruck @(...) immer auf True zurückgesetzt$?, sodass (Write-Error)true angezeigt wird$?. Dies wurde in PowerShell 7 geändert, sodass $? dies immer den tatsächlichen Erfolg der letzten Befehlsausführung in diesen Ausdrücken widerspiegelt.

$^

Enthält das erste Token in der letzten Zeile, die von der Sitzung empfangen wurde.

$_

Wie in $PSItem. Enthält das aktuelle Objekt im Pipelineobjekt. Sie können diese Variable in Befehlen verwenden, die eine Aktion für jedes Objekt oder für ausgewählte Objekte in einer Pipeline ausführen.

$args

Enthält ein Array von Werten für nicht deklarierte Parameter, die an eine Funktion, ein Skript oder einen Skriptblock übergeben werden. Wenn Sie eine Funktion erstellen, können Sie die Parameter mithilfe des param Schlüsselwort (keyword) deklarieren oder eine durch Trennzeichen getrennte Liste von Parametern in Klammern nach dem Funktionsnamen hinzufügen.

In einer Ereignisaktion enthält die $Args Variable Objekte, die die Ereignisargumente des zu verarbeitenden Ereignisses darstellen. Diese Variable wird nur innerhalb des Action Blocks eines Ereignisregistrierungsbefehls aufgefüllt. Der Wert dieser Variablen befindet sich auch in der SourceArgs-Eigenschaft des psEventArgs-Objekts , das Get-Event zurückgibt.

$ConsoleFileName

Enthält den Pfad der Konsolendatei (.psc1), die zuletzt in der Sitzung verwendet wurde. Diese Variable wird aufgefüllt, wenn Sie PowerShell mit dem PSConsoleFile-Parameter starten oder wenn Sie das Export-Console Cmdlet verwenden, um Snap-In-Namen in eine Konsolendatei zu exportieren.

Wenn Sie das Export-Console Cmdlet ohne Parameter verwenden, wird automatisch die Konsolendatei aktualisiert, die zuletzt in der Sitzung verwendet wurde. Sie können diese automatische Variable verwenden, um zu bestimmen, welche Datei aktualisiert wird.

$Error

Enthält ein Array von Fehlerobjekten, die die neuesten Fehler darstellen. Der letzte Fehler ist das erste Fehlerobjekt im Array $Error[0].

Um zu verhindern, dass dem $Error Array ein Fehler hinzugefügt wird, verwenden Sie den allgemeinen ErrorAction-Parameter mit dem Wert Ignore. Weitere Informationen findest du unter about_CommonParameters.

$Event

Enthält ein PSEventArgs-Objekt , das das verarbeitete Ereignis darstellt. Diese Variable wird nur innerhalb des Action Blocks eines Ereignisregistrierungsbefehls aufgefüllt, z Register-ObjectEvent. B. . Der Wert dieser Variablen ist dasselbe Objekt, das vom Get-Event Cmdlet zurückgegeben wird. Daher können Sie die Eigenschaften der Event Variablen, z $Event.TimeGenerated. B. , in einem Action Skriptblock verwenden.

$EventArgs

Enthält ein -Objekt, das das erste Ereignisargument darstellt, das von EventArgs des zu verarbeitenden Ereignisses abgeleitet wird. Diese Variable wird nur innerhalb des Action Blocks eines Ereignisregistrierungsbefehls aufgefüllt. Der Wert dieser Variablen befindet sich auch in der SourceEventArgs-Eigenschaft des psEventArgs-Objekts , das Get-Event zurückgibt.

$EventSubscriber

Enthält ein PSEventSubscriber-Objekt , das den Ereignisabonnent des zu verarbeitenden Ereignisses darstellt. Diese Variable wird nur innerhalb des Action Blocks eines Ereignisregistrierungsbefehls aufgefüllt. Der Wert dieser Variablen ist dasselbe Objekt, das vom Get-EventSubscriber Cmdlet zurückgegeben wird.

$ExecutionContext

Enthält ein EngineIntrinsics-Objekt , das den Ausführungskontext des PowerShell-Hosts darstellt. Sie können diese Variable verwenden, um die Ausführungsobjekte zu finden, die für Cmdlets verfügbar sind.

$false

Enthält False. Sie können diese Variable verwenden, um False in Befehlen und Skripts darzustellen, anstatt die Zeichenfolge "false" zu verwenden. Die Zeichenfolge kann als True interpretiert werden, wenn sie in eine nicht leere Zeichenfolge oder in eine ganze Zahl ungleich Null konvertiert wird.

$foreach

Enthält den Enumerator (nicht die resultierenden Werte) einer ForEach-Schleife . Die $ForEach Variable ist nur vorhanden, während die ForEach Schleife ausgeführt wird. Sie wird gelöscht, nachdem die Schleife abgeschlossen wurde.

Enumeratoren enthalten Eigenschaften und Methoden, mit deren Hilfe Sie Schleifenwerte abrufen und die aktuelle Schleifeniteration ändern können. Weitere Informationen finden Sie unter Verwenden von Enumeratoren.

$HOME

Enthält den vollständigen Pfad des Basisverzeichnisses des Benutzers. Diese Variable ist die Entsprechung der "$env:homedrive$env:homepath" Windows-Umgebungsvariablen, in der Regel C:\Users\<UserName>.

$Host

Enthält ein -Objekt, das die aktuelle Hostanwendung für PowerShell darstellt. Sie können diese Variable verwenden, um den aktuellen Host in Befehlen darzustellen oder die Eigenschaften des Hosts anzuzeigen oder zu ändern, z$Host.version. B. oder $Host.CurrentCulture$host.ui.rawui.setbackgroundcolor("Red").

$input

Enthält einen Enumerator, der alle Eingaben aufzählt, die an eine Funktion übergeben werden. Die $input Variable ist nur für Funktionen und Skriptblöcke verfügbar (bei denen es sich um unbenannte Funktionen handelt).

• In einer Funktion ohne Begin, Processoder End -Block listet die $input Variable die Auflistung aller Eingaben für die Funktion auf.

• Begin Im -Block enthält die $input Variable keine Daten.

• Process Im -Block enthält die $input Variable das Objekt, das sich derzeit in der Pipeline befindet.

• End Im -Block listet die $input Variable die Auflistung aller Eingaben für die Funktion auf.

  Hinweis

  Sie können die $input Variable nicht sowohl innerhalb des Process-Blocks als auch des End-Blocks in derselben Funktion oder im gleichen Skriptblock verwenden.

Da $input ein Enumerator ist, ist $input der Zugriff auf eine seiner Eigenschaften nicht mehr verfügbar. Sie können in einer anderen Variablen speichern $input , um die Eigenschaften wiederzuverwenden $input .

Enumeratoren enthalten Eigenschaften und Methoden, mit deren Hilfe Sie Schleifenwerte abrufen und die aktuelle Schleifeniteration ändern können. Weitere Informationen finden Sie unter Verwenden von Enumeratoren.

$IsCoreCLR

Enthält $True , ob die aktuelle Sitzung in der .NET Core Runtime (CoreCLR) ausgeführt wird. Andernfalls enthält $False.

$IsLinux

Enthält $True , ob die aktuelle Sitzung unter einem Linux-Betriebssystem ausgeführt wird. Andernfalls enthält $False.

$IsMacOS

Enthält $True , ob die aktuelle Sitzung unter einem MacOS-Betriebssystem ausgeführt wird. Andernfalls enthält $False.

$IsWindows

Enthält $TRUE , ob die aktuelle Sitzung unter einem Windows-Betriebssystem ausgeführt wird. Andernfalls enthält $FALSE.

$LastExitCode

Enthält den Exitcode des letzten ausgeführten Windows-basierten Programms.

$Matches

Die Matches Variable funktioniert mit den -match Operatoren und -notmatch . Wenn Sie skalare Eingaben an den -match -Operator oder -notmatch übermitteln und eine Übereinstimmung erkennt, wird ein boolescher Wert zurückgegeben und die $Matches automatische Variable mit einer Hashtabelle mit allen übereinstimmenden Zeichenfolgenwerten aufgefüllt. Die $Matches Hashtabelle kann auch mit Aufzeichnungen aufgefüllt werden, wenn Sie reguläre Ausdrücke mit dem -match Operator verwenden.

Weitere Informationen zum -match Operator finden Sie unter about_Comparison_Operators. Weitere Informationen zu regulären Ausdrücken finden Sie unter about_Regular_Expressions.

$MyInvocation

Enthält Informationen zum aktuellen Befehl, z. B. den Namen, Parameter, Parameterwerte und Informationen darüber, wie der Befehl gestartet, aufgerufen oder aufgerufen wurde, z. B. den Namen des Skripts, das den aktuellen Befehl aufgerufen hat.

$MyInvocation wird nur für Skripts, Funktionen und Skriptblöcke aufgefüllt. Sie können die Informationen im System.Management.Automation.InvocationInfo-Objekt verwenden, das $MyInvocation im aktuellen Skript zurückgibt, z. B. den Pfad und dateinamen des Skripts ($MyInvocation.MyCommand.Path) oder den Namen einer Funktion ($MyInvocation.MyCommand.Name), um den aktuellen Befehl zu identifizieren. Dies ist besonders nützlich, um den Namen des aktuellen Skripts zu ermitteln.

Ab PowerShell 3.0 MyInvocation verfügt über die folgenden neuen Eigenschaften.

Eigenschaft	BESCHREIBUNG
PSScriptRoot	Enthält den vollständigen Pfad zum Skript, das aufgerufen wurde.
	der aktuelle Befehl. Der Wert dieser Eigenschaft ist
	nur aufgefüllt, wenn der Aufrufer ein Skript ist.
PSCommandPath	Enthält den vollständigen Pfad und Dateinamen des Skripts.
	, der den aktuellen Befehl aufgerufen hat. Der Wert dieses Werts
	-Eigenschaft wird nur aufgefüllt, wenn der Aufrufer ein
	„Hello World!“.

Im Gegensatz zu den $PSScriptRoot$PSCommandPath automatischen Variablen enthalten die Eigenschaften PSScriptRoot und PSCommandPath der $MyInvocation automatischen Variablen Informationen zum Aufrufer oder aufrufenden Skript, nicht zum aktuellen Skript.

$NestedPromptLevel

Enthält die aktuelle Eingabeaufforderungsebene. Der Wert 0 gibt die ursprüngliche Eingabeaufforderungsebene an. Der Wert wird erhöht, wenn Sie eine geschachtelte Ebene eingeben und beim Beenden dekrementiert.

PowerShell zeigt beispielsweise eine geschachtelte Eingabeaufforderung an, wenn Sie die $Host.EnterNestedPrompt -Methode verwenden. PowerShell stellt auch eine geschachtelte Eingabeaufforderung bereit, wenn Sie einen Haltepunkt im PowerShell-Debugger erreichen.

Wenn Sie eine geschachtelte Eingabeaufforderung eingeben, hält PowerShell den aktuellen Befehl an, speichert den Ausführungskontext und erhöht den Wert der $NestedPromptLevel Variablen. Um zusätzliche geschachtelte Eingabeaufforderungen zu erstellen (bis zu 128 Ebenen) oder zur ursprünglichen Eingabeaufforderung zurückzukehren, schließen Sie den Befehl ab, oder geben Sie ein exit.

Die $NestedPromptLevel Variable hilft Ihnen beim Nachverfolgen der Eingabeaufforderungsebene. Sie können eine alternative PowerShell-Eingabeaufforderung erstellen, die diesen Wert enthält, damit er immer sichtbar ist.

$null

$null ist eine automatische Variable, die einen NULL- oder leeren Wert enthält. Sie können diese Variable verwenden, um einen fehlenden oder nicht definierten Wert in Befehlen und Skripts darzustellen.

PowerShell behandelt $null ein Objekt mit einem Wert, d. h. als expliziten Platzhalter, sodass Sie einen leeren Wert in einer Reihe von Werten darstellen können $null .

Wenn $null sie beispielsweise in einer Auflistung enthalten ist, wird sie als eines der Objekte gezählt.

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

3

Wenn Sie die $null Variable an das ForEach-Object Cmdlet weiterleiten, wird ein Wert für $nullgeneriert, genau wie für die anderen Objekte.

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

Hello one
Hello
Hello three

Daher können Sie keinen Parameterwert verwenden$null. Ein Parameterwert von $null überschreibt den Standardwert.

Da PowerShell die $null Variable jedoch als Platzhalter behandelt, können Sie sie in Skripts wie dem folgenden verwenden, die nicht funktionieren würden, wenn $null sie ignoriert würden.

$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

Enthält den Prozessbezeichner (PiD) des Prozesses, der die aktuelle PowerShell-Sitzung hostt.

$PROFILE

Enthält den vollständigen Pfad des PowerShell-Profils für den aktuellen Benutzer und die aktuelle Hostanwendung. Sie können diese Variable verwenden, um das Profil in Befehlen darzustellen. Sie können es beispielsweise in einem Befehl verwenden, um zu bestimmen, ob ein Profil erstellt wurde:

Test-Path $PROFILE

Sie können es auch in einem Befehl verwenden, um ein Profil zu erstellen:

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

Sie können es in einem Befehl verwenden, um das Profil in notepad.exezu öffnen:

notepad.exe $PROFILE

$PSBoundParameters

Enthält ein Wörterbuch der Parameter, die an ein Skript oder eine Funktion übergeben werden, und deren aktuelle Werte. Diese Variable verfügt nur über einen Wert in einem Bereich, in dem Parameter deklariert werden, z. B. ein Skript oder eine Funktion. Sie können sie verwenden, um die aktuellen Werte von Parametern anzuzeigen oder zu ändern oder Parameterwerte an ein anderes Skript oder eine andere Funktion zu übergeben.

In diesem Beispiel übergibt die Test2-Funktion die $PSBoundParameters an die Test1-Funktion . Die $PSBoundParameters werden im Format "Schlüssel " und " Wert" angezeigt.

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

Enthält ein -Objekt, das das Cmdlet oder die erweiterte Funktion darstellt, die ausgeführt wird.

Sie können die Eigenschaften und Methoden des Objekts in Ihrem Cmdlet- oder Funktionscode verwenden, um auf die Nutzungsbedingungen zu reagieren. Beispielsweise enthält die ParameterSetName-Eigenschaft den Namen des verwendeten Parametersatzes, und die ShouldProcess-Methode fügt dem Cmdlet dynamisch die Parameter WhatIf und Confirm hinzu.

Weitere Informationen zur $PSCmdlet automatischen Variablen finden Sie unter about_Functions_CmdletBindingAttribute und about_Functions_Advanced.

$PSCommandPath

Enthält den vollständigen Pfad und Dateinamen des Skripts, das ausgeführt wird. Diese Variable ist in allen Skripts gültig.

$PSCulture

Enthält den Namen der Kultur, die derzeit im Betriebssystem verwendet wird. Die Kultur bestimmt das Anzeigeformat von Elementen wie Zahlen, Währungen und Datumsangaben und wird in einem System.Globalization.CultureInfo-Objekt gespeichert. Verwenden Sie Get-Culture , um die Kultur des Computers anzuzeigen. $PSCulture enthält den Wert der Name-Eigenschaft .

$PSDebugContext

Beim Debuggen enthält diese Variable Informationen zur Debugumgebung. Andernfalls enthält es einen NULL-Wert . Daher können Sie damit angeben, ob der Debugger über eine Steuerung verfügt. Wenn es aufgefüllt ist, enthält es ein PsDebugContext-Objekt mit Breakpoints - und InvocationInfo-Eigenschaften . Die InvocationInfo-Eigenschaft verfügt über mehrere nützliche Eigenschaften, einschließlich der Location-Eigenschaft . Die Location-Eigenschaft gibt den Pfad des Skripts an, das debuggt wird.

$PSHOME

Enthält den vollständigen Pfad des Installationsverzeichnisses für PowerShell, in der Regel in $env:windir\System32\PowerShell\v1.0 Windows-Systemen. Sie können diese Variable in den Pfaden von PowerShell-Dateien verwenden. Der folgende Befehl durchsucht beispielsweise die konzeptionellen Hilfethemen nach der Wortvariablen:

Select-String -Pattern Variable -Path $pshome\*.txt

$PSItem

Wie in $_. Enthält das aktuelle Objekt im Pipelineobjekt. Sie können diese Variable in Befehlen verwenden, die eine Aktion für jedes Objekt oder für ausgewählte Objekte in einer Pipeline ausführen.

$PSScriptRoot

Enthält das Verzeichnis, aus dem ein Skript ausgeführt wird.

In PowerShell 2.0 ist diese Variable nur in Skriptmodulen (.psm1) gültig. Ab PowerShell 3.0 ist sie in allen Skripts gültig.

$PSSenderInfo

Enthält Informationen zum Benutzer, der die PSSession gestartet hat, einschließlich der Benutzeridentität und der Zeitzone des Ursprungscomputers. Diese Variable ist nur in PSSessions verfügbar.

Die $PSSenderInfo Variable enthält die vom Benutzer konfigurierbare Eigenschaft ApplicationArguments, die standardmäßig nur das aus der $PSVersionTable ursprünglichen Sitzung enthält. Um der ApplicationArguments-Eigenschaft Daten hinzuzufügen, verwenden Sie den ApplicationArguments-Parameter des New-PSSessionOption Cmdlets.

$PSUICulture

Enthält den Namen der Benutzeroberflächeskultur, die derzeit im Betriebssystem verwendet wird. Die Benutzeroberflächenkultur bestimmt, welche Textzeichenfolgen für die Benutzeroberflächenelemente, z. B. Menüs und Meldungen, verwendet werden. Dies ist der Wert der System.Globalization.CultureInfo.CurrentUICulture.Name Eigenschaft des Systems. Verwenden Sie Get-UICulture das Cmdlet, um das System.Globalization.CultureInfo-Objekt für das System abzurufen.

$PSVersionTable

Enthält eine schreibgeschützte Hashtabelle, die Details zur Version von PowerShell anzeigt, die in der aktuellen Sitzung ausgeführt wird. Die Tabelle enthält die folgenden Elemente:

Eigenschaft	BESCHREIBUNG
PSVersion	Die PowerShell-Versionsnummer
PSEdition	Diese Eigenschaft hat den Wert "Desktop" für
	PowerShell 4 und niedriger sowie PowerShell
	5.1 für windows-Editionen mit vollem Funktionsumfang.
	Diese Eigenschaft hat den Wert "Core" für
	PowerShell 6 und höher sowie PowerShell
	PowerShell 5.1 für Editionen mit reduziertem Platzbedarf
	wie Windows Nano Server oder Windows IoT.
GitCommitId	Die Commit-ID der Quelldateien in GitHub,
Betriebssystem	Beschreibung des Betriebssystems, das
	PowerShell wird unter ausgeführt.
Plattform	Plattform, auf der das Betriebssystem ausgeführt wird
	Abonnements. Der Wert unter Linux und macOS ist Unix.
	Prüfen Sie $IsMacOs und $IsLinux.
PSCompatibleVersions	Kompatible Versionen von PowerShell
	mit der aktuellen Version
PSRemotingProtocolVersion	Die Version der PowerShell-Remoteversion
	Verwaltungsprotokoll.
SerialisierungVersion	Die Version der Serialisierungsmethode
WSManStackVersion	Die Versionsnummer des WS-Management Stapels

$PWD

Enthält ein Pfadobjekt, das den vollständigen Pfad des aktuellen Verzeichnisses darstellt.

$Sender

Enthält das Objekt, das dieses Ereignis generiert hat. Diese Variable wird nur im Aktionsblock eines Ereignisregistrierungsbefehls aufgefüllt. Der Wert dieser Variablen befindet sich auch in der Sender-Eigenschaft des zurückgegebenen PSEventArgs-ObjektsGet-Event.

$ShellId

Enthält den Bezeichner der aktuellen Shell.

$StackTrace

Enthält eine Stapelablaufverfolgung für den neuesten Fehler.

$switch

Enthält den Enumerator, nicht die resultierenden Werte einer Switch Anweisung. Die $switch Variable ist nur vorhanden, während die Switch -Anweisung ausgeführt wird. Sie wird gelöscht, wenn die -Anweisung die switch Ausführung abgeschlossen hat. Weitere Informationen finden Sie unter about_Switch.

Enumeratoren enthalten Eigenschaften und Methoden, die Sie verwenden können, um Schleifenwerte abzurufen und die aktuelle Schleifeniteration zu ändern. Weitere Informationen finden Sie unter Verwenden von Enumeratoren.

$this

In einem Skriptblock, der eine Skripteigenschaft oder Skriptmethode definiert, verweist die $this Variable auf das Objekt, das erweitert wird.

In einer benutzerdefinierten Klasse bezieht sich die $this Variable auf das Klassenobjekt selbst, was den Zugriff auf die in der Klasse definierten Eigenschaften und Methoden ermöglicht.

$True

Enthält True. Sie können diese Variable verwenden, um True in Befehlen und Skripts darzustellen.

Verwenden von Enumeratoren

Die $inputVariablen , $foreach, und $switch sind alle Enumeratoren, die zum Durchlaufen der Werte verwendet werden, die von ihrem enthaltenden Codeblock verarbeitet werden.

Ein Enumerator enthält Eigenschaften und Methoden, die Sie zum Voranbringen oder Zurücksetzen der Iteration oder zum Abrufen von Iterationswerten verwenden können. Das direkte Manipulieren von Enumeratoren wird nicht als bewährte Methode betrachtet.

• Innerhalb von Schleifen sollten Flusssteuerungsschlüsselwörter umbrechen und fortfahren bevorzugt werden.

• In Funktionen, die Pipelineeingaben akzeptieren, empfiehlt es sich, Parameter mit den Attributen ValueFromPipeline oder ValueFromPipelineByPropertyName zu verwenden.

  Weitere Informationen finden Sie unter about_Functions_Advanced_Parameters.

MoveNext

Die MoveNext-Methode bringt den Enumerator zum nächsten Element der Auflistung. MoveNext gibt True zurück, wenn der Enumerator erfolgreich erweitert wurde, False , wenn der Enumerator das Ende der Auflistung überschritten hat.

Hinweis

Der boolesche Wert, der meine MoveNext zurückgegeben hat, wird an den Ausgabedatenstrom gesendet. Sie können die Ausgabe unterdrücken, indem Sie sie an oder als Piping an [void]Out-Null (Out-Null) eingeben.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

Die Reset-Methode legt den Enumerator auf seine Ursprüngliche Position fest, die sich vor dem ersten Element in der Auflistung befindet.

Aktuell

Die Current-Eigenschaft ruft das Element in der Auflistung oder Pipeline an der aktuellen Position des Enumerators ab.

Die Current-Eigenschaft gibt weiterhin dieselbe Eigenschaft zurück, bis MoveNext aufgerufen wird.

Beispiele

Beispiel 1: Verwenden der variablen $input

Im folgenden Beispiel löscht der Zugriff auf die $input Variable die Variable, bis der Prozessblock das nächste Mal ausgeführt wird. Mithilfe der Reset-Methode wird die $input Variable auf den aktuellen Pipelinewert zurückgesetzt.

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

Der Prozessblock erhöht die $input Variable automatisch, auch wenn Sie nicht darauf zugreifen.

$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

Beispiel 2: Verwenden von $input außerhalb des Prozessblocks

Außerhalb des Prozessblocks stellt die $input Variable alle Werte dar, die an die Funktion übergeben werden.

• Durch den Zugriff auf die $input Variable werden alle Werte gelöscht.
• Die Reset-Methode setzt die gesamte Auflistung zurück.
• Die Current-Eigenschaft wird nie aufgefüllt.
• Die MoveNext-Methode gibt false zurück, da die Auflistung nicht erweitert werden kann.
  • Durch Aufrufen von MoveNext wird die $input Variable gelöscht.

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:

Beispiel 3: Verwenden des $input. Current-Eigenschaft

Mithilfe der Current-Eigenschaft kann mehrmals auf den aktuellen Pipelinewert zugegriffen werden, ohne die Reset-Methode zu verwenden. Der Prozessblock ruft nicht automatisch die MoveNext-Methode auf.

Die Current-Eigenschaft wird nie aufgefüllt, es sei denn, Sie rufen MoveNext explizit auf. Auf die Current-Eigenschaft kann mehrmals innerhalb des Prozessblocks zugegriffen werden, ohne dessen Wert zu löschen.

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

Beispiel 4: Verwenden der variablen $foreach

$input Im Gegensatz zur Variablen stellt die $foreach Variable immer alle Elemente in der Auflistung dar, wenn direkt darauf zugegriffen wird. Verwenden Sie die Current-Eigenschaft , um auf das aktuelle Auflistungselement zuzugreifen, und die Methoden Reset und MoveNext , um den Wert zu ändern.

Hinweis

Jede Iteration der foreach Schleife ruft automatisch die MoveNext-Methode auf.

Die folgende Schleife wird nur zweimal ausgeführt. In der zweiten Iteration wird die Auflistung in das dritte Element verschoben, bevor die Iteration abgeschlossen ist. Nach der zweiten Iteration sind nun keine weiteren Werte mehr zu durchlaufen, und die Schleife wird beendet.

Die MoveNext-Eigenschaft wirkt sich nicht auf die Variable aus, die ausgewählt wurde, um die Auflistung zu durchlaufen ($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 has not changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num has not changed: two

Mithilfe der Reset-Methode wird das aktuelle Element in der Auflistung zurückgesetzt. Im folgenden Beispiel werden die ersten beiden Elemente zweimal durchschleifen, da die Reset-Methode aufgerufen wird. Nach den ersten beiden Schleifen schlägt die if Anweisung fehl, und die Schleife durchlaufen alle drei Elemente normal.

Wichtig

Dies kann zu einer Endlosschleife führen.

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

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset() | Out-Null
        ("`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

Beispiel 5: Verwenden der variablen $switch

Die $switch Variable hat genau die gleichen Regeln wie die $foreach Variable. Im folgenden Beispiel werden alle Enumeratorkonzepte veranschaulicht.

Hinweis

Beachten Sie, dass der NotEvaluated-Fall nie ausgeführt wird, obwohl nach der MoveNext-Methode keine break Anweisung vorhanden ist.

$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

Weitere Informationen

about_Functions

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