ForEach-Object

Modul:

Microsoft.PowerShell.Core

Führt einen Vorgang für jedes Element in einer Auflistung von Eingabeobjekten aus.

Syntax

ForEach-Object
            [-InputObject <PSObject>]
            [-Begin <ScriptBlock>]
            [-Process] <ScriptBlock[]>
            [-End <ScriptBlock>]
            [-RemainingScripts <ScriptBlock[]>]
            [-WhatIf]
            [-Confirm]
            [<CommonParameters>]

ForEach-Object
            [-InputObject <PSObject>]
            [-MemberName] <String>
            [-ArgumentList <Object[]>]
            [-WhatIf]
            [-Confirm]
            [<CommonParameters>]

ForEach-Object
            -Parallel <scriptblock>
            [-InputObject <psobject>]
            [-ThrottleLimit <int>]
            [-TimeoutSeconds <int>]
            [-AsJob]
            [-UseNewRunspace]
            [-WhatIf]
            [-Confirm]
            [<CommonParameters>]

Beschreibung

Das ForEach-Object Cmdlet führt einen Vorgang für jedes Element in einer Sammlung von Eingabeobjekten aus. Die Eingabeobjekte können an das Cmdlet weitergeleitet oder mithilfe des InputObject-Parameters angegeben werden.

Ab Windows PowerShell 3.0 gibt es zwei verschiedene Möglichkeiten zum Erstellen eines ForEach-Object Befehls.

• Skriptblock. Sie können einen Skriptblock verwenden, um den Vorgang anzugeben. Verwenden Sie innerhalb des Skriptblocks die $_ Variable, um das aktuelle Objekt darzustellen. Der Skriptblock ist der Wert des Process-Parameters . Der Skriptblock kann ein beliebiges PowerShell-Skript enthalten.

  Der folgende Befehl ruft beispielsweise den Wert der ProcessName-Eigenschaft jedes Prozesses auf dem Computer ab.

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

  ForEach-Objectunterstützt die beginin processabout_functions beschriebenen Blöcke und end Blöcke.

  Hinweis

  Die Skriptblöcke werden im Bereich des Aufrufers ausgeführt. Daher haben die Blöcke Zugriff auf Variablen in diesem Bereich und können neue Variablen erstellen, die nach Abschluss des Cmdlets in diesem Bereich beibehalten werden.

• Operation-Anweisung. Sie können auch eine Vorgangsanweisung schreiben, die viel ähnlich wie natürliche Sprache ist. Sie können die Vorgangsanweisung verwenden, um einen Eigenschaftenwert anzugeben oder eine Methode aufzurufen. Vorgangsanweisungen wurden in Windows PowerShell 3.0 eingeführt.

  Der folgende Befehl ruft beispielsweise auch den Wert der ProcessName-Eigenschaft jedes Prozesses auf dem Computer ab.

  Get-Process | ForEach-Object ProcessName

• Parallel ausgeführter Skriptblock. Ab PowerShell 7.0 ist ein dritter Parametersatz verfügbar, der jeden Skriptblock parallel ausführt. Der ThrottleLimit-Parameter begrenzt die Anzahl paralleler Skripts, die gleichzeitig ausgeführt werden. Verwenden Sie wie zuvor die $_ Variable, um das aktuelle Eingabeobjekt im Skriptblock darzustellen. Verwenden Sie das $using: Schlüsselwort, um Variablenverweise an das ausgeführte Skript zu übergeben.

  In PowerShell 7 wird für jede Schleifeniteration ein neuer Runspace erstellt, um eine maximale Isolation sicherzustellen. Dies kann eine große Leistung und Ressourcentreffer sein, wenn die arbeit, die Sie ausführen, im Vergleich zum Erstellen neuer Runspaces klein ist oder wenn viele Iterationen erhebliche Arbeit leisten. Ab PowerShell 7.1 werden Runspaces aus einem Runspace-Pool standardmäßig wiederverwendet. Der Parameter ThrottleLimit legt die Größe des Runspacepools fest. Die Standardgröße des Runspacepools ist 5. Sie können weiterhin einen neuen Runspace für jede Iteration mithilfe der UseNewRunspace-Option erstellen.

  Standardmäßig verwenden die parallelen Skriptblocks das aktuelle Arbeitsverzeichnis des Aufrufers, das die parallelen Aufgaben gestartet hat.

  Weitere Informationen finden Sie im Abschnitt "NOTIZEN " dieses Artikels.

