ForEach-Object

Modul:

Microsoft.PowerShell.Core Module

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

Syntax

ScriptBlockSet (Standardwert)

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

PropertyAndMethodSet

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

ParallelParameterSet

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

Beschreibung

Das Cmdlet ForEach-Object 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.

• Skriptblocksyntax. Sie können einen Skriptblock verwenden, um den Vorgang anzugeben. Verwenden Sie im Skriptblock 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 processend beschriebenen Blöcke und 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.

• Vereinfachte Syntax. Mit der vereinfachten Syntax geben Sie einen Eigenschafts- oder Methodennamen des Objekts in der Pipeline an. ForEach-Object gibt den Wert der Eigenschaft oder Methode für jedes Objekt in der Pipeline zurück.

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

  Get-Process | ForEach-Object ProcessName

  Die vereinfachte Syntax wurde in Windows PowerShell 3.0 eingeführt. Weitere Informationen finden Sie unter about_Simplified_Syntax.

• 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 den Using: Bereichsmodifizierer, um variable Verweise auf 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 Cmdlet ForEach-Object. 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 das Formular 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 ändert, ist das cmdlet ForEach-Object 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 Cmdlet ForEach-Object veranschaulicht.

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

Hello
Hello
Hello
Hello

Da PowerShell $null als expliziten Platzhalter behandelt, generiert das cmdlet ForEach-Object einen Wert für $null wie für andere Objekte, die an sie 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, aber sie sind gleichwertig 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. Sie verwendet die Punktsyntax, um die Methode und Klammern anzugeben, 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 von ForEach-Object 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 von ForEach-Object 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. Der Using: Bereichsmodifizierer 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-Objectohne 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

Variablen für allgemeine PipelineVariable-Parameter werden in Szenarien auch mit dem ForEach-Object -Parallel Bereichsmodifizierer Using: unterstützt.

Beispiel 17: Übergeben von Variablen in geschachtelten parallelen Skriptblocks

Sie können eine Variable außerhalb eines ForEach-Object -Parallel bereichsbezogenen Scriptblocks erstellen und innerhalb des Scriptblocks mit dem Using: Bereichsmodifizierer verwenden. Ab PowerShell 7.2 können Sie eine Variable innerhalb eines ForEach-Object -Parallel bereichsbezogenen Skriptblocks erstellen und in einem geschachtelten Scriptblock verwenden.

$test1 = 'TestA'
1..2 | ForEach-Object -Parallel {
    $Using:test1
    $test2 = 'TestB'
    1..2 | ForEach-Object -Parallel {
        $Using:test2
    }
}

TestA
TestA
TestB
TestB
TestB
TestB

Hinweis

In Versionen vor PowerShell 7.2 kann der geschachtelte Scriptblock 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 ArgumentListfinden Sie unter about_Splatting.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Parametereigenschaften

Typ:	Object[]
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	Argumente

Parametersätze

PropertyAndMethodSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ParallelParameterSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	ScriptBlock
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ScriptBlockSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-Confirm

Fordert Sie zur Bestätigung auf, bevor Sie das Cmdlet ausführen.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	vgl

Parametersätze

(All)

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	ScriptBlock
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ScriptBlockSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-InputObject

Gibt die Eingabeobjekte an. ForEach-Object führt die Skriptblock- oder Vorgangsanweisung für jedes Eingabeobjekt aus. Geben Sie eine Variable ein, die die Objekte enthält, oder geben Sie einen Befehl oder Ausdruck ein, der die Objekte ermittelt.

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, wenn es sich bei dem Wert um eine Auflistung handelt, die das Ergebnis eines Befehls ist, z. B. -InputObject (Get-Process). 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 .

Parametereigenschaften

Typ:	PSObject
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

(All)

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	True
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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. Get-Process | foreach -MemberName *Nameausführen, entspricht das Wildcardmuster mehreren Membern, die dazu führen, dass der Befehl fehlschlägt.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Parametereigenschaften

Typ:	String
Standardwert:	None
Unterstützt Platzhalter:	True
Nicht anzeigen:	False

Parametersätze

PropertyAndMethodSet

Position:	0
Obligatorisch.:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

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

Parametereigenschaften

Typ:	ScriptBlock
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ParallelParameterSet

Position:	Named
Obligatorisch.:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	ScriptBlock[]
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ScriptBlockSet

Position:	0
Obligatorisch.:	True
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-RemainingScripts

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

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Parametereigenschaften

Typ:	ScriptBlock[]
Standardwert:	None
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ScriptBlockSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	Int32
Standardwert:	5
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ParallelParameterSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	Int32
Standardwert:	0
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ParallelParameterSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	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.

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False

Parametersätze

ParallelParameterSet

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

-WhatIf

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

Parametereigenschaften

Typ:	SwitchParameter
Standardwert:	False
Unterstützt Platzhalter:	False
Nicht anzeigen:	False
Aliase:	Wi

Parametersätze

(All)

Position:	Named
Obligatorisch.:	False
Wert aus Pipeline:	False
Wert aus Pipeline nach dem Eigenschaftsnamen:	False
Wert aus verbleibenden Argumenten:	False

CommonParameters

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

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 wurden Where- und ForEach Methoden für die Verwendung mit Sammlungen hinzugefügt. Weitere Informationen zu diesen neuen Methoden finden Sie hier about_Arrays

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

• Variablen für allgemeine PipelineVariable-Parameter werden in parallelen Szenarien auch mit dem Using: Bereichsmodifizierer nicht unterstützt.

  Von Bedeutung

  Der ForEach-Object -Parallel Parametersatz führt Skriptblöcke parallel in separaten Prozessthreads aus. Der Using: Modifizierer ermöglicht das Übergeben von Variablenverweise aus dem Cmdlet-Aufrufthread an jeden ausgeführten Skriptblockthread. 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
• Gruppenobjekt
• Measure-Object
• Neues Objekt
• Select-Object
• Sort-Object
• Tee-Object