ForEach-Object

  • Referenz
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 Auflistung von Eingabeobjekten aus. Die Eingabeobjekte können an das Cmdlet weitergeleitet oder mit dem InputObject-Parameter angegeben werden.

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

  • Skriptblock. 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 der einzelnen Prozesse auf dem Computer ab.

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

    ForEach-Object unterstützt die beginBlöcke , processund end , wie in about_functions beschrieben.

    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 mehr der natürlichen Sprache entspricht. 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 ebenfalls den Wert der ProcessName-Eigenschaft der einzelnen Prozesse 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 Parameter ThrottleLimit schränkt die Anzahl parallel ausgeführter Skripts ein. Verwenden Sie wie zuvor die $_ Variable, um das aktuelle Eingabeobjekt im Skriptblock darzustellen. Verwenden Sie die $using: Schlüsselwort (keyword), 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 ein großer Leistungs- und Ressourcentreffer sein, wenn die Arbeit, die Sie ausführen, im Vergleich zum Erstellen neuer Runspaces gering ist oder wenn es viele Iterationen gibt, die 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 mit dem UseNewRunspace-Switch erstellen.

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

    Weitere Informationen finden Sie im Abschnitt NOTES dieses Artikels.

Beispiele

Beispiel 1: Teilen ganzer Zahlen in einem Array

In diesem Beispiel wird ein Array von drei ganzen Zahlen verwendet und jede einzelne durch 1024 unterteilt.

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 seiner 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: Ausführen der neuesten Systemereignisse

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 leitet sie an das ForEach-Object Cmdlet weiter. Der Begin-Parameter zeigt das aktuelle Datum und die Uhrzeit. Als Nächstes erstellt der Process-Parameter mithilfe des Out-File Cmdlets eine Textdatei mit dem Namen events.txt und speichert die Nachrichteneigenschaft jedes Ereignisses in dieser Datei. Schließlich wird der End-Parameter verwendet, um das Datum und die Uhrzeit anzuzeigen, nachdem die gesamte Verarbeitung abgeschlossen ist.

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 Netzwerklaufwerk dar, das bei der Anmeldung wieder verbunden wird. Der RemotePath-Eintrag enthält den UNC-Pfad des verbundenen Laufwerks. Wenn Sie z. B. das E: Laufwerk \\Server\Sharezuordnen, wird in ein E-Unterschlüssel erstellt, wobei HKCU:\Network der RemotePath-Registrierungswert auf \\Server\Sharefestgelegt ist.

Der Befehl verwendet das Get-ItemProperty Cmdlet, um alle Unterschlüssel des Netzwerkschlüssels und des Set-ItemProperty Cmdlets abzurufen, um den Wert des RemotePath-Registrierungseintrags in jedem Schlüssel zu ändern. Set-ItemProperty Im Befehl 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 keinen Registrierungseintrag darstellt. Der Befehl verwendet die ToUpper() -Methode des RemotePath-Werts , bei dem es sich um eine Zeichenfolge REG_SZ.

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 des Pipings der $null automatischen Variablen an das ForEach-Object Cmdlet veranschaulicht.

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

Hello
Hello
Hello
Hello

Da PowerShell als expliziten $null Platzhalter behandelt, generiert das ForEach-Object Cmdlet einen Wert für $null wie für andere Objekte, die an es 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. Es verwendet den Foreach Alias des ForEach-Object Cmdlets und lässt den Namen des MemberName-Parameters aus, der optional ist.

Das ForEach-Object Cmdlet ist nützlich zum Abrufen von Eigenschaftswerten, da es 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 Möglichkeiten gezeigt, zwei punkttrennte Modulnamen in ihre Komponentennamen aufzuteilen. Die Befehle rufen die SplitMethode 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 geteiltes Trennzeichen zu identifizieren.

Der dritte Befehl verwendet den Foreach-Alias des ForEach-Object Cmdlets und verzichtet auf die Namen der optionalen Parameter MemberName und ArgumentList .

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 wären sie an die Parameter Begin, Process und End übergeben worden.

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 mit dem Process-Parameter ü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 von langsamen Skripts in parallelen Batches

