ForEach-Object

Syntaxe

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

Description

Rutina ForEach-Object provádí operaci pro každou položku v kolekci vstupních objektů. Vstupní objekty lze předvést do rutiny nebo zadat pomocí parametru InputObject .

Počínaje windows PowerShellem 3.0 existují dva různé způsoby vytvoření ForEach-Object příkazu.

• Blok skriptu. K určení operace můžete použít blok skriptu. V rámci bloku skriptu použijte $_ proměnnou k reprezentaci aktuálního objektu. Blok skriptu je hodnota parametru Process . Blok skriptu může obsahovat libovolný skript PowerShellu.

  Například následující příkaz získá hodnotu ProcessName vlastnost každého procesu v počítači.

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

  ForEach-Objectbeginpodporuje , processa end bloky, jak je popsáno v about_functions.

  Poznámka:

  Bloky skriptu se spouštějí v oboru volajícího. Bloky proto mají přístup k proměnným v daném oboru a můžou vytvářet nové proměnné, které se v daném oboru zachovají po dokončení rutiny.

• Příkaz Operation. Můžete také napsat příkaz operace, což je mnohem více jako přirozený jazyk. Příkaz operace můžete použít k určení hodnoty vlastnosti nebo volání metody. Příkazy operací byly zavedeny ve Windows PowerShellu 3.0.

  Například následující příkaz také získá hodnotu ProcessName vlastnost každého procesu v počítači.

  Get-Process | ForEach-Object ProcessName

• Paralelní spuštění bloku skriptu. Počínaje PowerShellem 7.0 je k dispozici třetí sada parametrů, která spouští každý blok skriptu paralelně. Parametr ThrottleLimit omezuje počet paralelních skriptů spuštěných najednou. Stejně jako předtím použijte $_ proměnnou k reprezentaci aktuálního vstupního objektu v bloku skriptu. Pomocí klíčového $using: slova předejte do spuštěného skriptu odkazy na proměnné.

  V PowerShellu 7 se vytvoří nový runspace pro každou iteraci smyčky, aby se zajistila maximální izolace. To může být velký výkon a dosažení prostředků, pokud je práce, kterou děláte, malá ve srovnání s vytvářením nových prostředí runspace nebo pokud existuje velké množství iterací provádějících významnou práci. Od PowerShellu 7.1 se ve výchozím nastavení znovu používají prostory z fondu runspace. Parametr ThrottleLimit nastaví velikost fondu runspace. Výchozí velikost fondu runspace je 5. Stále můžete vytvořit nový runspace pro každou iteraci pomocí přepínače UseNewRunspace .

  Ve výchozím nastavení používají paralelní bloky skriptů aktuální pracovní adresář volajícího, který spustil paralelní úlohy.

  Další informace najdete v části POZNÁMKY tohoto článku.

Příklady

Příklad 1: Dělení celých čísel v matici

V tomto příkladu se používá pole se třemi celými čísly a každý z nich vydělí číslem 1024.

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

29.296875
55.466796875
12.140625

Příklad 2: Získání délky všech souborů v adresáři

Tento příklad zpracovává soubory a adresáře v instalačním adresáři $PSHOMEPowerShellu .

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

Pokud objekt není adresář, blok skriptu získá název souboru, vydělí hodnotu jeho vlastnosti Length hodnotou 1024 a přidá mezeru (" ") k jeho oddělení od další položky. Rutina používá vlastnost PSISContainer k určení, zda je objekt adresáře.

Příklad 3: Operace s nejnovějšími událostmi systému

Tento příklad zapíše 1000 nejnovějších událostí z protokolu událostí systému do textového souboru. Aktuální čas se zobrazí před a po zpracování událostí.

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 získá 1000 nejnovějších událostí z protokolu událostí systému a předá je do rutiny ForEach-Object . Parametr Begin zobrazuje aktuální datum a čas. Parametr Process dále pomocí rutiny Out-File vytvoří textový soubor s názvem events.txt a uloží vlastnost zprávy jednotlivých událostí v daném souboru. Nakonec se parametr End použije k zobrazení data a času po dokončení veškerého zpracování.