Beispiele

Beispiel 1: Dividieren ganzzahliger Zahlen in einem Array

In diesem Beispiel wird ein Array mit drei ganzzahligen Zahlen verwendet und jede von ihnen durch 1024 dividiert.

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

29.296875
55.466796875
12.140625

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

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

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, dividiert den Wert der Length-Eigenschaft durch 1024 und fügt ein Leerzeichen (" ") hinzu, um es vom nächsten Eintrag zu trennen. Das Cmdlet verwendet die PSISContainer-Eigenschaft , um zu bestimmen, ob ein Objekt ein Verzeichnis ist.

Beispiel 3: Arbeiten mit den neuesten Systemereignissen

In diesem Beispiel werden die 1000 neuesten Ereignisse aus dem Systemereignisprotokoll in eine Textdatei geschrieben. Die aktuelle Uhrzeit wird vor und nach der Verarbeitung der Ereignisse angezeigt.

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

Get-EventLog ruft die 1000 neuesten Ereignisse aus dem Systemereignisprotokoll ab und übergibt sie an das ForEach-Object Cmdlet. Der Begin-Parameter zeigt das aktuelle Datum und die aktuelle Uhrzeit an. Als Nächstes verwendet der Process-Parameter das Out-File Cmdlet, um eine Textdatei mit dem Namen events.txt zu erstellen und die Nachrichteneigenschaft der einzelnen Ereignisse in dieser Datei zu speichern. Zuletzt wird der End-Parameter verwendet, um das Datum und die Uhrzeit anzuzeigen, nachdem die gesamte Verarbeitung abgeschlossen wurde.

Beispiel 4: Ändern des Werts eines Registrierungsschlüssels

In diesem Beispiel wird der Wert des RemotePath-Registrierungseintrags in allen Unterschlüsseln unter dem HKCU:\Network Schlüssel 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 eines Registrierungseintragswerts zu ändern.

Jeder Unterschlüssel im Netzwerkschlüssel stellt ein zugeordnetes Netzlaufwerk dar, das bei der Anmeldung erneut eine Verbindung herstellt. Der RemotePath-Eintrag enthält den UNC-Pfad des verbundenen Laufwerks. Wenn Sie das E: Laufwerk \\Server\Sharez. B. zuordnen, wird ein E-Unterschlüssel erstellt, in HKCU:\Network dem der Registrierungswert "RemotePath " auf " \\Server\Share.

Der Befehl verwendet das Get-ItemProperty Cmdlet, um alle Unterschlüssel des Netzwerkschlüssels und das Set-ItemProperty Cmdlet abzurufen, um den Wert des RemotePath-Registrierungseintrags in jedem Schlüssel zu ändern. Set-ItemProperty Im Befehl ist der Pfad der PSPath-Eigenschaft des Registrierungsschlüssels. Dies ist eine Eigenschaft des Microsoft .NET Framework-Objekts, das den Registrierungsschlüssel und keinen Registrierungseintrag darstellt. Der Befehl verwendet die ToUpper()- Methode des RemotePath-Werts , bei dem es sich um eine Zeichenfolge REG_SZ handelt.

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

Beispiel 5: Verwenden der $null automatischen Variablen

In diesem Beispiel wird die Auswirkung der Verleitung der $null automatischen Variablen an das ForEach-Object Cmdlet veranschaulicht.

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

Hello
Hello
Hello
Hello

Da PowerShell als expliziter Platzhalter behandelt wird $null , generiert das ForEach-Object Cmdlet einen Wert wie $null für andere Objekte, die an ihn weitergeleitet werden.

Beispiel 6: Abrufen von Eigenschaftswerten

In diesem Beispiel wird der Wert der Path-Eigenschaft aller installierten PowerShell-Module mithilfe des MemberName-Parameters des ForEach-Object Cmdlets abgerufen.

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

Der zweite Befehl entspricht dem ersten. Er verwendet den Foreach Alias des ForEach-Object Cmdlets und übergibt den Namen des MemberName-Parameters , der optional ist.

