ForEach-Object

Syntax

ForEach-Object <ScriptBlock> >] 

ForEach-Object <String> >] 

ForEach-Object -Parallel <scriptblock> 

Beschreibung

Das Cmdlet ForEach-Object führt für jedes Element in einer Sammlung von Eingabeobjekten einen Vorgang aus. Die Eingabeobjekte können über die Pipeline an das Cmdlet übergeben oder mit dem InputObject-Parameter angegeben werden.

Ab Windows PowerShell 3.0 gibt es zwei verschiedene Möglichkeiten, einen ForEach-ObjectBefehl zu erstellen.

• Skriptblock. Sie können einen Skriptblock verwenden, um den Vorgang zu spezifizieren. Innerhalb des Skriptblocks verwenden Sie die Variable $_, um das aktuelle Objekt darzustellen. Der Skriptblock ist der Wert des ParametersProcess. Der Skriptblock kann ein beliebiges PowerShell-Skript enthalten.

  Beispielsweise ruft der folgende Befehl den Wert der Eigenschaft ProcessName jedes Prozesses auf dem Computer ab.

  Get-Process | ForEach-Object {$_.ProcessName}

  ForEach-Object unterstützt das beginprocess, und end Blöcke wie inabout_functions beschrieben.

  Hinweis

  Die Skriptblöcke laufen im Scope des Aufrufers. Daher haben die Blöcke Zugriff auf Variablen in diesem Bereich und können neue Variablen erstellen, die nach Beendigung des Cmdlets in diesem Bereich bestehen bleiben.

• Operationsanweisung. Sie können auch eine Operationsanweisung schreiben, die einer natürlichen Sprache sehr viel ähnlicher ist. Sie können die Operationsanweisung verwenden, um einen Eigenschaftswert anzugeben oder eine Methode aufzurufen. Operationsanweisungen wurden in Windows PowerShell 3.0 eingeführt.

  Beispielsweise ruft der folgende Befehl auch den Wert der Eigenschaft „ProcessName“ jedes Prozesses auf dem Computer ab.

  Get-Process | ForEach-Object ProcessName

• Parallel laufender Skriptblock. Ab PowerShell 7.0 ist ein dritter Parametersatz verfügbar, der jeden Skriptblock parallel ausführt. Der ThrottleLimit-Parameter begrenzt die Anzahl der parallel ausgeführten Skripte zu einem Zeitpunkt. Verwenden Sie wie zuvor die Variable $_, um das aktuelle Eingabeobjekt im Skriptblock darzustellen. Verwenden Sie das $using:-Schlüsselwort, um Variablenreferenzen an das laufende Skript zu übergeben.

  In PowerShell 7 wird für jede Schleifeniteration ein neuer Runspace erstellt, um eine maximale Isolierung zu gewährleisten.

  Dies kann ein großer Leistungs- und Ressourcenschaden sein, wenn die Arbeit, die Sie ausführen, im Vergleich zum Erstellen neuer Runspaces klein ist oder wenn es viele Iterationen gibt, die erhebliche Arbeit leisten. AbPowerShell 7.1 werden Runspaces aus einem Runspace-Pool standardmäßig wiederverwendet. Die Größe des Runspace-Pools wird durch den Parameter „ThrottleLimit“ festgelegt. Die Standardgröße des Runspace-Pools ist 5. Mit dem Schalter „UseNewRunspace“ können Sie dennoch für jede Iteration einen neuen Runspace erstellen.

  Standardmäßig verwenden die parallelen Skriptblöcke das aktuelle Arbeitsverzeichnis des Aufrufers, der die parallelen Aufgaben gestartet hat.

  Nicht abschließende Fehler werden in den Cmdlet-Fehlerstrom geschrieben, wenn sie in parallel ausgeführten Skriptblöcken auftreten. Da die Reihenfolge der Ausführung paralleler Skriptblöcke nicht bestimmt werden kann, ist die Reihenfolge, in der Fehler im Fehlerstrom erscheinen, zufällig. Ebenso werden Meldungen, die in andere Datenströme geschrieben werden, wie Warnungen, ausführliche Informationen oder Informationen, in einer unbestimmten Reihenfolge in diese Datenströme geschrieben.

  Beendende Fehler, wie z. B. Ausnahmen, beenden die einzelnen parallelen Instanzen der Skriptblöcke, in denen sie auftreten. Ein abschließender Fehler in einem Skriptblock darf nicht zum Abbruch des Foreach-Object-Cmdlets führen. Die anderen Skriptblöcke, die parallel ausgeführt werden, werden weiter ausgeführt, bis sie ebenfalls auf einen abbrechenden Fehler stoßen. Der abschließende Fehler wird als ErrorRecord mit einer FullyQualifiedErrorId von PSTaskException in den Fehlerdatenstrom geschrieben. Abschließende Fehler können mithilfe von PowerShell try/catch- oder Trap-Blöcken in nicht abschließende Fehler umgewandelt werden.