Příklad 4: Změna hodnoty klíče registru

Tento příklad změní hodnotu položky registru RemotePath ve všech podklíčích pod HKCU:\Network klíčem na velká písmena textu.

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

Tento formát můžete použít ke změně formuláře nebo obsahu hodnoty položky registru.

Každý podklíč v síťovém klíči představuje namapovanou síťovou jednotku, která se znovu připojí při přihlášení. Položka RemotePath obsahuje cestu UNC připojené jednotky. Pokud například namapujete jednotku E: na \\Server\Sharepodklíč E, vytvoří se podklíč HKCU:\Network E s hodnotou registru RemotePath nastavenou na \\Server\Sharehodnotu .

Příkaz pomocí rutiny Get-ItemProperty získá všechny podklíče síťového klíče a rutiny Set-ItemProperty ke změně hodnoty položky registru RemotePath v každém klíči. Set-ItemProperty V příkazu je cesta hodnotou vlastnosti PSPath klíče registru. Toto je vlastnost objektu rozhraní Microsoft .NET Framework, který představuje klíč registru, nikoli položku registru. Příkaz používá metodu ToUpper() hodnoty RemotePath, což je řetězec REG_SZ.

Vzhledem k tomu Set-ItemProperty , že se mění vlastnost každého klíče, ForEach-Object je rutina nutná pro přístup k této vlastnosti.

Příklad 5: Použití $null automatické proměnné

Tento příklad ukazuje účinek propojení $null automatické proměnné do rutiny ForEach-Object .

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

Hello
Hello
Hello
Hello

Vzhledem k tomu, že PowerShell považuje $null za explicitní zástupný symbol, rutina vygeneruje hodnotu tak$null, ForEach-Object jak to dělá pro ostatní objekty předané do něj.

Příklad 6: Získání hodnot vlastností

Tento příklad získá hodnotu Path vlastnost všech nainstalovaných modulů PowerShellu pomocí parametru MemberName rutiny ForEach-Object .

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

Druhý příkaz je ekvivalentní prvnímu příkazu. Používá Foreach alias ForEach-Object rutiny a vynechá název parametru MemberName , který je volitelný.

Rutina ForEach-Object je užitečná pro získání hodnot vlastností, protože získá hodnotu beze změny typu, na rozdíl od rutin Format nebo rutiny Select-Object , která změní typ hodnoty vlastnosti.

Příklad 7: Rozdělení názvů modulů na názvy komponent

Tento příklad ukazuje tři způsoby rozdělení dvou názvů modulů oddělených tečkami na názvy komponent. Příkazy volají metodu Split řetězců. Tyto tři příkazy používají jinou syntaxi, ale jsou ekvivalentní a zaměnitelné. Výstup je stejný pro všechny tři případy.

"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

První příkaz používá tradiční syntaxi, která zahrnuje blok skriptu a aktuální operátor $_objektu . Pomocí syntaxe tečky určuje metodu a závorky k uzavření argumentu oddělovače.

Druhý příkaz používá parametr MemberName k určení Split metoda a ArgumentList parametr identifikovat tečku (.) jako oddělovač rozdělení.

Třetí příkaz používá alias ForEach-Object Foreach rutiny a vynechá názvy parametrů MemberName a ArgumentList, které jsou volitelné.

Příklad 8: Použití objektu ForEach se dvěma bloky skriptu

V tomto příkladu předáme dva bloky skriptu pozičním způsobem. Všechny bloky skriptu se sváže s parametrem Process . Považují se však za to, že byly předány parametrům Begin a Process .

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

begin
process
process

Příklad 9: Použití objektu ForEach s více než dvěma bloky skriptu

V tomto příkladu předáváme pozičním způsobem čtyři bloky skriptu. Všechny bloky skriptu se sváže s parametrem Process . Považují se však za to, že byly předány parametrům Begin, Process a End .

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

begin
process A
process B
process A
process B
end

Příklad 10: Spuštění více bloků skriptů pro každou položku kanálu

