ForEach-Object

Moduł:: Microsoft.PowerShell.Core Module

Wykonuje operację względem każdego elementu w kolekcji obiektów wejściowych.

Składnia

ScriptBlockSet (Domyślna)

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

Opis

Polecenie cmdlet ForEach-Object wykonuje operację na każdym elemencie w kolekcji obiektów wejściowych. Obiekty wejściowe mogą być przesyłane potokami do polecenia cmdlet lub określone przy użyciu parametru InputObject .

Począwszy od programu Windows PowerShell 3.0, istnieją dwa różne sposoby konstruowania polecenia ForEach-Object.

Składnia bloku skryptu. Możesz użyć bloku skryptu, aby określić operację. W bloku skryptu użyj zmiennej $_ do reprezentowania bieżącego obiektu. Blok skryptu jest wartością parametru Process . Blok skryptu może zawierać dowolny skrypt programu PowerShell.

Na przykład następujące polecenie pobiera wartość właściwości ProcessName każdego procesu na komputerze.

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

ForEach-Object program obsługuje bloki begin, processi end zgodnie z opisem w about_Functions.

Uwaga / Notatka

Bloki skryptu są uruchamiane w zakresie wywołującego. W związku z tym bloki mają dostęp do zmiennych w tym zakresie i mogą tworzyć nowe zmienne, które utrzymują się w tym zakresie po zakończeniu wykonywania polecenia cmdlet.
Uproszczona składnia. Korzystając z uproszczonej składni, należy określić właściwość lub nazwę metody obiektu w potoku. ForEach-Object Zwraca wartość właściwości lub metody dla każdego obiektu w potoku.

Na przykład następujące polecenie pobiera również wartość właściwości ProcessName każdego procesu na komputerze.

Get-Process | ForEach-Object ProcessName

Uproszczona składnia została wprowadzona w programie Windows PowerShell 3.0. Aby uzyskać więcej informacji, zobacz about_Simplified_Syntax.
Blok równoległego uruchamiania skryptu. Począwszy od programu PowerShell 7.0, dostępny jest trzeci zestaw parametrów, który równolegle uruchamia każdy blok skryptu. Parametr ThrottleLimit ogranicza liczbę uruchomionych jednocześnie skryptów równoległych. Tak jak poprzednio, użyj zmiennej $_ do reprezentowania bieżącego obiektu wejściowego w bloku skryptu. Using: Użyj modyfikatora zakresu, aby przekazać odwołania do zmiennych do uruchomionego skryptu.

W programie PowerShell 7 zostanie utworzona nowa przestrzeń uruchamiania dla każdej iteracji pętli w celu zapewnienia maksymalnej izolacji. Może to być duża wydajność i trafienie zasobów, jeśli praca, którą wykonujesz, jest niewielka w porównaniu z tworzeniem nowych obszarów runspace lub jeśli istnieje wiele iteracji wykonujących znaczną pracę. Od wersji programu PowerShell 7.1 przestrzeń uruchomieniowa z puli obszarów runspace jest domyślnie ponownie wykorzystywana. Parametr ThrottleLimit ustawia rozmiar puli przestrzeni uruchomieniowej. Domyślny rozmiar puli przestrzeni uruchomieniowej to 5. Nadal można utworzyć nową przestrzeń runspace dla każdej iteracji przy użyciu przełącznika UseNewRunspace .

Domyślnie skrypty równoległe używają bieżącego katalogu roboczego obiektu wywołującego, który uruchamiał zadania równoległe.

Aby uzyskać więcej informacji, zobacz sekcję UWAGI tego artykułu.

Przykłady

Przykład 1. Dzielenie liczb całkowitych w tablicy

W tym przykładzie jest pobierana tablica trzech liczb całkowitych i dzieli każdą z nich o 1024.

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

29.296875
55.466796875
12.140625

Przykład 2. Pobieranie długości wszystkich plików w katalogu

W tym przykładzie pliki i katalogi są przetwarzane w katalogu instalacyjnym programu PowerShell $PSHOME.

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

Jeśli obiekt nie jest katalogiem, blok skryptu pobiera nazwę pliku, dzieli wartość właściwości Length przez 1024 i dodaje spację (""), aby oddzielić ją od następnego wpisu. Polecenie cmdlet używa właściwości PSIsContainer , aby określić, czy obiekt jest katalogiem.

