ForEach-Object

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

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

ForEach-Object
    -Parallel <ScriptBlock>
    [-InputObject <PSObject>]
    [-ThrottleLimit <Int32>]
    [-TimeoutSeconds <Int32>]
    [-AsJob]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

L’applet ForEach-Object de commande effectue une opération sur chaque élément d’une collection d’objets d’entrée. Les objets d’entrée peuvent être redirigés vers l’applet de commande ou spécifiés à l’aide du paramètre InputObject .

À compter de Windows PowerShell 3.0, il existe deux façons différentes de construire une commande ForEach-Object.

• de bloc de script . Vous pouvez utiliser un bloc de script pour spécifier l’opération. Dans le bloc de script, utilisez la $_ variable pour représenter l’objet actuel. Le bloc de script est la valeur du paramètre Process . Le bloc de script peut contenir n’importe quel script PowerShell.

  Par exemple, la commande suivante obtient la valeur de la propriété ProcessName de chaque processus sur l’ordinateur.

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

  ForEach-Object Prend en charge les beginblocs , processet end comme décrit dans about_functions.

  Remarque

  Les blocs de script s’exécutent dans l’étendue de l’appelant. Par conséquent, les blocs ont accès aux variables de cette étendue et peuvent créer de nouvelles variables qui persistent dans cette étendue une fois l’applet de commande terminée.

• instruction Operation. Vous pouvez également écrire une instruction d’opération, qui est beaucoup plus semblable au langage naturel. Vous pouvez utiliser l’instruction d’opération pour spécifier une valeur de propriété ou appeler une méthode. Les instructions d’opération ont été introduites dans Windows PowerShell 3.0.

  Par exemple, la commande suivante obtient également la valeur de la propriété ProcessName de chaque processus sur l’ordinateur.

  Get-Process | ForEach-Object ProcessName

• Bloc de script en cours d’exécution parallèle. À compter de PowerShell 7.0, un troisième jeu de paramètres est disponible qui exécute chaque bloc de script en parallèle. Le paramètre ThrottleLimit limite le nombre de scripts parallèles en cours d’exécution à la fois. Comme précédemment, utilisez la $_ variable pour représenter l’objet d’entrée actuel dans le bloc de script. Utilisez le mot-clé pour transmettre des $using: références de variables au script en cours d’exécution.

  Dans PowerShell 7, un nouvel espace d’exécution est créé pour chaque itération de boucle pour garantir l’isolation maximale. Il peut s’agir d’un impact important sur les performances et les ressources si le travail que vous effectuez est petit par rapport à la création de nouveaux espaces d’exécution ou s’il existe beaucoup d’itérations effectuant un travail significatif. À partir de PowerShell 7.1, les instances d’exécution d’un pool d’espaces de exécution sont réutilisées par défaut. La taille du pool d’espace d’exécution est spécifiée par le paramètre ThrottleLimit . La taille du pool runspace par défaut est 5. Vous pouvez toujours créer un espace d’exécution pour chaque itération à l’aide du commutateur UseNewRunspace .

  Par défaut, les blocs de script parallèles utilisent le répertoire de travail actuel de l’appelant qui a démarré les tâches parallèles.

  Pour plus d’informations, consultez la section NOTES de cet article.

Cet exemple prend un tableau de trois entiers et divise chacun d’eux par 1024.

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

29.296875
55.466796875
12.140625

Cet exemple traite les fichiers et les répertoires dans le répertoire $PSHOMEd’installation de PowerShell.

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

Si l’objet n’est pas un répertoire, le bloc de script obtient le nom du fichier, divise la valeur de sa propriété Length par 1024 et ajoute un espace ( » « ) pour le séparer de l’entrée suivante. L’applet de commande utilise la propriété PSISContainer pour déterminer si un objet est un répertoire.

Cet exemple écrit les 1 000 événements les plus récents du journal des événements système dans un fichier texte. L’heure actuelle s’affiche avant et après le traitement des événements.