Jak je znázorněno v předchozím příkladu, několik bloků skriptu předaných pomocí parametru Process se mapuje na parametry Begin a End . Chcete-li se tomuto mapování vyhnout, je nutné zadat explicitní hodnoty parametrů Begin a End .

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

one
two
three
one
two
three

Příklad 11: Spuštění pomalého skriptu v paralelních dávkách

V tomto příkladu se spustí blok skriptu, který vyhodnocuje řetězec a po dobu jedné sekundy spí.

$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

Hodnota parametru ThrottleLimit je nastavena na hodnotu 4, aby se vstup zpracovával v dávkách čtyř. Klíčové $using: slovo slouží k předání $Message proměnné do každého bloku paralelního skriptu.

Příklad 12: Paralelní načtení položek protokolu

Tento příklad načte 50 000 položek protokolu z 5 systémových protokolů na místním počítači s 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

50000

Parametr Parallel určuje blok skriptu, který se spouští paralelně pro každý název vstupního protokolu. Parametr ThrottleLimit zajišťuje, že se současně spustí všech pět bloků skriptu.

Příklad 13: Paralelní spuštění jako úloha

Tento příklad vytvoří úlohu, která paralelně spustí blok skriptu, dva po druhé.

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 omezuje počet paralelních bloků skriptů spuštěných najednou. Parametr AsJob způsobí, ForEach-Object že rutina vrátí objekt úlohy místo výstupu streamování do konzoly. Proměnná $job obdrží objekt úlohy, který shromažďuje výstupní data a monitoruje spuštěný stav. Vlastnost $job.ChildJobs obsahuje podřízené úlohy, které spouští bloky paralelních skriptů.

Příklad 14: Použití odkazůnach

Tento příklad vyvolá bloky skriptu paralelně ke shromažďování jedinečných pojmenovaných objektů Process.

$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

Do každého bloku skriptu se předá jedna instance objektu ConcurrentDictionary , aby se objekty shromáždily. Vzhledem k tomu, že ConcurrentDictionary je bezpečný pro přístup z více vláken, je bezpečné je upravovat každý paralelní skript. Objekt, který není bezpečný pro vlákno, jako je System.Collections.Generic.Dictionary, by zde nebyl bezpečný.

Příklad 15: Zápis chyb s paralelním spouštěním

Tento příklad zapisuje do datového proudu chyb paralelně, kde pořadí zapsaných chyb je náhodné.

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

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

Příklad 16: Ukončení chyb při paralelním spuštění

Tento příklad ukazuje ukončující chybu v jednom paralelním spuštění skriptublock.

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 není nikdy zapsán, protože paralelní skriptblock pro tuto iteraci byl ukončen.

Příklad 17: Předávání proměnných ve vnořeném paralelním skriptu ScriptBlockSet

Můžete vytvořit proměnnou mimo blok skriptu s vymezeným Foreach-Object -Parallel oborem a použít ji uvnitř skriptublock s klíčovým slovem $using .

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

Vnořený skriptblock nemá přístup k $test2 proměnné a vyvolá se chyba.

Příklad 18: Vytvoření více úloh, které spouští skripty paralelně

Parametr ThrottleLimit omezuje počet paralelních skriptů spuštěných během každé instance ForEach-Object -Parallel. Neomezuje počet úloh, které je možné vytvořit při použití parametru AsJob . Vzhledem k tomu, že samotné úlohy běží souběžně, je možné vytvořit několik paralelních úloh, přičemž každý z nich běží až do limitu počtu souběžných skriptů.

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

$jobs | Receive-Job -Wait

Tento příklad vytvoří 10 spuštěných úloh. Každá úloha nespustí více než 5 skriptů současně. Celkový počet spuštěných současně spuštěných instancí je omezen na 50 (10 úloh krát omezení 5).

Parametry

-ArgumentList

-AsJob

-Begin

-Confirm

-End

-InputObject

-MemberName

-Parallel

-Process

-RemainingScripts

-ThrottleLimit

-TimeoutSeconds

-UseNewRunspace

-WhatIf

Vstupy

PSObject

Do této rutiny můžete převést libovolný objekt.