Przykład 3. Działanie na najnowszych zdarzeniach systemowych

W tym przykładzie jest zapisywanych 1000 najnowszych zdarzeń z dziennika zdarzeń systemu do pliku tekstowego. Bieżący czas jest wyświetlany przed i po przetworzeniu zdarzeń.

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 pobiera 1000 najnowszych zdarzeń z dziennika zdarzeń systemu i potokuje je do polecenia cmdlet ForEach-Object. Parametr Begin wyświetla bieżącą datę i godzinę. Następnie parametr Process używa Out-File polecenia cmdlet do utworzenia pliku tekstowego o nazwie events.txt i przechowuje właściwość komunikatu każdego zdarzenia w tym pliku. Na koniec parametr End służy do wyświetlania daty i godziny po zakończeniu całego przetwarzania.

Przykład 4. Zmiana wartości klucza rejestru

Ten przykład zmienia wartość wpisu rejestru RemotePath we wszystkich podkluczach pod kluczem HKCU:\Network na wielkie litery.

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

Możesz użyć tego formatu, aby zmienić formularz lub zawartość wartości wpisu rejestru.

Każdy podklucz w kluczu sieci reprezentuje zamapowany dysk sieciowy, który ponownie łączy się podczas logowania. Wpis RemotePath zawiera ścieżkę UNC podłączonego dysku. Jeśli na przykład zamapujesz E: dysk na \\Server\Share, zostanie utworzony podklucz HKCU:\Network z wartością rejestru RemotePath ustawioną na \\Server\Sharewartość .

Polecenie używa Get-ItemProperty polecenia cmdlet , aby pobrać wszystkie podklucze klucza sieciowego i Set-ItemProperty polecenie cmdlet, aby zmienić wartość wpisu rejestru RemotePath w każdym kluczu. W poleceniu Set-ItemProperty ścieżka jest wartością właściwości PSPath klucza rejestru. Jest to właściwość obiektu programu Microsoft .NET Framework, która reprezentuje klucz rejestru, a nie wpis rejestru. Polecenie używa metody ToUpper() wartości RemotePath , która jest ciągiem REG_SZ.

Ponieważ Set-ItemProperty zmienia właściwość każdego klucza, polecenie cmdlet ForEach-Object jest wymagane do uzyskania dostępu do właściwości.

Przykład 5. Używanie zmiennej automatycznej $null

W tym przykładzie pokazano efekt potokowania $null zmiennej automatycznej do polecenia cmdlet ForEach-Object.

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

Hello
Hello
Hello
Hello

Ponieważ program PowerShell traktuje $null jako jawny symbol zastępczy, polecenie cmdlet ForEach-Object generuje wartość dla $null, podobnie jak w przypadku innych obiektów potokowych do niego.

Przykład 6. Pobieranie wartości właściwości

Ten przykład pobiera wartość właściwości Path wszystkich zainstalowanych modułów programu PowerShell przy użyciu parametru ForEach-Object polecenia cmdlet.

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

Drugie polecenie jest równoważne pierwszemu. Używa Foreach aliasu ForEach-Object polecenia cmdlet i pomija nazwę parametru MemberName , który jest opcjonalny.

Polecenie ForEach-Object cmdlet jest przydatne do pobierania wartości właściwości, ponieważ pobiera wartość bez zmiany typu, w przeciwieństwie do poleceń cmdlet Format lub Select-Object polecenia cmdlet, które zmieniają typ wartości właściwości.

Przykład 7. Dzielenie nazw modułów na nazwy składników

W tym przykładzie przedstawiono trzy sposoby dzielenia dwóch nazw modułów rozdzielonych kropkami na ich nazwy składników. Polecenia wywołają metodę Split ciągów. Trzy polecenia używają innej składni, ale są równoważne i zamienne. Dane wyjściowe są takie same dla wszystkich trzech przypadków.

"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

Pierwsze polecenie używa tradycyjnej składni, która zawiera blok skryptu i bieżący operator obiektu $_. Używa składni kropki, aby określić metodę i nawiasy, aby ująć argument ogranicznika.