In diesem Beispiel wird ein Skriptblock ausgeführt, der eine Zeichenfolge auswertet und eine Sekunde lang 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 Wert des ThrottleLimit-Parameters ist auf 4 festgelegt, sodass die Eingabe in vier Batches verarbeitet wird. Die $using: Schlüsselwort (keyword) 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 ThrottleLimit-Parameter stellt sicher, dass alle fünf Skriptblöcke gleichzeitig ausgeführt werden.

Beispiel 13: Parallele Ausführung als Auftrag

In diesem Beispiel wird ein Auftrag erstellt, der einen Skriptblock parallel ausführt, zwei gleichzeitig.

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 schränkt die Anzahl parallel ausgeführter Skriptblöcke ein. Der AsJob-Parameter bewirkt, dass das ForEach-Object Cmdlet ein Auftragsobjekt zurückgibt, anstatt die Ausgabe an die Konsole zu streamen. 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 Threadsicherheitsvariablenreferenzen

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

Ein einzelner instance eines ConcurrentDictionary-Objekts wird an jeden Skriptblock übergeben, um die Objekte zu sammeln. Da concurrentDictionary threadsicher ist, kann es von jedem parallelen Skript geändert werden. Ein nicht threadsicheres Objekt, z. B . System.Collections.Generic.Dictionary, kann hier nicht sicher verwendet werden.

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, jedes Skript in einem separaten Thread aufrufen zu müssen. Die Ausführung ForEach-Object ohne parallelen Switch ist effizienter und schneller. In diesem Beispiel soll nur veranschaulicht werden, wie sichere Threadvariablen verwendet werden.

Beispiel 15: Schreibfehler mit paralleler Ausführung

In diesem Beispiel wird parallel in den Fehlerstream 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 der parallelen Ausführung

In diesem Beispiel wird ein Abbruchfehler in einem parallel ausgeführten Skriptblock 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 Skriptblock für diese Iteration beendet wurde.

Hinweis

PipelineVariable allgemeine Parametervariablen werden in Foreach-Object -Parallel Szenarien nicht unterstützt, auch nicht mit dem $using: Schlüsselwort (keyword).

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