$Events = Get-EventLog -LogName System -Newest 1000
$events | ForEach-Object -Begin {Get-Date} -Process {Out-File -FilePath Events.txt -Append -InputObject $_.Message} -End {Get-Date}

Get-EventLog récupère les 1000 événements les plus récents à partir du journal des événements système et les stocke dans la $Events variable. $Events est ensuite redirigé vers l’applet ForEach-Object de commande. Le paramètre Begin affiche la date et l’heure actuelles. Ensuite, le paramètre Process utilise l’applet de commande Out-File pour créer un fichier texte nommé events.txt et stocke la propriété de message de chacun des événements de ce fichier. Enfin, le paramètre End est utilisé pour afficher la date et l’heure après la fin du traitement.

Cet exemple remplace la valeur de l’entrée de registre RemotePath dans toutes les sous-clés sous la HKCU:\Network clé par du texte en majuscules.

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

Vous pouvez utiliser ce format pour modifier le formulaire ou le contenu d’une valeur d’entrée de Registre.

Chaque sous-clé de la clé réseau représente un lecteur réseau mappé qui se reconnecte lors de l’authentification. L’entrée RemotePath contient le chemin UNC du lecteur connecté. Par exemple, si vous mappez le lecteur E : à \\Server\Share, une sous-clé E est créée dans HKCU:\Network avec la valeur de registre RemotePath définie sur \\Server\Share.

La commande utilise l’applet de commande pour obtenir toutes les sous-clés de la clé de Réseau et l’applet de commande pour modifier la valeur de l’entrée de Registre RemotePath dans chaque clé. Dans la Set-ItemProperty commande, le chemin d’accès est la valeur de la propriété PSPath de la clé de Registre. Il s’agit d’une propriété de l’objet Microsoft .NET Framework qui représente la clé de Registre, et non une entrée de Registre. La commande utilise la méthode ToUpper() de la valeur RemotePath , qui est une chaîne (REG_SZ).

Étant donné que Set-ItemProperty la modification de la propriété de chaque clé est nécessaire, l’applet ForEach-Object de commande doit accéder à la propriété.

Cet exemple montre l’effet de la conversion de la $Null variable automatique à l’applet ForEach-Object de commande.

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

Hello
Hello
Hello
Hello

Étant donné que PowerShell traite null comme un espace réservé explicite, l’applet de commande ForEach-Object génère une valeur pour $Null, tout comme pour les autres objets que vous dirigez vers celui-ci.

Cet exemple récupère la valeur de la propriété Path de tous les modules PowerShell installés à l’aide du paramètre MemberName de l’applet ForEach-Object de commande.

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

La deuxième commande équivaut au premier. Il utilise l’alias Foreach de l’applet ForEach-Object de commande et omet le nom du paramètre MemberName , qui est facultatif.

L’applet ForEach-Object de commande est utile pour obtenir des valeurs de propriété, car elle obtient la valeur sans modifier le type, contrairement aux applets de commande Format ou à l’applet Select-Object de commande, qui modifient le type de valeur de propriété.

Cet exemple montre trois façons de fractionner deux noms de modules séparés par points en noms de composants. Les commandes appellent la méthode Split de chaînes. Les trois commandes utilisent une syntaxe différente, mais elles sont équivalentes et interchangeables. La sortie est la même pour les trois cas.

"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

La première commande utilise la syntaxe traditionnelle, qui inclut un bloc de script et l’opérateur $_d’objet actuel. Il utilise la syntaxe des points pour spécifier la méthode et les parenthèses pour placer l’argument délimiteur.

La deuxième commande utilise le paramètre MemberName pour spécifier la méthode Split et le paramètre ArgumentList pour identifier le point (.) comme délimiteur fractionné.

La troisième commande utilise l’alias Foreach de l’applet ForEach-Object de commande et omet les noms des paramètres MemberName et ArgumentList , qui sont facultatifs.

