ForEach-Object

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

Description

Cmdleten ForEach-Object utför en åtgärd på varje objekt i en samling indataobjekt. Indataobjekten kan skickas till cmdleten eller anges med hjälp av parametern InputObject .

Från och med Windows PowerShell 3.0 finns det två olika sätt att konstruera ett ForEach-Object kommando.

• Skriptblock. Du kan använda ett skriptblock för att ange åtgärden. Använd variabeln i skriptblocket $_ för att representera det aktuella objektet. Skriptblocket är värdet för parametern Process . Skriptblocket kan innehålla valfritt PowerShell-skript.

  Följande kommando hämtar till exempel värdet för egenskapen ProcessName för varje process på datorn.

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

  ForEach-Object stöder blocken begin, processoch end enligt beskrivningen i about_functions.

  Kommentar

  Skriptblocken körs i anroparens omfång. Därför har blocken åtkomst till variabler i det omfånget och kan skapa nya variabler som finns kvar i omfånget när cmdleten har slutförts.

• Åtgärdsuttryck. Du kan också skriva en åtgärdsinstruktur som är mycket mer likt naturligt språk. Du kan använda åtgärdssatsen för att ange ett egenskapsvärde eller anropa en metod. Åtgärdsinstruktioner introducerades i Windows PowerShell 3.0.

  Följande kommando hämtar till exempel även värdet för egenskapen ProcessName för varje process på datorn.

  Get-Process | ForEach-Object ProcessName

• Skriptblock som körs parallellt. Från och med PowerShell 7.0 är en tredje parameteruppsättning tillgänglig som kör varje skriptblock parallellt. Parametern ThrottleLimit begränsar antalet parallella skript som körs åt gången. Precis som tidigare använder du variabeln $_ för att representera det aktuella indataobjektet i skriptblocket. Använd nyckelordet $using: för att skicka variabelreferenser till skriptet som körs.

  I PowerShell 7 skapas en ny runspace för varje loop-iteration för att säkerställa maximal isolering. Detta kan vara en stor prestanda- och resursträff om det arbete du utför är litet jämfört med att skapa nya runspaces eller om det finns många iterationer som utför betydande arbete. Från och med PowerShell 7.1 återanvänds runspaces från en runspace-pool som standard. Parametern ThrottleLimit anger storleken på runspace-poolen. Standardstorleken för runspace-poolen är 5. Du kan fortfarande skapa en ny runspace för varje iteration med hjälp av växeln UseNewRunspace .

  Som standard använder parallella scriptblocks den aktuella arbetskatalogen för anroparen som startade de parallella uppgifterna.

  Mer information finns i avsnittet ANTECKNINGAR i den här artikeln.

Exempel

Exempel 1: Dela upp heltal i en matris

Det här exemplet tar en matris med tre heltal och delar var och en av dem med 1024.

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

29.296875
55.466796875
12.140625

Exempel 2: Hämta längden på alla filer i en katalog

Det här exemplet bearbetar filerna och katalogerna i PowerShell-installationskatalogen $PSHOME.

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

Om objektet inte är en katalog hämtar skriptblocket namnet på filen, delar upp värdet för egenskapen Length med 1024 och lägger till ett blanksteg (" ") för att skilja det från nästa post. Cmdleten använder egenskapen PSISContainer för att avgöra om ett objekt är en katalog.

Exempel 3: Arbeta med de senaste systemhändelserna

I det här exemplet skrivs de 1 000 senaste händelserna från systemhändelseloggen till en textfil. Den aktuella tiden visas före och efter bearbetning av händelserna.

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 hämtar de 1 000 senaste händelserna från systemhändelseloggen och skickar dem till cmdleten ForEach-Object . Parametern Begin visar aktuellt datum och tid. Därefter använder parametern Process cmdleten Out-File för att skapa en textfil med namnet events.txt och lagrar meddelandeegenskapen för var och en av händelserna i filen. Sist används parametern End för att visa datum och tid när all bearbetning har slutförts.

Exempel 4: Ändra värdet för en registernyckel

I det här exemplet ändras värdet för RemotePath-registerposten i alla undernycklar under HKCU:\Network nyckeln till versaler.

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

Du kan använda det här formatet för att ändra formuläret eller innehållet i ett registerpostvärde.

Varje undernyckel i nätverksnyckeln representerar en mappad nätverksenhet som återansluter vid inloggning. RemotePath-posten innehåller UNC-sökvägen för den anslutna enheten. Om du till exempel mappar E: enheten till \\Server\Shareskapas en E-undernyckel i HKCU:\Network med registervärdet RemotePath inställt på \\Server\Share.

Kommandot använder cmdleten Get-ItemProperty för att hämta alla undernycklar för nätverksnyckeln och cmdleten Set-ItemProperty för att ändra värdet för RemotePath-registerposten i varje nyckel. Set-ItemProperty I kommandot är sökvägen värdet för PSPath-egenskapen för registernyckeln. Det här är en egenskap för Microsoft .NET Framework-objektet som representerar registernyckeln, inte en registerpost. Kommandot använder metoden ToUpper() för RemotePath-värdet , som är en sträng REG_SZ.