Das ForEach-Object Cmdlet ist nützlich für das Abrufen von Eigenschaftswerten, da er den Wert erhält, ohne den Typ zu ändern, im Gegensatz zu den Format-Cmdlets oder dem Select-Object Cmdlet, die den Eigenschaftswerttyp ändern.

Beispiel 7: Aufteilen von Modulnamen in Komponentennamen

In diesem Beispiel werden drei Methoden gezeigt, um zwei punkttrennte Modulnamen in ihre Komponentennamen aufzuteilen. Die Befehle rufen die Split-Methode von Zeichenfolgen auf. Die drei Befehle verwenden unterschiedliche Syntax, sind aber äquivalent und austauschbar. Die Ausgabe ist für alle drei Fälle identisch.

"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 "."

Microsoft
PowerShell
Core
Microsoft
PowerShell
Host

Der erste Befehl verwendet die herkömmliche Syntax, die einen Skriptblock und den aktuellen Objektoperator $_enthält. Es verwendet die Punktsyntax zum Angeben der Methode und die Klammern, um das Trennzeichenargument einzuschließen.

Der zweite Befehl verwendet den MemberName-Parameter , um die Split-Methode und den ArgumentList-Parameter anzugeben, um den Punkt (.) als Trennzeichen zu identifizieren.

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

Beispiel 8: Verwenden des ForEach-Objekts mit zwei Skriptblöcken

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

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

begin
process
process

Beispiel 9: Verwenden des ForEach-Objekts mit mehr als zwei Skriptblöcken

In diesem Beispiel übergeben wir vier Skriptblöcke positional. Alle Skriptblöcke binden an den Process-Parameter . Sie werden jedoch so behandelt, als ob sie an die Parameter "Begin", "Process" und "End " übergeben wurden.

1..2 | ForEach-Object { 'begin' } { 'process A' }  { 'process B' } { 'end' }

begin
process A
process B
process A
process B
end

Hinweis

Der erste Skriptblock wird immer dem begin Block zugeordnet, der letzte Block wird dem end Block zugeordnet, und die beiden mittleren Blöcke werden dem process Block zugeordnet.

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

Wie im vorherigen Beispiel gezeigt, werden mehrere Skriptblöcke, die mithilfe des Process-Parameters ü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 $null

one
two
three
one
two
three

Beispiel 11: Ausführen eines langsamen Skripts in parallelen Batches

In diesem Beispiel wird ein Skriptblock ausgeführt, der eine Zeichenfolge auswertet und für eine Sekunde ruhet.

$Message = "Output:"

1..8 | ForEach-Object -Parallel {
    "$using:Message $_"
    Start-Sleep 1
} -ThrottleLimit 4

Output: 1
Output: 2
Output: 3
Output: 4
Output: 5
Output: 6
Output: 7
Output: 8

Der ThrottleLimit-Parameterwert ist auf 4 festgelegt, sodass die Eingabe in Batches von vier verarbeitet wird. Das $using: Schlüsselwort wird verwendet, um die $Message Variable an jeden parallelen Skriptblock zu übergeben.

Beispiel 12: Paralleles Abrufen von Protokolleinträgen

In diesem Beispiel werden 50.000 Protokolleinträge aus 5 Systemprotokollen auf einem lokalen Windows-Computer abgerufen.

$logNames = 'Security', 'Application', 'System', 'Windows PowerShell',
    'Microsoft-Windows-Store/Operational'

$logEntries = $logNames | ForEach-Object -Parallel {
    Get-WinEvent -LogName $_ -MaxEvents 10000
} -ThrottleLimit 5

$logEntries.Count

50000

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 Auftrag erstellt, der einen Skriptblock parallel, zwei gleichzeitig ausführt.

PS> $job = 1..10 | ForEach-Object -Parallel {
    "Output: $_"
    Start-Sleep 1
} -ThrottleLimit 2 -AsJob

PS> $job

Id     Name            PSJobTypeName   State         HasMoreData     Location      Command
--     ----            -------------   -----         -----------     --------      -------
23     Job23           PSTaskJob       Running       True            PowerShell    …

PS> $job.ChildJobs