Drugie polecenie używa parametru MemberName , aby określić metodę Split i parametr ArgumentList w celu zidentyfikowania kropki (.) jako ogranicznika podziału.

Trzecie polecenie używa foreach aliasu ForEach-Object polecenia cmdlet i pomija nazwy parametrów MemberName i ArgumentList , które są opcjonalne.

Przykład 8: Używanie ForEach-Object z dwoma blokami skryptów

W tym przykładzie przekazujemy dwa bloki skryptu pozycjonalnie. Wszystkie bloki skryptu są powiązane z parametrem Proces . Są one jednak traktowane tak, jakby zostały przekazane do parametrów Begin i Process .

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

begin
process
process

Przykład 9: Używanie ForEach-Object z więcej niż dwoma blokami skryptu

W tym przykładzie przekazujemy cztery bloki skryptu pozycjonalnie. Wszystkie bloki skryptu są powiązane z parametrem Proces . Są one jednak traktowane tak, jakby zostały przekazane do parametrów Begin, Process i End .

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

begin
process A
process B
process A
process B
end

Uwaga / Notatka

Pierwszy blok skryptu jest zawsze mapowany na blok begin, ostatni blok jest mapowany na blok end, a dwa środkowe bloki są mapowane na blok process.

Przykład 10: Uruchamianie wielu bloków skryptów dla każdego elementu potoku

Jak pokazano w poprzednim przykładzie, wiele bloków skryptu przekazanych przy użyciu parametru Proces jest mapowane na parametry Początek i Koniec . Aby uniknąć tego mapowania, należy podać jawne wartości parametrów Begin i End .

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

one
two
three
one
two
three

Przykład 11. Uruchamianie powolnego skryptu w równoległych partiach

W tym przykładzie jest uruchamiany blok skryptu, który ocenia ciąg i śpi przez jedną sekundę.

$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

Wartość parametru ThrottleLimit jest ustawiona na 4, dzięki czemu dane wejściowe są przetwarzane w partiach czterech. Modyfikator Using: zakresu służy do przekazywania zmiennej $Message do każdego bloku skryptu równoległego.

Przykład 12: Równoległe pobieranie wpisów dziennika

Ten przykład pobiera 50 000 wpisów dziennika z 5 dzienników systemowych na lokalnym komputerze z systemem Windows.

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

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

$logEntries.Count

Parametr Parallel określa blok skryptu uruchamiany równolegle dla każdej nazwy dziennika wejściowego. Parametr ThrottleLimit gwarantuje, że wszystkie pięć bloków skryptu jest uruchamianych w tym samym czasie.

Przykład 13: Uruchamianie równoległe jako zadanie

W tym przykładzie jest tworzone zadanie, które uruchamia blok skryptu równolegle, dwa naraz.

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    …

Parametr ThrottleLimit ogranicza liczbę bloków skryptów równoległych uruchomionych jednocześnie. Parametr AsJob powoduje, ForEach-Object że polecenie cmdlet zwraca obiekt zadania zamiast przesyłania strumieniowego danych wyjściowych do konsoli. Zmienna $job odbiera obiekt zadania, który zbiera dane wyjściowe i monitoruje stan działania. Właściwość $job.ChildJobs zawiera podrzędne zadania, które uruchamiają bloki skryptów równoległych.

Przykład 14: Używanie odwołań do zmiennych bezpiecznych wątków

W tym przykładzie są wywoływane bloki skryptów równolegle w celu zbierania unikatowych obiektów procesu.

$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

Pojedyncze wystąpienie obiektu ConcurrentDictionary jest przekazywane do każdego bloku skryptu w celu zbierania obiektów. Ponieważ element ConcurrentDictionary jest bezpieczny wątkiem, można bezpiecznie zmodyfikować go przez każdy skrypt równoległy. Obiekt niezwiązany z wątkiem, taki jak System.Collections.Generic.Dictionary, nie byłby bezpieczny do użycia w tym miejscu.

Uwaga / Notatka

W tym przykładzie jest nieefektywne użycie parametru Parallel . Skrypt dodaje obiekt wejściowy do współbieżnego obiektu słownika. Jest to proste i nie jest warte obciążenia związanego z wywoływaniem każdego skryptu w osobnym wątku. Uruchamianie ForEach-Object bez przełącznika równoległego jest wydajniejsze i szybsze. W tym przykładzie pokazano tylko, jak używać zmiennych bezpiecznych wątków.