Sie können eine Variable außerhalb eines Foreach-Object -Parallel bereichsbezogenen Skriptblocks erstellen und sie im Skriptblock mit dem $using Schlüsselwort (keyword) 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 Skriptblock 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 ThrottleLimit-Parameter schränkt die Anzahl paralleler Skripts ein, die während jeder instance von ForEach-Object -Parallelausgeführt werden. Die Anzahl von Aufträgen, die mit dem AsJob-Parameter erstellt werden können, wird nicht eingeschränkt. Da Aufträge selbst gleichzeitig ausgeführt werden, ist es möglich, mehrere parallele Aufträge zu erstellen, die jeweils bis zum Drosselungslimit der Anzahl gleichzeitiger Skriptblocks 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 5 Skripts gleichzeitig aus. Die Gesamtzahl der gleichzeitig ausgeführten Instanzen ist auf 50 begrenzt (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.

Type:Object[]
Aliases:Args
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AsJob

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

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Gibt die Eingabeobjekte an. ForEach-Object führt den Skriptblock oder die Vorgangsanweisung 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-Objectverwenden, anstatt Befehlsergebnisse an zu pipieren, ForEach-Objectwird 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. B -InputObject (Get-Process). . Da InputObject keine einzelnen Eigenschaften aus einem Array oder einer Auflistung von Objekten zurückgeben kann, wird empfohlen, dass Sie, wie in den Beispielen in diesem Thema gezeigt, in der Pipeline verwendenForEach-Object, wenn Sie zum Ausführen von Vorgängen für eine Auflistung von Objekten verwendenForEach-Object, die bestimmte Werte in definierten Eigenschaften aufweisen.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-MemberName

Gibt den Namen der abzurufenden Membereigenschaft oder der aufzurufenden Membermethode an. Die Member müssen instance Member sein, nicht statische Elemente.

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

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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.

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 mehrere Skriptblöcke für den Parameter Process bereitstellen, wird dem Block immer der erste Skriptblock zugeordnet begin . 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.

Type:ScriptBlock[]
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-RemainingScripts

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

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Type:ScriptBlock[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThrottleLimit

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

Der Parameter ThrottleLimit begrenzt die Anzahl paralleler Skripts, die während der einzelnen instance von ForEach-Object -Parallelausgeführt werden. Die Anzahl von Aufträgen, die erstellt werden können, wenn der AsJob-Parameter verwendet wird, wird nicht eingeschränkt. Da Aufträge selbst gleichzeitig ausgeführt werden, ist es möglich, eine Reihe von parallelen Aufträgen zu erstellen, die jeweils bis zur Drosselungsgrenze anzahl gleichzeitiger Skriptblocks ausgeführt werden.

Dieser Parameter wurde in PowerShell 7.0 eingeführt.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSeconds

Gibt die Anzahl von Sekunden an, die auf die parallele Verarbeitung aller Eingaben gewartet werden soll. Nach dem angegebenen Timeout werden alle ausgeführten Skripts beendet. Alle verbleibenden zu verarbeitenden Eingabeobjekte werden ignoriert. Der Standardwert von 0 deaktiviert das Timeout und ForEach-Object -Parallel kann unbegrenzt ausgeführt werden. Durch Drücken 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.

Type:Int32
Position:Named
Default value:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseNewRunspace

Bewirkt, dass der parallele Aufruf einen neuen Runspace für jede Schleifeniteration erstellt, anstatt Runspaces aus dem Runspacepool wiederzuverwenden.

Dieser Parameter wurde in PowerShell 7.1 eingeführt.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

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

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 WhereForEach wurden Methoden zur 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 verursachen deutlich mehr Mehraufwand als die Ausführung ForEach-Object bei sequenzieller Verarbeitung. Es ist wichtig, Parallel zu verwenden, wenn der Aufwand für die parallele Ausführung im Vergleich zu der Arbeit, die der Skriptblock ausführt, gering ist. Beispiel:

    • Computeintensive Skripts auf Computern mit mehreren Kernen
    • Skripts, die Zeit damit verbringen, auf Ergebnisse zu warten oder Dateivorgänge auszuführen

    Die Verwendung des Parallel-Parameters kann dazu führen, dass Skripts viel langsamer als normal ausgeführt werden. Insbesondere, wenn die parallelen Skripts trivial sind. Experimentieren Sie mit Parallel , um herauszufinden, wo dies von Vorteil sein kann.

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

    Der Aufruf des Skriptblocks 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 keinen Runspace mehr gibt, in dem die Skripts ausgeführt werden können.

    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 im Startrunspace vorhanden sind.

  • Nicht beendende Fehler werden in den Cmdlet-Fehlerstream geschrieben, wie sie in parallel ausgeführten Skriptblocks auftreten. Da die Ausführungsreihenfolge des parallelen Skriptblocks nicht deterministisch ist, ist die Reihenfolge, in der Fehler im Fehlerstream angezeigt werden, zufällig. Ebenso werden Nachrichten, die in andere Datenströme geschrieben wurden, z. B. Warnungen, ausführliche Informationen oder Informationen, in unbestimmter Reihenfolge in diese Datenströme geschrieben.

    Beim Beenden von Fehlern, z. B. Ausnahmen, werden die einzelnen parallelen instance der Skriptblöcke, in denen sie auftreten, beendet. Ein Abbruchfehler in einem Skriptblock führt möglicherweise nicht zum Beenden des Foreach-Object Cmdlets. Die anderen Skriptblöcke, die parallel ausgeführt werden, werden weiterhin ausgeführt, es sei denn, sie stoßen ebenfalls auf einen Abbruchfehler. Der beendende Fehler wird als ErrorRecord mit der FullyQualifiedErrorId von PSTaskExceptionin den Fehlerdatenstrom geschrieben. Das Beenden von Fehlern kann mithilfe von PowerShell try/catch oder trap Blöcken in Nicht-Beenden-Fehler konvertiert werden.

  • PipelineVariable allgemeine Parametervariablen werden in parallelen Szenarien nicht unterstützt, auch nicht mit dem $using: Schlüsselwort (keyword).

    Wichtig

    Der ForEach-Object -Parallel Parametersatz führt Skriptblöcke parallel für separate Prozessthreads aus. Die $using: Schlüsselwort (keyword) 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 als Verweis übergebenen Objektvariablen sicher verwendet werden. In der Regel ist es sicher, von Objekten zu lesen, auf die verwiesen wird, die sich nicht ändern. Wenn Sie den Objektzustand ändern müssen, müssen Sie threadsichere Objekte wie .NET System.Collection.Concurrent-Typen verwenden (siehe Beispiel 14).