Id     Name            PSJobTypeName   State         HasMoreData     Location      Command
--     ----            -------------   -----         -----------     --------      -------
24     Job24           PSTaskChildJob  Completed     True            PowerShell    …
25     Job25           PSTaskChildJob  Completed     True            PowerShell    …
26     Job26           PSTaskChildJob  Running       True            PowerShell    …
27     Job27           PSTaskChildJob  Running       True            PowerShell    …
28     Job28           PSTaskChildJob  NotStarted    False           PowerShell    …
29     Job29           PSTaskChildJob  NotStarted    False           PowerShell    …
30     Job30           PSTaskChildJob  NotStarted    False           PowerShell    …
31     Job31           PSTaskChildJob  NotStarted    False           PowerShell    …
32     Job32           PSTaskChildJob  NotStarted    False           PowerShell    …
33     Job33           PSTaskChildJob  NotStarted    False           PowerShell    …

Der ThrottleLimit-Parameter begrenzt die Anzahl paralleler Skriptblöcke, die gleichzeitig ausgeführt werden. Der AsJob-Parameter bewirkt, dass das ForEach-Object Cmdlet ein Auftragsobjekt zurückgibt, anstatt die Streamingausgabe an die Konsole zu senden. Die $job Variable empfängt das Auftragsobjekt, das Ausgabedaten sammelt und den Ausführungszustand überwacht. Die $job.ChildJobs Eigenschaft enthält die untergeordneten Aufträge, die die parallelen Skriptblöcke ausführen.

Beispiel 14: Verwenden von threadsicheren Variablenverweisen

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

$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new()
Get-Process | ForEach-Object -Parallel {
    $dict = $using:threadSafeDictionary
    $dict.TryAdd($_.ProcessName, $_)
}

$threadSafeDictionary["pwsh"]

NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
     82    82.87     130.85      15.55    2808   2 pwsh

Eine einzelne Instanz eines gleichzeitigenDictionary-Objekts wird an jeden Skriptblock übergeben, um die Objekte zu sammeln. Da das gleichzeitigeDictionary threadsicher ist, ist es sicher, von jedem parallelen Skript geändert zu werden. Ein nicht threadsicheres Objekt, z . B. System.Collections.Generic.Dictionary, wäre hier nicht sicher zu verwenden.

Hinweis

Dieses Beispiel ist eine ineffiziente Verwendung des Parallel-Parameters . Das Skript fügt das Eingabeobjekt einem gleichzeitigen Wörterbuchobjekt hinzu. Es ist trivial und lohnt sich nicht den Aufwand, jedes Skript in einem separaten Thread auf sich zu aufrufen. Die Ausführung ForEach-Object ohne parallelen Schalter ist effizienter und schneller. Dieses Beispiel soll nur veranschaulichen, wie Threadsichere Variablen verwendet werden.

Beispiel 15: Schreiben von Fehlern mit paralleler Ausführung

In diesem Beispiel wird parallel in den Fehlerdatenstrom geschrieben, wobei die Reihenfolge der geschriebenen Fehler zufällig ist.

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

Write-Error: Error: 1
Write-Error: Error: 3
Write-Error: Error: 2

Beispiel 16: Beenden von Fehlern in paralleler Ausführung

In diesem Beispiel wird ein Beendigungsfehler in einem parallel ausgeführten Scriptblock veranschaulicht.

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

    Write-Output "Output: $_"
}

Exception: Terminating Error: 3
Output: 1
Output: 4
Output: 2
Output: 5

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

Hinweis

PipelineVariable common parameter variables are not supported in Foreach-Object -Parallel scenarios even with the $using: keyword.

Beispiel 17: Übergeben von Variablen in geschachtelten parallelen Skript ScriptBlockSet

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

$test1 = 'TestA'
1..2 | Foreach-Object -Parallel {
    $using:test1
}

TestA
TestA

# 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' can't be retrieved because it has
     | not been set in the local session.

Der geschachtelte Scriptblock kann nicht auf die $test2 Variable zugreifen, und ein Fehler wird ausgelöst.

Beispiel 18: Erstellen mehrerer Aufträge, die Skripts parallel ausführen

Der Parameter ThrottleLimit begrenzt die Anzahl der parallelen Skripts, die während jeder Instanz von ForEach-Object -Parallel. Es beschränkt nicht die Anzahl der Aufträge, die bei Verwendung des AsJob-Parameters erstellt werden können. Da Aufträge selbst gleichzeitig ausgeführt werden, ist es möglich, mehrere parallele Aufträge zu erstellen, die jeweils bis zur Drosselungsgrenze der Anzahl gleichzeitiger Scriptblocks ausgeführt werden.