Przykład 15: Pisanie błędów z wykonywaniem równoległym

W tym przykładzie jest zapisywany strumień błędów równolegle, gdzie kolejność zapisanych błędów jest losowa.

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

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

Przykład 16: Kończenie błędów w równoległym wykonywaniu

W tym przykładzie pokazano błąd zakończenia w jednym równoległym uruchomieniu skryptblocku.

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 nigdy nie jest zapisywany, ponieważ równoległy blok skryptu dla tej iteracji został zakończony.

Uwaga / Notatka

Typowe zmienne parametrów PipelineVariablenie są obsługiwane w ForEach-Object -Parallel scenariuszach nawet w Using: przypadku modyfikatora zakresu.

Przykład 17: Przekazywanie zmiennych w zagnieżdżonych blokach skryptów równoległych

Możesz utworzyć zmienną poza blokiem skryptu ForEach-Object -Parallel o określonym zakresie i użyć jej wewnątrz bloku skryptu z modyfikatorem Using: zakresu. Począwszy od programu PowerShell 7.2, można utworzyć zmienną wewnątrz ForEach-Object -Parallel bloku skryptu o określonym zakresie i użyć jej wewnątrz zagnieżdżonego bloku skryptów.

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

TestA
TestA
TestB
TestB
TestB
TestB

Uwaga / Notatka

W wersjach wcześniejszych niż program PowerShell 7.2 zagnieżdżony skryptblock nie może uzyskać dostępu do zmiennej $test2 i zostanie zgłoszony błąd.

Przykład 18: Tworzenie wielu zadań, które uruchamiają skrypty równolegle

Parametr ThrottleLimit ogranicza liczbę skryptów równoległych uruchomionych podczas każdego wystąpienia klasy ForEach-Object -Parallel. Nie ogranicza liczby zadań, które można utworzyć podczas korzystania z parametru AsJob . Ponieważ same zadania są uruchamiane współbieżnie, istnieje możliwość utworzenia wielu zadań równoległych, z których każdy działa do limitu ograniczenia liczby współbieżnych bloków skryptów.

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

$jobs | Receive-Job -Wait

W tym przykładzie jest tworzonych 10 uruchomionych zadań. Każde zadanie nie uruchamia więcej niż 5 skryptów jednocześnie. Łączna liczba wystąpień uruchomionych współbieżnie jest ograniczona do 50 (10 razy wartość throttleLimit 5).

Parametry

-ArgumentList

Określa tablicę argumentów do wywołania metody. Aby uzyskać więcej informacji na temat działania ArgumentList, zobacz about_Splatting.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	Object[]
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	Argumenty

Zestawy parametrów

PropertyAndMethodSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-AsJob

Powoduje uruchomienie równoległego wywołania jako zadania programu PowerShell. Pojedynczy obiekt zadania jest zwracany zamiast danych wyjściowych z uruchomionych bloków skryptu. Obiekt zadania zawiera podrzędne zadania dla każdego bloku skryptu równoległego, który jest uruchamiany. Możesz użyć obiektu zadania z dowolnymi poleceniami cmdlet zadania programu PowerShell, aby wyświetlić stan uruchomienia i pobrać dane.

Ten parametr został wprowadzony w programie PowerShell 7.0.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ParallelParameterSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Begin

Określa blok skryptu uruchamiany przed wykonaniem tego polecenia cmdlet przetwarza wszystkie obiekty wejściowe. Ten blok skryptu jest uruchamiany tylko raz dla całego potoku. Aby uzyskać więcej informacji na temat begin bloku, zobacz about_Functions.

Właściwości parametru

Typ:	ScriptBlock
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ScriptBlockSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Confirm

Prosi o potwierdzenie przed uruchomieniem cmdletu.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	por

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-End

Określa blok skryptu uruchamiany po tym poleceniu cmdlet przetwarza wszystkie obiekty wejściowe. Ten blok skryptu jest uruchamiany tylko raz dla całego potoku. Aby uzyskać więcej informacji na temat end bloku, zobacz about_Functions.

Właściwości parametru

Typ:	ScriptBlock
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ScriptBlockSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-InputObject