Dans cet exemple, nous passons deux blocs de script en position position. Tous les blocs de script sont liés au paramètre Process . Cependant, ils sont traités comme s’ils avaient été transmis aux paramètres Begin et Process .

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

begin
process
process

Dans cet exemple, nous passons deux blocs de script en position position. Tous les blocs de script sont liés au paramètre Process . Cependant, ils sont traités comme s’ils avaient été transmis aux paramètres Begin, Process et End .

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

begin
process A
process B
process A
process B
end

Comme indiqué dans l’exemple précédent, plusieurs blocs de script passés à l’aide du paramètre Process sont mappés aux paramètres Begin et End . Pour éviter ce mappage, vous devez fournir des valeurs explicites pour les paramètres Begin et End .

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

one
two
three
one
two
three

Cet exemple exécute un bloc de script simple qui évalue une chaîne et se met en veille pendant une seconde.

$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

La valeur du paramètre ThrottleLimit est définie sur 4 afin que l’entrée soit traitée par lots de quatre. Le $using: mot-clé est utilisé pour passer la $Message variable dans chaque bloc de script parallèle.

Cet exemple récupère 50 000 entrées de journal à partir de 5 journaux système sur un ordinateur Windows local.

$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

Le paramètre Parallel spécifie le bloc de script qui est exécuté en parallèle pour chaque nom de journal d’entrée. Le paramètre ThrottleLimit garantit que les cinq blocs de script s’exécutent en même temps.

Cet exemple exécute un bloc de script simple en parallèle, en créant deux travaux d’arrière-plan à la fois.

$job = 1..10 | ForEach-Object -Parallel {
    "Output: $_"
    Start-Sleep 1
} -ThrottleLimit 2 -AsJob

$job | Receive-Job -Wait

Output: 1
Output: 2
Output: 3
Output: 4
Output: 5
Output: 6
Output: 7
Output: 8
Output: 9
Output: 10

La $job variable reçoit l’objet Job qui collecte les données de sortie et surveille l’état en cours d’exécution. L’objet de travail est redirigé Receive-Job vers l’aide du paramètre de commutateur Wait . Et cela transmet la sortie à la console, comme s’il ForEach-Object -Parallel était exécuté sans AsJob.

Cet exemple appelle des blocs de script en parallèle pour collecter des objets Process nommés de manière unique.

$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

Une seule instance d’un objet ConcurrentDictionary est passée à chaque bloc de script pour collecter les objets. Étant donné que le ConcurrentDictionary est thread-safe, il peut être modifié en toute sécurité par chaque script parallèle. Un objet non thread-safe, tel que System.Collections.Generic.Dictionary, ne serait pas sûr d’être utilisé ici.

Cet exemple écrit dans le flux d’erreurs en parallèle, où l’ordre des erreurs écrites est aléatoire.

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

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

Cet exemple illustre une erreur de fin dans un scriptblock en cours d’exécution parallèle.

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 n’est jamais écrit, car le scriptblock parallèle pour cette itération a été arrêté.

Vous pouvez créer une variable en dehors d’un Foreach-Object -Parallel scriptblock limité et l’utiliser à l’intérieur du scriptblock avec le mot-clé $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' cannot be retrieved because it has not been set in the local session.

Le scriptblock imbriqué ne peut pas accéder à la $test2 variable et une erreur est générée.

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

Vous pouvez diriger n’importe quel objet vers cette applet de commande.

Cette applet de commande retourne des objets déterminés par l’entrée.

L’applet de commande ForEach-Object fonctionne comme l’instruction Foreach, sauf que vous ne pouvez pas diriger l’entrée vers une instruction Foreach. Pour plus d’informations sur l’instruction Foreach, consultez about_Foreach.

