ForEach-Object

Syntaxe

ForEach-Object <ScriptBlock> >] 

ForEach-Object <String> >] 

ForEach-Object -Parallel <scriptblock> 

.

Description

Le ForEach-Object cmdlet effectue une opération sur chaque élément d’une collection d’objets d’entrée. Les objets d’entrée peuvent être acheminés vers la cmdlet ou spécifiés à l’aide du paramètre InputObject.

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

• 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ètreProcess. Le bloc de script peut contenir tout 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 le beginprocess, et end blocs tels que décrits dansabout_functions.

  Note

  Les blocs de script s’exécutent dans la portée de l’appelant. Par conséquent, les blocs ont accès aux variables de cette portée et peuvent créer de nouvelles variables qui persistent dans cette portée après la fin du cmdlet.

L’instruction d’opération. Vous pouvez également écrire une instruction d’opération, qui ressemble beaucoup plus à un 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 chaqueprocess sur l’ordinateur.

Get-Process | ForEach-Object ProcessName

• Bloc de script à exécution parallèle. À partir 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 alors le nombre de scripts parallèles exécutés à 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é $using: pour transmettre des 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 afin d’assurer une isolation maximale.Cela peut représenter un gros impact sur les performances et les ressources si le travail que vous effectuez est faible par rapport à la création de nouveaux espaces d’exécution ou s’il y a beaucoup d’itérations effectuant un travail important. À partir de PowerShell 7.1, les espaces d’exécution d’un pool d’espaces d’exécution sont réutilisés par défaut. La taille du pool d’espaces de travail est spécifiée par le paramètre ThrottleLimit. La taille du pool d’espaces d’exécution par défaut est de 5. Vous pouvez toujours créer un nouvel 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 lancé les tâches parallèles.

  Les erreurs non terminées sont écrites dans le flux d’erreurs du cmdlet à mesure qu’elles se produisent dans les blocs de script parallèles. L’ordre d’exécution des blocs de script parallèles ne pouvant être déterminé, 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, comme warning, verbose ou information, sont écrits dans ces flux de données dans un ordre indéterminé.

  Les erreurs terminales, comme les exceptions, mettent fin à l’instance parallèle individuelle des scriptblocks dans lesquels elles se produisent. Une erreur de terminaison dans un scriptblocks peut ne pas provoquer la terminaison du Foreach-Object cmdlet. Les autres blocs de script, qui s’exécutent en parallèle, continuent de s’exécuter à moins qu’ils ne rencontrent également une erreur terminale. L’erreur de terminaison est écrite dans le flux de données d’erreur en tant que ErrorRecord avec un FullyQualifiedErrorId de PSTaskException.Les erreurs de terminaison peuvent être converties en erreurs de non-terminaison à l’aide des blocs try/catch ou trap de PowerShell.

Exemples

Exemple 1 : Diviser des entiers dans un tableau

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

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

Exemple 2 : Obtenir la longueur de tous les fichiers d’un répertoire

Cet exemple traite les fichiers et répertoires du répertoire d’installation de PowerShell $PSHOME.

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. Lecmdlet utilise la propriété PSISContainer pour déterminer si un objet est un répertoire.

Exemple 3 : Opérer sur les événements système les plus récents

Cet exemple écrit les 1000 événements les plus récents du journal des événements système dans un fichier texte. L’heure courante est affichée 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 obtient les 1000 événements les plus récents du journal des événements du Système et les stocke dans la variable$Events$Events est ensuite acheminé vers le cmdlet ForEach-Object. Le paramètre Beginaffiche la date et l’heure actuelles. Ensuite, le paramètre Process utilise le cmdlet Out-File pour créer un fichier texte nommé events.txt et y stocker la propriété message de chacun des événements. Enfin, le paramètre End est utilisé pour afficher la date et l’heure après la fin de tout le traitement.

Exemple 4 : changer la valeur d’une clé de registre

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

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

Vous pouvez utiliser ce format pour modifier la forme ou le contenu d’une valeur d’entrée de registre.

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