$jobs = for ($i=0; $i -lt 10; $i++) {
    1..10 | ForEach-Object -Parallel {
        ./RunMyScript.ps1
    } -AsJob -ThrottleLimit 5
}

$jobs | Receive-Job -Wait

In diesem Beispiel werden 10 ausgeführte Aufträge erstellt. Jeder Auftrag führt nicht mehr als fünf Skripts gleichzeitig aus. Die Gesamtzahl der gleichzeitig ausgeführten Instanzen ist auf 50 beschränkt (10 Aufträge mal das ThrottleLimit von 5).

Parameter

-ArgumentList

Gibt ein Array von Argumenten für einen Methodenaufruf an. Weitere Informationen zum Verhalten von ArgumentList finden Sie unter about_Splatting.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:	Object[]
Aliase:	Args
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-AsJob

Bewirkt, dass der parallele Aufruf als PowerShell-Auftrag ausgeführt wird. Ein einzelnes Auftragsobjekt wird anstelle der Ausgabe der ausgeführten Skriptblöcke zurückgegeben. Das Auftragsobjekt enthält untergeordnete Aufträge für jeden parallelen Skriptblock, der ausgeführt wird. Sie können das Auftragsobjekt mit einem der PowerShell-Auftrags-Cmdlets verwenden, um den ausgeführten Zustand anzuzeigen und Daten abzurufen.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Typ:	SwitchParameter
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-Begin

Gibt einen Skriptblock an, der ausgeführt wird, bevor dieses Cmdlet Eingabeobjekte verarbeitet. Dieser Skriptblock wird nur einmal für die gesamte Pipeline ausgeführt. Weitere Informationen zum begin Block finden Sie unter about_Functions.

Typ:	ScriptBlock
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-Confirm

Hiermit werden Sie vor der Ausführung des Cmdlets zur Bestätigung aufgefordert.

Typ:	SwitchParameter
Aliase:	cf
Position:	Named
Standardwert:	False
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-End

Gibt einen Skriptblock an, der ausgeführt wird, nachdem dieses Cmdlet alle Eingabeobjekte verarbeitet hat. Dieser Skriptblock wird nur einmal für die gesamte Pipeline ausgeführt. Weitere Informationen zum end Block finden Sie unter about_Functions.

Typ:	ScriptBlock
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-InputObject

Gibt die Eingabeobjekte an. ForEach-Object führt die Skriptblock- oder Operationsanweisung für jedes Eingabeobjekt aus. Geben Sie eine Variable ein, die die Objekte enthält, oder geben Sie einen Befehl oder einen Ausdruck ein, mit dem die Objekte abgerufen werden.

Wenn Sie den InputObject-Parameter mit ForEach-Object, anstelle von Befehlsergebnissen ForEach-Objectan die Leitung, verwenden, wird der InputObject-Wert als einzelnes Objekt behandelt. Dies gilt auch dann, wenn es sich bei dem Wert um eine Auflistung handelt, die das Ergebnis eines Befehls ist, z -InputObject (Get-Process). B. . Da InputObject keine einzelnen Eigenschaften aus einem Array oder einer Auflistung von Objekten zurückgeben kann, empfehlen wir, dass Sie ForEach-Object , wie in den Beispielen in diesem Thema gezeigt, Vorgänge für eine Auflistung von Objekten für objekte ausführen, die bestimmte Werte in definierten Eigenschaften aufweisen, in der Pipeline verwenden ForEach-Object .

Typ:	PSObject
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	True
Platzhalterzeichen akzeptieren:	False

-MemberName

Gibt den Namen der Membereigenschaft an, die aufgerufen werden soll, oder die Elementmethode, die aufgerufen werden soll. Die Member müssen Instanzm, nicht statische Member sein.

Wildcardzeichen sind zulässig, funktionieren jedoch nur, wenn die resultierende Zeichenfolge in einen eindeutigen Wert aufgelöst wird. Wenn Sie z. B. ausführen Get-Process | ForEach -MemberName *Name, entspricht das Wildcardmuster mehreren Membern, die dazu führen, dass der Befehl fehlschlägt.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:	String
Position:	0
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	True

-Parallel