Beispiele

Beispiel 1: Teilen von Ganzzahlen in einem Array

In diesem Beispiel wird ein Array mit drei Ganzzahlen genommen und jede durch 1024 geteilt.

30000, 56798, 12432 | ForEach-Object -Process {$_/1024}29.29687555.46679687512.140625

Beispiel 2: Abrufen der Länge aller Dateien in einem Verzeichnis

In diesem Beispiel werden die Dateien und Verzeichnisse im PowerShell-Installationsverzeichnis $PSHOME verarbeitet.

Get-ChildItem $PSHOME | ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; " " }}

Wenn das Objekt kein Verzeichnis ist, ruft der Skriptblock den Namen der Datei ab, teilt den Wert der Eigenschaft „Length“ durch 1024 und fügt ein Leerzeichen (“ „) hinzu, um es vom nächsten Eintrag zu trennen. Dascmdlet verwendet die Eigenschaft PSISContainer, um festzustellen, ob es sich bei einem Objekt um ein Verzeichnis handelt.

Beispiel 3: Auf den jüngsten Systemereignissen operieren

Dieses Beispiel schreibt die 1000 jüngsten Ereignisse aus dem Systemereignisprotokoll in eine Textdatei. Die aktuelle Uhrzeit wird vor und nach der Verarbeitung der Ereignisse angezeigt.

$Events = Get-EventLog -LogName System -Newest 1000$events | ForEach-Object -Begin {Get-Date} -Process {Out-File -FilePath Events.txt -Append -InputObject $_.Message} -End {Get-Date}

Get-EventLog holt die 1000 aktuellsten Ereignisse aus dem Systemereignisprotokoll und speichert sie in der Variablen$Events$Events wird dann über die Pipeline an das Cmdlet ForEach-Object übergeben. Der Begin-Parameter zeigt das aktuelle Datum und die Uhrzeit an. Als Nächstes erstellt der Process-Parameter mit dem Cmdlet Out-File eine Textdatei mit dem Namen events.txt und speichert die Nachrichteneigenschaft der einzelnen Ereignisse in dieser Datei. Mit dem End-Parameter werden schließlich Datum und Uhrzeit nach Abschluss der Verarbeitung angezeigt.

Beispiel 4: Ändern des Werts eines Registrierungsschlüssels

In diesem Beispiel wird der Wert des Registrierungseintrags „RemotePath“ in allen Unterschlüsseln unter dem SchlüsselHKCU:\Network in Großbuchstaben geändert.

Get-ItemProperty -Path HKCU:\Network\* | ForEach-Object {Set-ItemProperty -Path $_.PSPath -Name RemotePath -Value $_.RemotePath.ToUpper();}

Sie können dieses Format verwenden, um die Form oder den Inhalt des Wertes eines Registrierungseintrags zu ändern.

Jeder Unterschlüssel im Schlüssel Netzwerk repräsentiert ein zugeordnetes Netzlaufwerk, das sich bei der Anmeldung neu anmeldet. Der EintragRemotePath enthält den UNC-Pfad des verbundenen Laufwerks. Wenn Sie beispielsweise das Laufwerk E:auf \\Server\Share zuordnen, wird ein Unterschlüssel E in HKCU:\Network mit dem Wert RemotePfadhregistry auf \\Server\Share erstellt.

Der Befehl verwendet das Cmdlet Get-ItemProperty, um alle Unterschlüssel des Schlüssels „Network“ abzurufen, und das Cmdlet Set-ItemProperty, um den Wert des Registrierungseintrags „RemotePath“ in jedem Schlüssel zu ändern.