Określa obiekty wejściowe. ForEach-Object uruchamia instrukcję bloku skryptu lub operacji dla każdego obiektu wejściowego. Wprowadź zmienną zawierającą obiekty lub wpisz polecenie lub wyrażenie, które pobiera obiekty.

Jeśli używasz parametru InputObject z parametrem ForEach-Object, zamiast potokowania wyników polecenia do ForEach-Object, wartość InputObject jest traktowana jako pojedynczy obiekt. Jest to prawda, nawet jeśli wartość jest kolekcją, która jest wynikiem polecenia, takiego jak -InputObject (Get-Process). Ponieważ obiekt InputObject nie może zwracać pojedynczych właściwości z tablicy lub kolekcji obiektów, zalecamy, aby w przypadku ForEach-Object używania operacji na kolekcji obiektów dla tych obiektów, które mają określone wartości we zdefiniowanych właściwościach, należy użyć ForEach-Object w potoku, jak pokazano w przykładach w tym temacie.

Właściwości parametru

Typ:	PSObject
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	True
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-MemberName

Określa nazwę właściwości elementu członkowskiego, która ma być wywoływana, lub metoda składowa. Składowe muszą być członkami wystąpienia, a nie statycznych elementów członkowskich.

Dozwolone są symbole wieloznaczne, ale działają tylko wtedy, gdy wynikowy ciąg jest rozpoznawany jako unikatowa wartość. Jeśli na przykład uruchomisz Get-Process | foreach -MemberName *Name, wzorzec wieloznaczny pasuje do więcej niż jednego elementu członkowskiego, co powoduje niepowodzenie polecenia.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	True
DontShow:	False

Zestawy parametrów

PropertyAndMethodSet

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Parallel

Określa blok skryptu, który ma być używany do przetwarzania równoległego obiektów wejściowych. Wprowadź blok skryptu opisujący operację.

Ten parametr został wprowadzony w programie PowerShell 7.0.

Właściwości parametru

Typ:	ScriptBlock
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ParallelParameterSet

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Process

Określa operację wykonywaną na każdym obiekcie wejściowym. Ten blok skryptu jest uruchamiany dla każdego obiektu w potoku. Aby uzyskać więcej informacji na temat process bloku, zobacz about_Functions.

Po podaniu wielu bloków skryptu do parametru Proces pierwszy blok skryptu jest zawsze mapowany na begin blok. Jeśli istnieją tylko dwa bloki skryptu, drugi blok jest mapowany na blok process. Jeśli istnieją co najmniej trzy bloki skryptu, pierwszy blok skryptu jest zawsze mapowany na blok begin, ostatni blok jest mapowany na blok end, a środkowe bloki są mapowane na blok process.

Właściwości parametru

Typ:	ScriptBlock[]
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ScriptBlockSet

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-RemainingScripts

Określa wszystkie bloki skryptu, które nie są pobierane przez parametr Process .

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	ScriptBlock[]
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ScriptBlockSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-ThrottleLimit

Określa liczbę bloków skryptu uruchamianych równolegle. Obiekty wejściowe są blokowane, dopóki liczba uruchomionych bloków skryptu nie spadnie poniżej wartości ThrottleLimit. Wartość domyślna to 5.

Parametr ThrottleLimit ogranicza liczbę skryptów równoległych uruchomionych podczas każdego wystąpienia klasy ForEach-Object -Parallel. Nie ogranicza liczby zadań, które można utworzyć podczas korzystania z parametru AsJob . Ponieważ same zadania są uruchamiane współbieżnie, można utworzyć wiele zadań równoległych, z których każdy działa do limitu limitu liczby współbieżnych bloków skryptów.

Ten parametr został wprowadzony w programie PowerShell 7.0.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	5
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ParallelParameterSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-TimeoutSeconds

Określa liczbę sekund oczekiwania na równoległe przetworzenie wszystkich danych wejściowych. Po upływie określonego limitu czasu wszystkie uruchomione skrypty zostaną zatrzymane. Pozostałe obiekty wejściowe do przetworzenia są ignorowane. Wartość domyślna wyłącza 0 limit czasu i ForEach-Object -Parallel może działać w nieskończoność. Wpisywanie Ctrl+C w wierszu polecenia zatrzymuje uruchomione ForEach-Object -Parallel polecenie. Nie można użyć tego parametru wraz z parametrem AsJob .