Gibt den Skriptblock an, der für die parallele Verarbeitung von Eingabeobjekten verwendet werden soll. Geben Sie einen Skriptblock ein, der den Vorgang beschreibt.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Typ:	ScriptBlock
Position:	Named
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-Process

Gibt den Vorgang an, der für jedes Eingabeobjekt ausgeführt wird. Dieser Skriptblock wird für jedes Objekt in der Pipeline ausgeführt. Weitere Informationen zum process Block finden Sie unter about_Functions.

Wenn Sie dem Process-Parameter mehrere Skriptblöcke bereitstellen, wird der erste Skriptblock immer dem begin Block zugeordnet. Wenn nur zwei Skriptblöcke vorhanden sind, wird der zweite Block dem process Block zugeordnet. Wenn drei oder mehr Skriptblöcke vorhanden sind, wird der erste Skriptblock immer dem begin Block zugeordnet, der letzte Block wird dem end Block zugeordnet, und die mittleren Blöcke werden dem process Block zugeordnet.

Typ:	ScriptBlock[]
Position:	0
Standardwert:	None
Erforderlich:	True
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-RemainingScripts

Gibt alle Skriptblöcke an, die nicht vom Process-Parameter übernommen werden.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:	ScriptBlock[]
Position:	Named
Standardwert:	None
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-ThrottleLimit

Gibt die Anzahl der Skriptblöcke an, die parallel ausgeführt werden. Eingabeobjekte werden blockiert, bis die Anzahl der ausgeführten Skriptblocks unter das ThrottleLimit fällt. Der Standardwert ist 5.

Der Parameter ThrottleLimit begrenzt die Anzahl der parallelen Skripts, die während jeder Instanz von ForEach-Object -Parallel. Es beschränkt nicht die Anzahl der Aufträge, die bei Verwendung des AsJob-Parameters erstellt werden können. Da Aufträge selbst gleichzeitig ausgeführt werden, ist es möglich, eine Reihe paralleler Aufträge zu erstellen, die jeweils bis zur Drosselungsgrenze der Anzahl gleichzeitiger Skriptblocks ausgeführt werden.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Typ:	Int32
Position:	Named
Standardwert:	5
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-TimeoutSeconds

Gibt die Anzahl der Sekunden an, bis alle Eingaben parallel verarbeitet werden. Nach dem angegebenen Timeout werden alle ausgeführten Skripts beendet. Alle verbleibenden zu verarbeitenden Eingabeobjekte werden ignoriert. Der Standardwert der Deaktivierungen des 0 Timeouts und ForEach-Object -Parallel kann unbegrenzt ausgeführt werden. Durch die Eingabe von STRG+C an der Befehlszeile wird ein ausgeführter ForEach-Object -Parallel Befehl beendet. Dieser Parameter kann nicht zusammen mit dem AsJob-Parameter verwendet werden.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Typ:	Int32
Position:	Named
Standardwert:	0
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-UseNewRunspace

Bewirkt, dass der parallele Aufruf für jede Schleifeniteration einen neuen Runspace erstellt, anstatt Runspaces aus dem Runspace-Pool erneut zu verwenden.

Dieser Parameter wurde in PowerShell 7.1 eingeführt.

Typ:	SwitchParameter
Position:	Named
Standardwert:	False
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

-WhatIf

Zeigt, was geschieht, wenn das Cmdlet ausgeführt wird. Das Cmdlet wird nicht ausgeführt.

Typ:	SwitchParameter
Aliase:	wi
Position:	Named
Standardwert:	False
Erforderlich:	False
Pipelineeingabe akzeptieren:	False
Platzhalterzeichen akzeptieren:	False

Eingaben

PSObject

Sie können jedes Objekt an dieses Cmdlet weiterleiten.

Ausgaben

PSObject

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

Hinweise

PowerShell enthält die folgenden Aliase für ForEach-Object:

• Alle Plattformen:
  • %
  • foreach

Das ForEach-Object Cmdlet funktioniert ähnlich wie die Foreach-Anweisung , mit der Ausnahme, dass Sie keine Eingabe an eine Foreach-Anweisung weiterleiten können. Weitere Informationen zur Foreach-Anweisung finden Sie unter about_Foreach.

Ab PowerShell 4.0 Where ForEach wurden Methoden für die Verwendung mit Sammlungen hinzugefügt. Weitere Informationen zu diesen neuen Methoden finden Sie hier about_arrays