Im Befehl Set-ItemProperty ist der Pfad der Wert der PSPath-Eigenschaft des Registrierungsschlüssels. Dies ist eine Eigenschaft des Microsoft .NET Framework-Objekts, das den Registrierungsschlüssel und nicht einen Registrierungseintrag darstellt. Der Befehl verwendet die ToUpper()-Methode des RemotePath-Werts, der eine Zeichenkette (REG_SZ) ist.

Da Set-ItemProperty die Eigenschaft jedes Schlüssels ändert, ist das Cmdlet ForEach-Object erforderlich, um auf die Eigenschaft zuzugreifen.

Beispiel 5: Verwenden der automatischen Variable „$Null“

In diesem Beispiel wird gezeigt, wie die automatische Variable $Null über die Pipeline an das Cmdlet ForEach-Object übergeben wird.

1, 2, $null, 4 | ForEach-Object {"Hello"}HelloHelloHelloHello

Da PowerShell null als expliziten Platzhalter behandelt, generiert das Cmdlet ForEach-Object einen Wert für $Null, genau wie bei anderen Objekten, die Sie über die Pipeline übergeben.

Beispiel 6: Abrufen von Eigenschaftswerten

In diesem Beispiel wird der Wert der Eigenschaft „Path“ aller installierten PowerShell-Module abgerufen, indem der Parameter „MemberName“ des Cmdlets ForEach-Object verwendet wird.

Get-Module -ListAvailable | ForEach-Object -MemberName PathGet-Module -ListAvailable | Foreach Path

Der zweite Befehl entspricht dem ersten. Er verwendet den Foreach Alias des ForEach-ObjectCmdlets und lässt den Namen des MemberName-Parameters weg, der optional ist.

Das Cmdlet „ForEach-Object ist für das Abrufen von Eigenschaftswerten nützlich, da es den Wert abruft, ohne den Typ zu ändern, im Gegensatz zu den Cmdlets „Format“ oder „Select-Object, die den Typ des Eigenschaftswerts ändern.

Beispiel 7: Aufteilen von Modulnamen in Komponentennamen

In diesem Beispiel werden drei Möglichkeiten zum Aufteilen von zwei durch Punkte getrennten Modulnamen in ihre Komponentennamen gezeigt.

"Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object {$_.Split(".")}"Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object -MemberName Split -ArgumentList ".""Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | Foreach Split "."MicrosoftPowerShellCoreMicrosoftPowerShellHost

Die Befehle rufen die Split-Methode von Strings auf. Die drei Befehle verwenden eine unterschiedliche Syntax, sind aber gleichwertig und austauschbar.

Der erste Befehl verwendet die traditionelle Syntax, die einen Skriptblock und den aktuellen Objektoperator $_ enthält. Er verwendet die Punktsyntax, um die Methode anzugeben, und Klammern, um das Trennargument einzuschließen.

Der zweite Befehl verwendet den MemberName-Parameter, um die Split-Methode anzugeben, und denArgumentName-Parameter, um den Punkt („.“) als Trennzeichen für die Aufteilung zu identifizieren.

Der dritte Befehl verwendet den Foreach-Alias des Cmdlets ForEach-Object und lässt die Namen der Parameter MemberName und ArgumentList weg, die optional sind.

Beispiel 8: Verwenden von ForEach-Object mit zwei Skriptblöcken

In diesem Beispiel werden zwei Skriptblöcke positionell übergeben. Alle Skriptblöcke binden an denProcess -Parameter. Sie werden jedoch so behandelt, als wären sie an die Parameter Begin undProcess übergeben worden.

1..2 | ForEach-Object { 'begin' } { 'process' }beginprocessprocess

Beispiel 9: Verwenden von ForEach-Object mit mehr als zwei Skriptblöcken

In diesem Beispiel werden zwei Skriptblöcke positionell übergeben. Alle Skriptblöcke binden an denProcess -Parameter. Sie werden jedoch so behandelt, als wären sie an die Parameter Begin,Process und End übergeben worden.

1..2 | ForEach-Object { 'begin' } { 'process A' } { 'process B' } { 'end' }beginprocess Aprocess Bprocess Aprocess Bend

Beispiel 10: Ausführen mehrerer Skriptblöcke für jedes Pipelineelement

Wie im vorherigen Beispiel gezeigt, werden mehrere Skriptblöcke, die mit dem Parameter „Process“ übergeben werden, den Parametern „Begin“ und „End“ zugeordnet. Um diese Zuordnung zu vermeiden, müssen Sie explizite Werte für die Parameter Begin und End angeben.