La commande utilise le cmdlet Get-ItemProperty pour obtenir toutes les sous-clés de la clé Network et le cmdlet Set-ItemProperty pour modifier la valeur de l’entrée de registre RemotePath dans chaque clé.Dans la commande Set-ItemProperty, le chemin 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 de caractères (REG_SZ).

Parce que Set-ItemProperty modifie la propriété de chaque clé, la cmdlet ForEach-Object estrequise pour accéder à la propriété.

Exemple 5 : utiliser la variable automatique $Null

Cet exemple montre l’effet du passage de la variable automatique $Null à la ForEach-Objectcmdlet.

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

Parce que PowerShell traite null comme un caractère de remplacement explicite, le cmdlet ForEach-Object génère une valeur pour $Null, tout comme il le fait pour les autres objets que vous lui transmettez par pipeline.

Exemple 6 : obtenir des valeurs de propriétés

Cet exemple obtient la valeur de la propriété Path de tous les modules PowerShell installés en utilisant le paramètre MemberName de la ForEach-Object cmdlet.

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

La deuxième commande est équivalente à la première. Elle utilise l’alias Foreach de la ForEach-Objectcmdlet et omet le nom du paramètre MemberName, qui est facultatif.

La cmdlet ForEach-Object est utile pour obtenir des valeurs de propriétés, car elle obtient la valeur sans en modifier le type, contrairement aux cmdlets Format ou à la cmdlet Select-Object, qui modifient le type de valeur de la propriété.

Exemple 7 : scinder les noms de modules en noms de composants

Cet exemple montre trois façons de scinder deux noms de modules séparés par des points en leurs noms de composants.

"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 "."MicrosoftPowerShellCoreMicrosoftPowerShellHost

Les commandes appellent la méthode Split des chaînes de caractères. Les trois commandes utilisent une syntaxe différente, mais elles sont équivalentes et interchangeables.

La première commande utilise la syntaxe traditionnelle, qui comprend un bloc de script et l’opérateur d’objet courant $_. Elle utilise la syntaxe du point pour spécifier la méthode et les parenthèses pour entourer le délimiteurargumentaire.

La deuxième commande utilise le paramètre MemberName pour spécifier la méthode Split et le paramètreArgumentName pour identifier le point (« . ») comme délimiteur de division.

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

Exemple 8 : Utilisation de ForEach-Object avec deux blocs de script

Dans cet exemple, nous passons deux blocs de script de manière positionnelle. Tous les blocs de script se lient au paramètreProcess. Cependant, ils sont traités comme s’ils avaient été passés aux paramètres Begin etProcess.

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

Exemple 9 : Utilisation de ForEach-Object avec plus de deux blocs de script

Dans cet exemple, nous passons deux blocs de script de manière positionnelle. Tous les blocs de script se lient au paramètreProcess. Cependant, ils sont traités comme s’ils avaient été passés aux paramètres Begin,Process et End.

1..2 | ForEach-Object { 'begin' } { 'process A' } { 'process B' } { 'end' }beginprocess Aprocess Bprocess Aprocess Bend

Exemple 10 : Exécuter plusieurs blocs de script pour chaque élément du pipeline

Comme le montre l’exemple précédent, plusieurs blocs de script transmis à 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 $nullonetwothreeonetwothree

Exemple 11 : Exécuter un script lent en lots parallèles

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

$Message = "Output:"1..8 | ForEach-Object -Parallel { "$using:Message $_" Start-Sleep 1} -ThrottleLimit 4Output: 1Output: 2Output: 3Output: 4Output: 5Output: 6Output: 7Output: 8

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

Exemple 12 : Récupérer les entrées de journal en parallèle

Cet exemple récupère 50 000 entrées de journal à partir de 5 journaux système sur une machine Windows locale.

$logNames = 'Security','Application','System','Windows PowerShell','Microsoft-Windows-Store/Operational'$logEntries = $logNames | ForEach-Object -Parallel { Get-WinEvent -LogName $_ -MaxEvents 10000} -ThrottleLimit 5$logEntries.Count50000

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.

Exemple 13 : Exécution en parallèle en tant que job

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

$job = 1..10 | ForEach-Object -Parallel { "Output: $_" Start-Sleep 1} -ThrottleLimit 2 -AsJob$job | Receive-Job -WaitOutput: 1Output: 2Output: 3Output: 4Output: 5Output: 6Output: 7Output: 8Output: 9Output: 10