Eftersom Set-ItemProperty ändrar egenskapen för varje nyckel krävs cmdleten ForEach-Object för att få åtkomst till egenskapen.

Exempel 5: Använd den $null automatiska variabeln

Det här exemplet visar effekten av att skicka den $null automatiska variabeln till cmdleten ForEach-Object .

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

Hello
Hello
Hello
Hello

Eftersom PowerShell behandlar $null som en explicit platshållare genererar cmdleten ForEach-Object ett värde för $null som det gör för andra objekt som skickas till den.

Exempel 6: Hämta egenskapsvärden

Det här exemplet hämtar värdet för egenskapen Path för alla installerade PowerShell-moduler med parametern MemberName i cmdleten ForEach-Object .

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

Det andra kommandot motsvarar det första. Den använder aliaset Foreach för cmdleten ForEach-Object och utelämnar namnet på parametern MemberName , som är valfri.

Cmdleten ForEach-Object är användbar för att hämta egenskapsvärden, eftersom den hämtar värdet utan att ändra typen, till skillnad från cmdletarna Format eller cmdleten Select-Object , som ändrar egenskapsvärdetypen.

Exempel 7: Dela upp modulnamn i komponentnamn

Det här exemplet visar tre sätt att dela upp två punktavgränsade modulnamn i sina komponentnamn. Kommandona anropar metoden Dela upp i strängar. De tre kommandona använder olika syntax, men de är likvärdiga och utbytbara. Utdata är desamma för alla tre fallen.

"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

Det första kommandot använder den traditionella syntaxen, som innehåller ett skriptblock och den aktuella objektoperatorn $_. Den använder punktsyntaxen för att ange metoden och parenteserna för att omsluta avgränsningsargumentet.

Det andra kommandot använder parametern MemberName för att ange metoden Split och parametern ArgumentList för att identifiera punkten (.) som avgränsare för delad.

Det tredje kommandot använder Foreach-aliaset för cmdleten ForEach-Object och utelämnar namnen på parametrarna MemberName och ArgumentList , som är valfria.

Exempel 8: Använda ForEach-Object med två skriptblock

I det här exemplet skickar vi två skriptblock positionligt. Alla skriptblock binder till parametern Process . De behandlas dock som om de hade skickats till parametrarna Begin och Process .

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

begin
process
process

Exempel 9: Använda ForEach-Object med fler än två skriptblock

I det här exemplet skickar vi fyra skriptblock positionligt. Alla skriptblock binder till parametern Process . De behandlas dock som om de hade skickats till parametrarna Begin, Process och End .

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

begin
process A
process B
process A
process B
end

Exempel 10: Kör flera skriptblock för varje pipelineobjekt

Som du ser i föregående exempel mappas flera skriptblock som skickas med hjälp av processparametern till parametrarna Begin och End . För att undvika den här mappningen måste du ange explicita värden för parametrarna Begin och End .

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

one
two
three
one
two
three

Exempel 11: Kör långsamt skript i parallella batchar

Det här exemplet kör ett skriptblock som utvärderar en sträng och viloläge under en 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

Parametervärdet ThrottleLimit är inställt på 4 så att indata bearbetas i batchar med fyra. Nyckelordet $using: används för att skicka variabeln $Message till varje parallellt skriptblock.

Exempel 12: Hämta loggposter parallellt

Det här exemplet hämtar 50 000 loggposter från 5 systemloggar på en lokal Windows-dator.

$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

Parametern Parallel anger skriptblocket som körs parallellt för varje indataloggnamn. Parametern ThrottleLimit säkerställer att alla fem skriptblock körs samtidigt.

Exempel 13: Kör parallellt som ett jobb

Det här exemplet skapar ett jobb som kör ett skriptblock parallellt, två i taget.

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    …

Parametern ThrottleLimit begränsar antalet parallella skriptblock som körs åt gången. Parametern AsJob gör att cmdleten ForEach-Object returnerar ett jobbobjekt i stället för att strömma utdata till konsolen. Variabeln $job tar emot jobbobjektet som samlar in utdata och övervakar körningstillståndet. Egenskapen $job.ChildJobs innehåller de underordnade jobb som kör de parallella skriptblocken.

Exempel 14: Använda trådsäkra variabelreferenser

Det här exemplet anropar skriptblock parallellt för att samla in unikt namngivna processobjekt.

$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

En enda instans av ett ConcurrentDictionary-objekt skickas till varje skriptblock för att samla in objekten. Eftersom ConcurrentDictionary är trådsäkert är det säkert att ändras av varje parallellt skript. Ett icke-trådsäkert objekt, till exempel System.Collections.Generic.Dictionary, skulle inte vara säkert att använda här.

Exempel 15: Skriva fel med parallell körning

Det här exemplet skriver till felströmmen parallellt, där ordningen på skriftliga fel är slumpmässig.

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

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

Exempel 16: Avsluta fel vid parallell körning

Det här exemplet visar ett avslutande fel i en parallell skriptblockering som körs parallellt.

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 skrivs aldrig eftersom den parallella scriptblock för iterationen avslutades.