1..2 | ForEach-Object -Begin $null -Process { 'one' }, { 'two' }, { 'three' } -End $nullonetwothreeonetwothree

Beispiel 11: Langsames Skript in parallelen Stapeln ausführen

In diesem Beispiel wird ein einfacher Skriptblock ausgeführt, der eine Zeichenfolge auswertet und eine Sekunde lang schläft.

$Message = "Output:"1..8 | ForEach-Object -Parallel { "$using:Message $_" Start-Sleep 1} -ThrottleLimit 4Output: 1Output: 2Output: 3Output: 4Output: 5Output: 6Output: 7Output: 8

Der Wert des Parameters ThrottleLimit wird auf 4 gesetzt, so dass die Eingabe in Vierer-Stapeln verarbeitet wird.Das $using:-Schlüsselwort wird verwendet, um die $Message-Variable in jeden parallelen Skriptblock zu übergeben.

Beispiel 12: Paralleles Abrufen von Protokolleinträgen

Dieses Beispiel ruft 50.000 Protokolleinträge aus 5 Systemprotokollen auf einem lokalen Windows-Rechner ab.

$logNames = 'Security','Application','System','Windows PowerShell','Microsoft-Windows-Store/Operational'$logEntries = $logNames | ForEach-Object -Parallel { Get-WinEvent -LogName $_ -MaxEvents 10000} -ThrottleLimit 5$logEntries.Count50000

Der Parameter Parallel gibt den Skriptblock an, der für jeden Eingabeprotokollnamen parallel ausgeführt wird. Der Parameter „ThrottleLimit“ stellt sicher, dass alle fünf Skriptblöcke gleichzeitig ausgeführt werden.

Beispiel 13: Parallel als Auftrag ausführen

In diesem Beispiel wird ein einfacher Skriptblock parallel ausgeführt, wobei zwei Hintergrundaufträge gleichzeitig erstellt werden.

$job = 1..10 | ForEach-Object -Parallel { "Output: $_" Start-Sleep 1} -ThrottleLimit 2 -AsJob$job | Receive-Job -WaitOutput: 1Output: 2Output: 3Output: 4Output: 5Output: 6Output: 7Output: 8Output: 9Output: 10

Die Variable $job empfängt das Job-Objekt, das die Ausgabedaten sammelt und den Betriebszustand überwacht.

Das Job-Objekt wird mit dem Schalterparameter Wait an Receive-Job übergeben. Dadurch wird die Ausgabe auf die Konsole gestreamt, genauso wie wenn ForEach-Object -Parallel ohne AsJob ausgeführt würde.

Beispiel 14: Verwendung von thread-sicheren Variablenreferenzen

In diesem Beispiel werden Skriptblöcke parallel aufgerufen, um eindeutig benannte Prozessobjekte zu sammeln.

$threadSafeDictionary = ]::new()Get-Process | ForEach-Object -Parallel { $dict = $using:threadSafeDictionary $dict.TryAdd($_.ProcessName, $_)}$threadSafeDictionaryNPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName ------ ----- ----- ------ -- -- ----------- 82 82.87 130.85 15.55 2808 2 pwsh

Eine einzelne Instanz eines ConcurrentDictionary-Objekts wird an jeden Skriptblock übergeben, um dieObjekte zu sammeln. Da das ConcurrentDictionary thread-sicher ist, kann es von jedem parallelen Skript sicher geändert werden. Ein nicht thread-sicheres Objekt, wie z. B. System.Collections.Generic.Dictionary, wäre hier nicht sicher zu verwenden.

Beispiel 15: Schreiben von Fehlern mit paralleler Ausführung

Dieses Beispiel schreibt parallel in den Fehlerstrom, wobei die Reihenfolge der geschriebenen Fehler zufällig ist.

1..3 | ForEach-Object -Parallel { Write-Error "Error: $_"}Write-Error: Error: 1Write-Error: Error: 3Write-Error: Error: 2

Beispiel 16: Beenden von Fehlern bei paralleler Ausführung

Dieses Beispiel demonstriert einen beendenden Fehler in einem parallel laufenden Skriptblock.