la variable $job reçoit l’objet job qui collecte les données de sortie et surveille l’état d’exécution.L’objet job est pipé vers Receive-Job avec le paramètre switch Wait. Et cela diffuse la sortie vers la console, tout comme si ForEach-Object -Parallel était exécuté sans AsJob.

Exemple 14 : Utilisation de références de variables thread safe

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

$threadSafeDictionary = ]::new()Get-Process | ForEach-Object -Parallel { $dict = $using:threadSafeDictionary $dict.TryAdd($_.ProcessName, $_)}$threadSafeDictionaryNPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName ------ ----- ----- ------ -- -- ----------- 82 82.87 130.85 15.55 2808 2 pwsh

Une instance unique d’un objet ConcurrentDictionary est transmise à chaque bloc de script pour collecter lesobjets. Comme 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 à utiliser ici.

Exemple 15 : Écriture d’erreurs avec exécution parallèle

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: 1Write-Error: Error: 3Write-Error: Error: 2

Exemple 16 : Terminer les erreurs en exécution parallèle

Cet exemple démontre une erreur de terminaison dans un bloc de script en exécution parallèle.

1..5 | ForEach-Object -Parallel { if ($_ -eq 3) { throw "Terminating Error: $_" } Write-Output "Output: $_"}Exception: Terminating Error: 3Output: 1Output: 4Output: 2Output: 5

Output: 3 n’est jamais écrit car le bloc de script parallèle pour cette itération a été terminé.

Exemple 17 : Passage de variables dans un script parallèle imbriqué ScriptBlockSet

Vous pouvez créer une variable à l’extérieur d’un Foreach-Object -Parallel scriptblock scopé et l’utiliser à l’intérieur du scriptblock avec le mot-clé $using.

$test1 = 'TestA'1..2 | Foreach-Object -Parallel { $using:test1}TestATestA# 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 variable $test2 et une erreur est lancée.

Paramètres

Entrées

PSObject

Vous pouvez canaliser n’importe quel objet vers ce cmdlet.

Sorties

PSObject

Ce cmdlet renvoie des objets qui sont déterminés par l’entrée.

Notes

• Le cmdlet ForEach-Object fonctionne à peu près comme l’instruction Foreach, sauf que vous ne pouvez pas acheminer d’entrée à une instruction Foreach. Pour plus d’informations sur l’instruction Foreach, voirabout_Foreach.

• Depuis PowerShell 4.0, les méthodes Where et ForEach ont été ajoutées pour être utilisées avec les collections. Vous pouvez en savoir plus sur ces nouvelles méthodes ici about_arrays

• Le ForEach-Object -Parallel jeu de paramètres utilise l’API interne de PowerShell pour exécuter chaque scriptblock. Cela représente une surcharge significative par rapport à l’exécution de ForEach-Object normalement avec le traitement séquentiel. Il est important d’utiliser Parallel lorsque la surcharge de l’exécution en parallèle est faible par rapport au travail effectué par le bloc de script. Par exemple :

  • Scripts intensifs en calcul sur des machines multicœurs
  • Scripts qui passent du temps à attendre des résultats ou à effectuer des opérations sur des fichiers

  L’utilisation du paramètre Parallèle peut entraîner une exécution des scripts beaucoup plus lente que la normale. Surtout si les scripts parallèles sont triviaux. Expérimentez avec Parallel pour découvrir où il peut êtrebénéfique.

  Important

  Le ForEach-Object -Parallel jeu de paramètres exécute les blocs de script en parallèle sur des processthreads séparés. Le mot-clé $using: permet de passer des références de variables du cmdlet invocationthread à chaque thread de bloc de script en cours d’exécution. Comme les blocs de script s’exécutent dans des threads différents, les variables d’objet passées par référence doivent être utilisées en toute sécurité. En général, il est sûr de lire des objets référencés qui ne changent pas. Mais si l’état de l’objet est modifié, alors vous devez utiliser des objets thread safe, tels que les types .Net System.Collection.Concurrent (voir exemple 11).

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

.