Výstupy

PSObject

Tato rutina vrátí objekty, které jsou určeny vstupem.

Poznámky

PowerShell obsahuje následující aliasy pro ForEach-Object:

• Všechny platformy:
  • %
  • foreach

Rutina ForEach-Object funguje podobně jako příkaz Foreach s tím rozdílem , že vstup do příkazu Foreach nelze převést. Další informace o příkazu Foreach najdete v tématu about_Foreach.

Počínaje PowerShellem 4.0 Where a ForEach metody byly přidány pro použití s kolekcemi. Další informace o těchto nových metodách najdete about_arrays

Pomocí ForEach-Object -Parallel:

• ForEach-Object -Parallel spustí každý blok skriptu v novém prostředí Runspace. Nové runspaces vytvářejí výrazně větší režii než spouštění ForEach-Object sekvenčním zpracováním. Je důležité použít paralelně , kdy je režie paralelního spuštění malá v porovnání s prací, kterou blok skriptu provádí. Příklad:

  • Skripty náročné na výpočetní výkon na počítačích s více jádry
  • Skripty, které tráví čas čekáním na výsledky nebo prováděním operací se soubory

  Použití parametru Parallel může způsobit, že skripty běží mnohem pomaleji než obvykle. Zvláště pokud jsou paralelní skripty triviální. Experimentujte s paralelně a zjistěte, kde může být přínosné.

• Při paralelním spuštění objekty zdobené ScriptProperties nebo ScriptMethods nemohou být zaručeny správné fungování, pokud jsou spuštěny v jiném prostředí runspace, než byly k nim původně připojeny skripty.

  Vyvolání scriptblocku se vždy pokusí spustit ve svém domovském prostředí runspace bez ohledu na to, kde se skutečně vyvolá. ForEach-Object -Parallel Vytvoří však dočasné prostředí runspace, které se po použití odstraní, takže už skripty nebudou spuštěné.

  Toto chování může fungovat, pokud home runspace stále existuje. Požadovaný výsledek však nelze získat, pokud je skript závislý na externích proměnných, které jsou přítomné pouze v prostředí runspace volajícího, a ne na domovském prostředí runspace.

• Neukončující chyby se zapisují do datového proudu chyb rutiny, protože probíhají paralelně se spouštěním skriptů. Vzhledem k tomu, že pořadí provádění paralelního bloku skriptu není deterministické, pořadí, ve kterém se chyby zobrazují v chybovém streamu, je náhodné. Podobně se zprávy zapsané do jiných datových proudů, jako jsou upozornění, podrobné nebo informace, zapisují do těchto datových proudů v neurčité pořadí.

  Ukončování chyb, jako jsou výjimky, ukončete jednotlivé paralelní instance skriptů, ve kterých k nim dochází. Ukončení chyby v jednom bloku skriptu nemusí způsobit ukončení rutiny Foreach-Object . Ostatní skripty, spuštěné paralelně, se budou dál spouštět, pokud také nenarazí na ukončující chybu. Ukončující chyba je zapsána do datového proudu chyby jako ErrorRecord s PlněQualifiedErrorId of PSTaskException. Ukončující chyby lze pomocí PowerShellu trycatch/nebo trap bloků převést na neukončující chyby.

• Běžné proměnné parametrů PipelineVariable nejsou podporovány v paralelních scénářích ani s klíčovým slovem$using:.

  Důležité

  Sada ForEach-Object -Parallel parametrů spouští bloky skriptu paralelně na samostatných vláknech procesu. Klíčové $using: slovo umožňuje předávání odkazů na proměnné z vlákna vyvolání rutiny do každého spuštěného vlákna bloku skriptu. Vzhledem k tomu, že bloky skriptu běží v různých vláknech, musí být proměnné objektů předané odkazem bezpečně použity. Obecně je bezpečné číst z odkazovaných objektů, které se nemění. Pokud potřebujete změnit stav objektu, musíte použít bezpečné objekty vlákna, jako jsou typy .NET System.Collection.Concurrent (viz příklad 14).

Související odkazy

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