1..5 | ForEach-Object -Parallel { if ($_ -eq 3) { throw "Terminating Error: $_" } Write-Output "Output: $_"}Exception: Terminating Error: 3Output: 1Output: 4Output: 2Output: 5

Output: 3 wird nie geschrieben, da der parallele Skriptblock für diese Iteration beendet wurde.

Beispiel 17: Übergabe von Variablen in verschachtelten parallelen Skriptblöcken

Sie können eine Variable außerhalb eines Foreach-Object -Parallel skalierten Skriptblocks erstellen und sie innerhalb des Skriptblocks mit dem Schlüsselwort $using verwenden.

$test1 = 'TestA'1..2 | Foreach-Object -Parallel { $using:test1}TestATestA# You CANNOT create a variable inside a scoped scriptblock# to be used in a nested foreach parallel scriptblock.$test1 = 'TestA'1..2 | Foreach-Object -Parallel { $using:test1 $test2 = 'TestB' 1..2 | Foreach-Object -Parallel { $using:test2 }}Line | 2 | 1..2 | Foreach-Object -Parallel { | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | The value of the using variable '$using:test2' cannot be retrieved because it has not been set in the local session.

Der verschachtelte Skriptblock kann nicht auf die $test2-Variable zugreifen und ein Fehler wird ausgelöst.

Parameter

Steuert die Anzahl der Skriptblöcke, die parallel laufen. Eingabeobjekte werden blockiert, bis die Anzahl der laufenden Skriptblöcke unter das ThrottleLimit fällt. Der Standardwert ist 5.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Typ:	Int32
Position:	Benannt
Standardwert:	5
Akzeptiere Pipeline-Eingabe:	False
Accept wildcard characters:	False

Eingaben

PSObject

Sie können ein beliebiges Objekt über die Pipeline an dieses Cmdlet übergeben.

Ausgaben

PSObject

Dieses Cmdlet gibt Objekte zurück, die durch die Eingabe bestimmt werden.

Hinweise

• Das Cmdlet ForEach-Object funktioniert ähnlich wie die Foreach-Anweisung, außer dass Sie keine Eingaben über die Pipeline an eine Foreach-Anweisung übergeben können. Weitere Informationen über die Foreach-Anweisung finden Sie unterabout_Foreach.

• Beginnend mit PowerShell 4.0 wurden die Methoden Where und ForEach für die Verwendung mit Sammlungen hinzugefügt. Mehr über diese neuen Methoden können Sie hier nachlesen: about_arrays

• Der ForEach-Object -Parallel-Parametersatz verwendet die interne API der PowerShell, um jeden Skriptblock auszuführen. Dies ist deutlich mehr Overhead als die normale Ausführung von ForEach-Object mit sequenzieller Verarbeitung. Es ist wichtig, Parallel zu verwenden, wenn der Overhead der parallelen Ausführung klein ist im Vergleich zur Arbeit, die der Skriptblock ausführt. Zum Beispiel:

  • Rechenintensive Skripte auf Multi-Core-Maschinen
  • Skripte, die Zeit mit dem Warten auf Ergebnisse oder mit Dateioperationen verbringen

  Die Verwendung des Parameters „Parallel“ kann dazu führen, dass Skripte viel langsamer als normal ausgeführt werden. Vor allem, wenn die parallelen Skripte trivial sind. Experimentieren Sie mit Parallel, um herauszufinden, wo es von Vorteil sein kann.

  Wichtig

  Der ForEach-Object -Parallel-Parametersatz führt Skriptblöcke parallel auf separaten Prozessthreads aus. Das $using:-Schlüsselwort ermöglicht die Übergabe von Variablenreferenzen vom Cmdlet-Aufrufthread an jeden laufenden Skriptblock-Thread. Da die Skriptblöcke in verschiedenen Threads ausgeführt werden, müssen die per Referenz übergebenen Objektvariablen sicher verwendet werden. Im Allgemeinen ist es sicher, von referenzierten Objekten zu lesen, die sich nicht ändern. Wenn sich aber der Objektzustand ändert, müssen Sie thread-sichere Objekte verwenden, wie zum Beispiel .Net System.Collection.Concurrent-Typen (siehe Beispiel 11).

• Vergleichsobjekt
• Wo-Objekt
• Gruppenobjekt
• Messobjekt
• Neu-Objekt
• Auswahl-Objekt
• Sortierobjekt
• Tee-Objekt