Ten parametr został wprowadzony w programie PowerShell 7.0.

Właściwości parametru

Typ:	Int32
Domyślna wartość:	0
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ParallelParameterSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-UseNewRunspace

Powoduje wywołanie równoległe w celu utworzenia nowej przestrzeni uruchomieniowej dla każdej iteracji pętli zamiast ponownego użycia przestrzeni runspace z puli obszarów runspace.

Ten parametr został wprowadzony w programie PowerShell 7.1

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

ParallelParameterSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-WhatIf

Pokazuje, co się stanie, jeśli polecenie cmdlet zostanie uruchomione. Cmdlet nie został uruchomiony.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	False
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	Wi

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Dane wejściowe

PSObject

Do tego polecenia cmdlet można przekierować dowolny obiekt.

Dane wyjściowe

PSObject

To polecenie cmdlet zwraca obiekty określone przez dane wejściowe.

Uwagi

Program PowerShell zawiera następujące aliasy dla ForEach-Object:

Wszystkie platformy:
- %
- foreach

Polecenie ForEach-Object cmdlet działa podobnie do instrukcji foreach , z tą różnicą, że nie można przekazać danych wejściowych foreach do instrukcji . Aby uzyskać więcej informacji na temat instrukcji foreach , zobacz about_Foreach.

Począwszy od programu PowerShell 4.0, metody Where i ForEach zostały dodane do użycia z kolekcjami. Więcej informacji na temat tych nowych metod można znaleźć tutaj about_Arrays

Używając ForEach-Object -Parallel:

ForEach-Object -Parallel uruchamia każdy blok skryptu w nowej przestrzeni uruchomieniowej. Nowe przestrzenie runspace powodują znacznie większe obciążenie niż uruchamianie ForEach-Object przy użyciu przetwarzania sekwencyjnego. Ważne jest, aby używać funkcji Parallel , w której obciążenie związane z równoległym działaniem jest niewielkie w porównaniu z pracą wykonywaną przez blok skryptów. Przykład:
- Skrypty intensywnie korzystające z obliczeń na maszynach wielordzeniowych
- Skrypty, które spędzają czas na oczekiwaniu na wyniki lub wykonywanie operacji na plikach
Użycie parametru Parallel może spowodować, że skrypty działają znacznie wolniej niż normalnie. Zwłaszcza jeśli skrypty równoległe są proste. Poeksperymentuj z usługą Parallel , aby dowiedzieć się, gdzie może być korzystne.
W przypadku równoległego uruchamiania obiektów ozdobionych właściwościami ScriptProperties lub ScriptMethods nie można zagwarantować poprawnego działania, jeśli są one uruchamiane w innym obszarze uruchamiania niż skrypty zostały pierwotnie dołączone do nich.

Wywołanie scriptblock zawsze próbuje uruchomić w swoim głównym obszarze runspace, niezależnie od tego, gdzie jest on rzeczywiście wywoływany. ForEach-Object -Parallel Jednak tworzy tymczasowe przestrzenie uruchomieniowe, które zostaną usunięte po użyciu, więc nie ma już przestrzeni uruchomieniowej, w której skrypty będą już wykonywane.

To zachowanie może działać tak długo, jak nadal istnieje przestrzeń uruchomieniowa domu . Jednak nie można uzyskać żądanego wyniku, jeśli skrypt jest zależny od zmiennych zewnętrznych, które są obecne tylko w przestrzeni uruchomieniowej obiektu wywołującego, a nie w przestrzeni uruchamiania macierzystego .
Błędy niepowodujące zakończenia są zapisywane w strumieniu błędów polecenia cmdlet, ponieważ występują równolegle uruchomione bloki skryptów. Ponieważ równoległa kolejność wykonywania skryptblock jest niedeterministyczna, kolejność, w której błędy pojawiają się w strumieniu błędów, jest losowa. Podobnie komunikaty zapisywane w innych strumieniach danych, takie jak ostrzeżenie, pełne lub informacje, są zapisywane w tych strumieniach danych w nieokreślonej kolejności.