Verwenden von ForEach-Object -Parallel:

• ForEach-Object -Parallel führt jeden Skriptblock in einem neuen Runspace aus. Die neuen Runspaces schaffen deutlich mehr Aufwand als die Ausführung ForEach-Object mit sequenzieller Verarbeitung. Es ist wichtig, Parallel zu verwenden, bei dem der Aufwand für die parallele Ausführung im Vergleich zur Ausführung des Skriptblocks gering ist. Zum Beispiel:

  • Berechnen intensiver Skripts auf Multi-Core-Computern
  • Skripts, die zeitlang auf Ergebnisse warten oder Dateivorgänge ausführen

  Die Verwendung des Parameters Parallel kann dazu führen, dass Skripts viel langsamer ausgeführt werden als normal. Insbesondere, wenn die parallelen Skripts trivial sind. Experimentieren Sie mit Parallel , um zu entdecken, wo es nützlich sein kann.

• Bei paralleler Ausführung können Objekte, die mit ScriptProperties oder ScriptMethods versehen sind, nicht ordnungsgemäß funktionieren, wenn sie in einem anderen Runspace ausgeführt werden als die Skripts ursprünglich angefügt wurden.

  Scriptblock-Aufruf versucht immer, in seinem Startrunspace auszuführen, unabhängig davon, wo er tatsächlich aufgerufen wird. Erstellt jedoch temporäre Runspaces, ForEach-Object -Parallel die nach der Verwendung gelöscht werden, sodass es keine Runspace für die Skripts mehr gibt.

  Dieses Verhalten kann funktionieren, solange der Startrunspace noch vorhanden ist. Möglicherweise erhalten Sie jedoch nicht das gewünschte Ergebnis, wenn das Skript von externen Variablen abhängig ist, die nur im Runspace des Aufrufers und nicht vom Startlaufbereich vorhanden sind.

• Nicht beendete Fehler werden in den Cmdlet-Fehlerdatenstrom geschrieben, da sie in parallel ausgeführten Scriptblocks auftreten. Da die Ausführungsreihenfolge für paralleles Skriptblock nicht deterministisch ist, ist die Reihenfolge, in der Fehler im Fehlerdatenstrom auftreten, zufällig. Ebenso werden Nachrichten, die in andere Datenströme geschrieben wurden, z. B. Warnung, Ausführlich oder Informationen, in diese Datenströme in unbestimmter Reihenfolge geschrieben.

  Beenden von Fehlern, z. B. Ausnahmen, beenden die einzelne parallele Instanz der Scriptblocks, in denen sie auftreten. Ein Beendigungsfehler in einem Scriptblocks kann nicht dazu führen, dass das Foreach-Object Cmdlet beendet wird. Die anderen Skriptblocks, die parallel ausgeführt werden, werden weiterhin ausgeführt, es sei denn, sie treten auch auf einen Beendigungsfehler auf. Der Beendigungsfehler wird in den Fehlerdatenstrom als ErrorRecord mit einer FullyQualifiedErrorId von PSTaskExceptiongeschrieben. Beendigungsfehler können mithilfe von PowerShell try/catch oder trap Blöcken in nicht beendete Fehler konvertiert werden.

• PipelineVariable common parameter variables are not supported in parallel scenarios even with the $using: keyword.

  Wichtig

  Der ForEach-Object -Parallel Parametersatz führt Skriptblöcke parallel in separaten Prozessthreads aus. Mit $using: dem Schlüsselwort können Variablenverweise aus dem Cmdlet-Aufrufthread an jeden ausgeführten Skriptblockthread übergeben werden. Da die Skriptblöcke in verschiedenen Threads ausgeführt werden, müssen die objektvariablen, die durch Verweis übergeben werden, sicher verwendet werden. Im Allgemeinen ist es sicher, aus referenzierten Objekten zu lesen, die sich nicht ändern. Wenn Sie den Objektstatus ändern müssen, müssen Sie threadsichere Objekte verwenden, z. B. .NET System.Collection.Gleichzeitige Typen (Siehe Beispiel 14).

Ähnliche Themen

• Compare-Object
• Where-Object
• Group-Object
• Measure-Object
• New-Object
• Select-Object
• Sort-Object
• Tee-Object