Exempel 17: Skicka variabler i kapslat parallellt skript ScriptBlockSet

Du kan skapa en variabel utanför en Foreach-Object -Parallel begränsad skriptblockering och använda den i skriptblocket med nyckelordet $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.

Det kapslade skriptblocket kan inte komma åt variabeln $test2 och ett fel utlöses.

Exempel 18: Skapa flera jobb som kör skript parallellt

Parametern ThrottleLimit begränsar antalet parallella skript som körs under varje instans av ForEach-Object -Parallel. Det begränsar inte antalet jobb som kan skapas när du använder parametern AsJob . Eftersom jobben körs samtidigt är det möjligt att skapa flera parallella jobb, var och en körs upp till begränsningsgränsen för antalet samtidiga skriptblock.

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

$jobs | Receive-Job -Wait

Det här exemplet skapar 10 jobb som körs. Varje jobb kör inte fler än 5 skript samtidigt. Det totala antalet instanser som körs samtidigt är begränsat till 50 (10 jobb gånger ThrottleLimit på 5).

Parametrar

-ArgumentList

-AsJob

-Begin

-Confirm

-End

-InputObject

-MemberName

-Parallel

-Process

-RemainingScripts

-ThrottleLimit

-TimeoutSeconds

-UseNewRunspace

-WhatIf

Indata

PSObject

Du kan skicka valfritt objekt till den här cmdleten.

Utdata

PSObject

Den här cmdleten returnerar objekt som bestäms av indata.

Kommentarer

PowerShell innehåller följande alias för ForEach-Object:

• Alla plattformar:
  • %
  • foreach

Cmdleten ForEach-Object fungerar ungefär som Foreach-instruktionen, förutom att du inte kan skicka indata till en Foreach-instruktion. Mer information om Foreach-instruktionen finns i about_Foreach.

Från och med PowerShell 4.0 Where har ForEach metoder lagts till för användning med samlingar. Du kan läsa mer om dessa nya metoder här about_arrays

Använda ForEach-Object -Parallel:

• ForEach-Object -Parallel kör varje skriptblock i ett nytt runspace. De nya runspaces skapar betydligt mer omkostnader än att köra ForEach-Object med sekventiell bearbetning. Det är viktigt att använda Parallel där kostnaden för att köra parallellt är liten jämfört med det arbete som skriptblocket utför. Till exempel:

  • Beräkningsintensiva skript på datorer med flera kärnor
  • Skript som ägnar tid åt att vänta på resultat eller utföra filåtgärder

  Om du använder parametern Parallell kan skript köras mycket långsammare än normalt. Särskilt om parallella skript är triviala. Experimentera med Parallel för att upptäcka var det kan vara fördelaktigt.

• När de körs parallellt kan objekt som är dekorerade med ScriptProperties eller ScriptMethods inte garanteras fungera korrekt om de körs i ett annat körningsutrymme än de skript som ursprungligen var kopplade till dem.

  Scriptblock-anrop försöker alltid köras i dess hemkörning , oavsett var det faktiskt anropas. Skapar dock ForEach-Object -Parallel tillfälliga runspaces som tas bort efter användning, så det finns ingen körningsplats för skripten att köra i längre.

  Det här beteendet kan fungera så länge hemkörningsytan fortfarande finns. Du kanske dock inte får önskat resultat om skriptet är beroende av externa variabler som bara finns i anroparens runspace och inte på startkörningen .

• Icke-avslutande fel skrivs till cmdlet-felströmmen när de inträffar parallellt med skriptblockering. Eftersom körningsordningen för parallell scriptblock är icke-deterministisk är ordningen i vilken felen visas i felströmmen slumpmässig. På samma sätt skrivs meddelanden som skrivs till andra dataströmmar, till exempel varning, utförlig eller information, till dessa dataströmmar i en obestämd ordning.

  Avslutande fel, till exempel undantag, avslutar den enskilda parallella instansen av skriptblocken där de inträffar. Ett avslutande fel i en skriptblockering kan inte orsaka att cmdleten Foreach-Object avslutas. De andra skriptblocken, som körs parallellt, fortsätter att köras om de inte också stöter på ett avslutande fel. Det avslutande felet skrivs till feldataströmmen som en ErrorRecord med ett FullyQualifiedErrorId för PSTaskException. Avslutande fel kan konverteras till icke-avslutande fel med hjälp av PowerShell try/catch eller trap block.

• PipelineVariable vanliga parametervariabler stöds inte i parallella scenarier även med nyckelordet $using: .

  Viktigt!

  Parameteruppsättningen ForEach-Object -Parallel kör skriptblock parallellt på separata processtrådar. Med nyckelordet $using: kan du skicka variabelreferenser från cmdlet-anropstråden till varje skriptblocktråd som körs. Eftersom skriptblocken körs i olika trådar måste objektvariablerna som skickas med referens användas på ett säkert sätt. Vanligtvis är det säkert att läsa från refererade objekt som inte ändras. Om du behöver ändra objekttillståndet måste du använda trådsäkra objekt, till exempel .NET System.Collection.Concurrent-typer (se exempel 14).

Relaterade länkar

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