Kończenie błędów, takich jak wyjątki, powoduje przerwanie pojedynczego wystąpienia równoległego bloków skryptów, w których występują. Błąd zakończenia w jednym skryblokach może nie spowodować zakończenia ForEach-Object polecenia cmdlet. Inne bloki skryptów, uruchomione równolegle, nadal działają, chyba że napotkają również błąd zakończenia. Błąd zakończenia jest zapisywany w strumieniu danych błędu jako BłądRekord z w pełniqualifiedErrorId wartości PSTaskException. Błędy zakończenia można konwertować na błędy niezwiązane z kończeniem przy użyciu programu PowerShell try/catch lub trap bloków.
Typowe zmienne parametrów PipelineVariablenie są obsługiwane w scenariuszach równoległych, nawet w przypadku Using: modyfikatora zakresu.

Ważne

Zestaw ForEach-Object -Parallel parametrów uruchamia bloki skryptów równolegle w osobnych wątkach procesu. Modyfikator Using: umożliwia przekazywanie odwołań zmiennych z wątku wywołania polecenia cmdlet do każdego uruchomionego wątku bloku skryptu. Ponieważ bloki skryptu są uruchamiane w różnych wątkach, zmienne obiektu przekazywane przez odwołanie muszą być bezpiecznie używane. Ogólnie rzecz biorąc, bezpieczne jest odczytywanie z przywołynych obiektów, które nie ulegają zmianie. Jeśli musisz zmodyfikować stan obiektu, musisz użyć bezpiecznych obiektów wątku, takich jak .NET System.Collection.Concurrent types (Zobacz przykład 14).

Sprzężenie zwrotne

Czy ta strona była pomocna?

Udostępnij za pomocą

ForEach-Object

Składnia

ScriptBlockSet (Domyślna)

PropertyAndMethodSet

ParallelParameterSet

Opis

Przykłady

Przykład 1. Dzielenie liczb całkowitych w tablicy

Przykład 2. Pobieranie długości wszystkich plików w katalogu

Przykład 3. Działanie na najnowszych zdarzeniach systemowych

Przykład 4. Zmiana wartości klucza rejestru

Przykład 5. Używanie zmiennej automatycznej $null

Przykład 6. Pobieranie wartości właściwości

Przykład 7. Dzielenie nazw modułów na nazwy składników

Przykład 8: Używanie ForEach-Object z dwoma blokami skryptów

Przykład 9: Używanie ForEach-Object z więcej niż dwoma blokami skryptu

Przykład 10: Uruchamianie wielu bloków skryptów dla każdego elementu potoku

Przykład 11. Uruchamianie powolnego skryptu w równoległych partiach

Przykład 12: Równoległe pobieranie wpisów dziennika

Przykład 13: Uruchamianie równoległe jako zadanie

Przykład 14: Używanie odwołań do zmiennych bezpiecznych wątków

Przykład 15: Pisanie błędów z wykonywaniem równoległym

Przykład 16: Kończenie błędów w równoległym wykonywaniu

Przykład 17: Przekazywanie zmiennych w zagnieżdżonych blokach skryptów równoległych

Przykład 18: Tworzenie wielu zadań, które uruchamiają skrypty równolegle

Parametry

-ArgumentList

Właściwości parametru

Zestawy parametrów

-AsJob

Właściwości parametru

Zestawy parametrów

-Begin

Właściwości parametru

Zestawy parametrów

-Confirm

Właściwości parametru

Zestawy parametrów

-End

Właściwości parametru

Zestawy parametrów

-InputObject

Właściwości parametru

Zestawy parametrów

-MemberName

Właściwości parametru

Zestawy parametrów

-Parallel

Właściwości parametru

Zestawy parametrów

-Process

Właściwości parametru

Zestawy parametrów

-RemainingScripts

Właściwości parametru

Zestawy parametrów

-ThrottleLimit

Właściwości parametru

Zestawy parametrów

-TimeoutSeconds

Właściwości parametru

Zestawy parametrów

-UseNewRunspace

Właściwości parametru

Zestawy parametrów

-WhatIf

Właściwości parametru

Zestawy parametrów

CommonParameters

Dane wejściowe

PSObject

Dane wyjściowe

PSObject

Uwagi

Linki powiązane

Sprzężenie zwrotne