À compter de PowerShell 4.0, Where les ForEach méthodes ont été ajoutées pour une utilisation avec des collections. Vous pouvez en savoir plus sur ces nouvelles méthodes ici about_arrays

Utilisation de ForEach-Object -Parallel:

• L’ensemble ForEach-Object -Parallel de paramètres utilise l’API interne de PowerShell pour exécuter chaque bloc de script dans un nouvel espace d’exécution. Il s’agit d’une surcharge nettement supérieure à celle d’un traitement ForEach-Object séquentiel. Il est important d’utiliser Parallel lorsque la surcharge liée à l’exécution en parallèle est faible par rapport au travail effectué par le bloc de script. Par exemple:

  • Calcul de scripts intensifs sur des machines multicœurs
  • Scripts qui passent du temps à attendre les résultats ou à effectuer des opérations de fichier

  L’utilisation du paramètre Parallel peut entraîner l’exécution de scripts beaucoup plus lents que la normale. Surtout si les scripts parallèles sont trivials. Expérimentez avec Parallel pour découvrir où il peut être bénéfique.

• Lorsqu’ils s’exécutent en parallèle, le bon fonctionnement des objets décorés avec ScriptProperties ou ScriptMethods est impossible s’ils sont exécutés dans un espace d’exécution différent de celui auquel les scripts étaient attachés à l’origine.

  L’appel scriptblock tente toujours de s’exécuter dans son runspace d’accueil , quel que soit l’emplacement où il est réellement appelé. Toutefois, ForEach-Object -Parallel crée des runspaces temporaires qui sont supprimés après l’utilisation. Il n’existe donc plus d’espace d’exécution pour que les scripts s’exécutent plus.

  Ce comportement peut fonctionner tant que l’espace d’exécution d’accueil existe toujours. Toutefois, vous n’obtenez peut-être pas le résultat souhaité si le script dépend de variables externes uniquement présentes dans l’espace d’exécution de l’appelant et non dans l’espace d’exécution de l’appelant.

• Les erreurs sans fin sont écrites dans le flux d’erreurs d’applet de commande lorsqu’elles se produisent dans des blocs de script en cours d’exécution parallèles. Étant donné que l’ordre d’exécution de scriptblock parallèle n’est pas déterministe, l’ordre dans lequel les erreurs apparaissent dans le flux d’erreurs est aléatoire. De même, les messages écrits dans d’autres flux de données, tels que l’avertissement, le verbe ou les informations, sont écrits dans ces flux de données dans un ordre indéterminé.

  La fin des erreurs, telles que les exceptions, met fin à l’instance parallèle individuelle des blocs de script dans lesquels elles se produisent. Une erreur de fin dans un scriptblocks peut ne pas entraîner l’arrêt de l’applet Foreach-Object de commande. Les autres blocs de script, s’exécutant en parallèle, continuent à s’exécuter, sauf s’ils rencontrent également une erreur de fin. L’erreur de fin est écrite dans le flux de données d’erreur en tant que ErrorRecord avec un FullyQualifiedErrorId de PSTaskException. Les erreurs de fin peuvent être converties en erreurs non finales à l’aide de blocs try/catch ou trap PowerShell.

• Les variables de paramètre commun PipelineVariablene sont pas prises en charge dans les scénarios parallèles, même avec le mot-clé$using:.

  Important

  Le ForEach-Object -Parallel jeu de paramètres exécute des blocs de script en parallèle sur des threads de processus distincts. Le $using: mot-clé permet de transmettre des références de variables du thread d’appel de l’applet de commande à chaque thread de bloc de script en cours d’exécution. Étant donné que les blocs de script s’exécutent dans différents threads, les variables d’objet passées par référence doivent être utilisées en toute sécurité. En général, il est prudent de lire à partir d’objets référencés qui ne changent pas. Toutefois, si l’état de l’objet est modifié, vous devez utiliser des objets threads sécurisés, tels que les types .NET System.Collection.Concurrent (voir l’exemple 11).