à propos des variables automatiques

Brève description

Décrit les variables qui stockent les informations d’état et qui sont créées et gérées par PowerShell.

Description longue

Conceptuellement, la plupart de ces variables sont considérées comme étant en lecture seule. Même s'il est possible d'écrire sur ces disques, il ne faut pas le faire pour des raisons de compatibilité ascendante.

Voici une liste des variables automatiques dans PowerShell :

• $$
• $?
• $^
• $_
• $args
• $ConsoleFileName
• $EnabledExperimentalFeatures
• $Error
• $Event
• $EventArgs
• $EventSubscriber
• $ExecutionContext
• $false
• $foreach
• $HOME
• $Host
• $input
• $IsCoreCLR
• $IsLinux
• $IsMacOS
• $IsWindows
• $LASTEXITCODE
• $Matches
• $MyInvocation
• $NestedPromptLevel
• $null
• $PID
• $PROFILE
• $PSBoundParameters
• $PSCmdlet
• $PSCommandPath
• $PSCulture
• $PSDebugContext
• $PSEdition
• $PSHOME
• $PSItem
• $PSScriptRoot
• $PSSenderInfo
• $PSUICulture
• $PSVersionTable
• $PWD
• $Sender
• $ShellId
• $StackTrace
• $switch
• $this
• $true

$$

Contient le dernier jeton de la dernière ligne reçue par la session.

$?

Contient l’état d’exécution de la dernière commande. Il contient True si la dernière commande a réussi et False si elle a échoué. Les erreurs d’analyse n’entraînent pas l’exécution. Elles n’affectent donc pas la valeur de $?.

Pour les cmdlets et les fonctions avancées qui sont exécutées à plusieurs étapes d'un pipeline, par exemple dans les blocs process et end, le fait d'appeler this.WriteError() ou $PSCmdlet.WriteError() respectivement à n'importe quel moment définit $? à False, tout comme this.ThrowTerminatingError() et $PSCmdlet.ThrowTerminatingError().

L’applet de commande Write-Error définit toujours $? sur False immédiatement après son exécution, mais ne définit pas $? sur False pour une fonction qui l’appelle :

function Test-WriteError
{
    Write-Error "Bad"
    "The `$? variable is: $?"
}

Test-WriteError
"Now the `$? variable is: $?"

Test-WriteError:
Line |
   7 |  Test-WriteError
     |  ~~~~~~~~~~~~~~~
     | Bad
The $? variable is: False
Now the $? variable is: True

À cette fin, $PSCmdlet.WriteError() doit être utilisé à la place.

Pour les commandes natives (exécutables), $? est défini sur True lorsque $LASTEXITCODE est 0 et défini sur False lorsque $LASTEXITCODE est une autre valeur.

$^

Contient le premier élément de la dernière ligne reçue par la session.

$_

Identique à $PSItem. Contient l’objet actif dans l’objet de pipeline. Vous pouvez utiliser cette variable dans les commandes qui effectuent une action sur chaque objet d’un pipeline.

Pour plus d'informations, voir about_PSItem.

$args

Contient un tableau de valeurs pour les paramètres non déclarés passés à une fonction, un script ou un scriptblock. Lorsque vous créez une fonction, vous pouvez déclarer les paramètres avec le mot clé param ou en ajoutant une liste séparée par des virgules de paramètres entre parenthèses après le nom de la fonction.

Dans une action d’événement, la variable $args contient des objets qui représentent les arguments d’événement de l’événement en cours de traitement. Cette variable est remplie uniquement dans le bloc Action d’une commande d’inscription d’événements. La valeur de cette variable se trouve également dans la propriété SourceArgs de l’objet PSEventArgs que Get-Event retourne.

$ConsoleFileName

Contient le chemin d’accès du fichier console (.psc1) qui a été utilisé le plus récemment dans la session. Cette variable est remplie lorsque vous démarrez PowerShell avec le paramètre PSConsoleFile ou lorsque vous utilisez le cmdlet Export-Console pour exporter les noms des snap-ins dans un fichier console.

Lorsque vous utilisez l’applet de commande Export-Console sans paramètres, elle met automatiquement à jour le fichier console qui a été utilisé le plus récemment dans la session. Vous pouvez utiliser cette variable automatique pour déterminer le fichier à mettre à jour.

$EnabledExperimentalFeatures

Contient la liste des noms des fonctionnalités expérimentales activées.

$Error

Contient un tableau d’objets d’erreur qui représentent les erreurs les plus récentes. L’erreur la plus récente est le premier objet d’erreur dans le tableau $Error[0].

Pour empêcher l’ajout d’une erreur au tableau $Error, utilisez le paramètre commun ErrorAction avec la valeur Ignorer. Pour plus d’informations, consultez about_CommonParameters.

$Event

Contient un objet PSEventArgs qui représente l’événement en cours de traitement. Cette variable est renseignée uniquement dans le bloc Action d’une commande d’inscription d’événements, telle que Register-ObjectEvent. La valeur de cette variable est le même objet que celui retourné par l’applet de commande Get-Event. Vous pouvez utiliser les propriétés de la Event variable, telles que $Event.TimeGenerated, dans un Action scriptblock.

$EventArgs

Contient un objet qui représente le premier argument d’événement qui dérive de EventArgs de l’événement en cours de traitement. Cette variable est remplie uniquement dans le bloc Action d’une commande d’inscription d’événements. La valeur de cette variable se trouve également dans la propriété SourceEventArgs de l’objet PSEventArgs retourné par Get-Event.

$EventSubscriber

Contient un objet PSEventSubscriber qui représente l’abonné à l’événement en cours de traitement. Cette variable est remplie uniquement dans le bloc Action d’une commande d’inscription d’événements. La valeur de cette variable est le même objet que celui retourné par l’applet de commande Get-EventSubscriber.

$ExecutionContext

Contient un objet EngineIntrinsics qui représente le contexte d’exécution de l’hôte PowerShell. Vous pouvez utiliser cette variable pour rechercher les objets d’exécution disponibles pour les applets de commande.

$false

Contient False. Vous pouvez utiliser cette variable pour représenter false dans les commandes et les scripts au lieu d’utiliser la chaîne "false". La chaîne peut être interprétée comme True si elle est convertie en chaîne non vide ou en entier non nul.

$foreach

Contient l’énumérateur (et non les valeurs résultantes) d’une boucle foreach. La variable $foreach existe uniquement pendant l’exécution de la boucle foreach ; elle est supprimée une fois la boucle terminée.

Les énumérateurs contiennent des propriétés et des méthodes que vous pouvez utiliser pour récupérer des valeurs de boucle et modifier l’itération de boucle actuelle. Pour plus d’informations, consultez Using Enumerators.

$HOME

Contient le chemin complet du répertoire de base de l’utilisateur. Sur Windows, cette variable utilise la valeur de la variable d’environnement "$Env:USERPROFILE" Windows, généralement C:\Users\<UserName>. Sur Unix, cette variable utilise la valeur de la variable d’environnement HOME.

$Host

Contient un objet qui représente l’application hôte actuelle pour PowerShell. Vous pouvez utiliser cette variable pour représenter l’hôte actuel dans les commandes ou pour afficher ou modifier les propriétés de l’hôte, telles que $Host.Version ou $Host.CurrentCulture, ou $Host.UI.RawUI.BackGroundColor = "Red".

$input

Contient un énumérateur qui énumère toutes les entrées passées à une fonction. La $input variable est disponible uniquement pour les fonctions, les scriptsblocks (qui sont des fonctions non nommées) et les fichiers de script (qui sont enregistrés scriptblocks).

• Dans une fonction sans begin, processou end bloc, la variable $input énumère la collection de toutes les entrées de la fonction.

• Dans le bloc begin, la variable $input ne contient aucune donnée.

• Dans le bloc process, la variable $input contient l’objet actuel dans le pipeline.

• Dans le bloc end, la variable $input énumère la collection de toutes les entrées de la fonction.

  Remarque

  Vous ne pouvez pas utiliser la $input variable à l’intérieur du process bloc et du end bloc dans la même fonction ou scriptblock.

Étant donné que $input est un énumérateur, l’accès à l’une de ses propriétés entraîne l’absence de $input disponible. Vous pouvez stocker $input dans une autre variable pour réutiliser les propriétés $input.

Les énumérateurs contiennent des propriétés et des méthodes que vous pouvez utiliser pour récupérer des valeurs de boucle et modifier l’itération de boucle actuelle. Pour plus d’informations, consultez Using Enumerators.

La variable $input est également disponible pour la commande spécifiée par le paramètre -Command de pwsh lorsqu’elle est appelée à partir de la ligne de commande. L’exemple suivant est exécuté à partir de l’interpréteur de commandes Windows.

echo Hello | pwsh -Command """$input World!"""

$IsCoreCLR

Contient $true si la session active s’exécute sur le runtime .NET Core (CoreCLR). Sinon, contient $false.

$IsLinux

Contient $true si la session active s’exécute sur un système d’exploitation Linux. Sinon, contient $false.

$IsMacOS

Contient $true si la session active s’exécute sur un système d’exploitation macOS. Sinon, contient $false.

$IsWindows

Contient $true si la session active s’exécute sur un système d’exploitation Windows. Sinon, contient $false.

$LASTEXITCODE

Contient le code de sortie du dernier programme natif ou script PowerShell exécuté.

Pour les scripts PowerShell, la valeur de $LASTEXITCODE dépend de la façon dont le script a été appelé et si le mot clé exit a été utilisé :

• Lorsqu’un script utilise le mot clé exit :

  $LASTEXITCODE est réglé à la valeur spécifiée par le mot clé exit. Pour plus d'informations, voir about_Language_Keywords.

• Lorsqu’un script est appelé directement, comme ./Test.ps1, ou avec l’opérateur d’appel (&) comme & ./Test.ps1:

  La valeur de $LASTEXITCODE n’est pas modifiée, sauf si :

  • Le script appelle un autre script qui utilise le mot clé exit
  • Le script appelle une commande native
  • Le script utilise le mot clé exit

• Lorsqu’un script est appelé avec à l’aide du paramètre fichier , est défini sur :

  • 1 si le script s’est arrêté en raison d’une exception
  • Valeur spécifiée par le mot clé exit, si elle est utilisée dans le script
  • 0 si le script s’est terminé avec succès

• Lorsqu’un script est appelé avec à l’aide du paramètre command , est défini sur :

  • 1 si le script s'est terminé en raison d'une exception ou si le résultat de la dernière commande a fixé $? à $false
  • 0 si le script s’est terminé correctement et que le résultat de l'ensemble de commandes a mis $? sur $true

Pour plus d’informations sur les paramètres de fichier et de commande , consultez about_Pwsh.

$Matches

La variable $Matches fonctionne avec les opérateurs -match et -notmatch. Lorsque vous envoyez entrée scalaire à l’opérateur -match ou -notmatch, et qu’une seule détecte une correspondance, elle retourne une valeur booléenne et remplit la variable automatique $Matches avec une table de hachage de toutes les valeurs de chaîne qui ont été mises en correspondance. La table de hachage $Matches peut également être remplie avec des captures lorsque vous utilisez des expressions régulières avec l’opérateur -match.

Pour plus d'informations sur l'opérateur -match, consultez à propos des opérateurs de comparaison. Pour plus d’informations sur les expressions régulières, consultez about_Regular_Expressions.

La variable $Matches fonctionne également dans une instruction switch avec le paramètre -Regex. Il est renseigné de la même manière que les opérateurs -match et -notmatch. Pour plus d’informations sur la déclaration switch, consultez about_Switch.

$MyInvocation

Contient des informations sur la commande actuelle, telles que le nom, les paramètres, les valeurs de paramètres, et les informations sur la façon dont la commande a été démarrée, exécutée ou invoquée, par exemple le nom du script qui a appelé la commande actuelle.

$MyInvocation est renseigné uniquement pour les scripts, les fonctions et les blocs de script. Vous pouvez utiliser les informations de l’objet System.Management.Automation.InvocationInfo qui $MyInvocation retourne dans le script actuel, par exemple le nom d’une fonction ($MyInvocation.MyCommand.Name) pour identifier la commande active. Cela est utile pour trouver le nom du script actuel.

À compter de PowerShell 3.0, MyInvocation a les nouvelles propriétés suivantes.

• PSScriptRoot : contient le chemin d’accès complet au script qui a appelé la commande actuelle. La valeur de cette propriété est renseignée uniquement lorsque l’appelant est un script.
• PSCommandPath : contient le chemin d’accès complet et le nom de fichier du script qui a appelé la commande actuelle. La valeur de cette propriété est renseignée uniquement lorsque l’appelant est un script.

Contrairement aux variables automatiques $PSScriptRoot et $PSCommandPath, les PSScriptRoot et les propriétés PSCommandPath de la variable automatique $MyInvocation contiennent des informations sur l’appelant ou le script appelant, et non sur le script actuel.

$NestedPromptLevel

Contient le niveau d’invite actuel. La valeur 0 indique le niveau d’invite d’origine. La valeur est incrémentée lorsque vous entrez un niveau imbriqué et décrémentée lorsque vous le quittez.

Par exemple, PowerShell présente une invite de commandes imbriquée lorsque vous utilisez la méthode $Host.EnterNestedPrompt. PowerShell présente également une requête de commande imbriquée lorsque vous atteignez un point d'arrêt dans le débogueur PowerShell.

Lorsque vous entrez une invite imbriquée, PowerShell suspend la commande actuelle, enregistre le contexte d’exécution et incrémente la valeur de la variable $NestedPromptLevel. Pour créer des invites de commandes imbriquées supplémentaires (jusqu’à 128 niveaux) ou revenir à l’invite de commandes d’origine, terminez la commande ou tapez exit.

La variable $NestedPromptLevel vous permet de suivre le niveau de la requête. Vous pouvez créer une autre invite de commandes PowerShell qui inclut cette valeur afin qu’elle soit toujours visible.

$null

$null est une variable automatique qui contient une valeur null ou vide. Vous pouvez utiliser cette variable pour représenter une valeur absente ou non définie dans les commandes et les scripts.

PowerShell traite $null en tant qu’objet avec une valeur ou un espace réservé. Vous pouvez donc utiliser $null pour représenter une valeur vide dans une collection de valeurs.

Par exemple, lorsque $null est inclus dans une collection, il est compté comme l’un des objets.

$a = "one", $null, "three"
$a.Count

3

Si vous dirigez la variable $null vers l’applet de commande ForEach-Object, elle génère une valeur pour $null, tout comme pour les autres objets

"one", $null, "three" | ForEach-Object {"Hello " + $_}

Hello one
Hello
Hello three

Par conséquent, vous ne pouvez pas utiliser $null pour signifier qu'il n'y a pas de valeur de paramètre. Une valeur de paramètre de $null remplace la valeur de paramètre par défaut.

Toutefois, étant donné que PowerShell traite la variable $null comme un espace réservé, vous pouvez l’utiliser dans des scripts comme celui-ci, ce qui ne fonctionnerait pas si $null était ignoré.

$calendar = @($null, $null, "Meeting", $null, $null, "Team Lunch", $null)
$days = "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
        "Friday", "Saturday"
$currentDay = 0
foreach($day in $calendar)
{
    if($day -ne $null)
    {
        "Appointment on $($days[$currentDay]): $day"
    }

    $currentDay++
}

Appointment on Tuesday: Meeting
Appointment on Friday: Team lunch

$PID

Contient l’identificateur de processus (PID) du processus qui héberge la session PowerShell actuelle.

$PROFILE

Contient le chemin complet du profil PowerShell pour l’utilisateur actuel et l’application hôte actuelle. Vous pouvez utiliser cette variable pour représenter le profil dans les commandes. Par exemple, vous pouvez l’utiliser dans une commande pour déterminer si un profil a été créé :

Test-Path $PROFILE

Vous pouvez également l’utiliser dans une commande pour créer un profil :

New-Item -ItemType File -Path $PROFILE -Force

Vous pouvez l’utiliser dans une commande pour ouvrir le profil dans notepad.exe:

notepad.exe $PROFILE

$PSBoundParameters

Contient un dictionnaire des paramètres passés à un script ou à une fonction et à leurs valeurs actuelles. Cette variable a une valeur uniquement dans une étendue où les paramètres sont déclarés, tels qu’un script ou une fonction. Vous pouvez l’utiliser pour afficher ou modifier les valeurs actuelles des paramètres ou passer des valeurs de paramètre à un autre script ou fonction.

Dans cet exemple, la fonction Test2 transmet les $PSBoundParameters à la fonction Test1. Les $PSBoundParameters sont affichés au format Clé et Valeur.

function Test1 {
   param($a, $b)

   # Display the parameters in dictionary format.
   $PSBoundParameters
}

function Test2 {
   param($a, $b)

   # Run the Test1 function with $a and $b.
   Test1 @PSBoundParameters
}

Test2 -a Power -b Shell

Key   Value
---   -----
a     Power
b     Shell

$PSCmdlet

Contient un objet qui représente l’applet de commande ou la fonction avancée en cours d’exécution.

Vous pouvez utiliser les propriétés et méthodes de l’objet dans votre applet de commande ou votre code de fonction pour répondre aux conditions d’utilisation. Par exemple, la propriété ParameterSetName contient le nom du jeu de paramètres utilisé et la méthode ShouldProcess ajoute les paramètres WhatIf et Confirmer les paramètres à l’applet de commande de manière dynamique.

Pour plus d’informations sur la variable automatique $PSCmdlet, consultez about_Functions_CmdletBindingAttribute et about_Functions_Advanced.

$PSCommandPath

Contient le chemin d’accès complet et le nom de fichier du script en cours d’exécution. Cette variable est valide dans tous les scripts.

$PSCulture

À compter de PowerShell 7, $PSCulture reflète la culture de l’espace d’exécution PowerShell actuel (session). Si la culture est modifiée dans un runspace PowerShell, la valeur $PSCulture pour cet espace d’exécution est mise à jour.

La culture détermine le format d’affichage des éléments tels que les nombres, la devise et les dates, et est stocké dans un objet System.Globalization.CultureInfo. Utilisez Get-Culture pour afficher la culture de l’ordinateur. $PSCulture contient la valeur de la propriété Name.

$PSDebugContext

Lors du débogage, cette variable contient des informations sur l’environnement de débogage. Sinon, il contient une valeur nulle. Par conséquent, vous pouvez l’utiliser pour déterminer si le débogueur a le contrôle. Lorsqu'il est rempli, il contient un objet PsDebugContext qui possède les propriétés Breakpoints et InvocationInfo. La propriété InvocationInfo possède plusieurs propriétés utiles, dont la propriété Location. La propriété Location indique le chemin du script en cours de débogage.

$PSEdition

Contient la même valeur dans $PSVersionTable.PSEdition. Cette variable est disponible pour être utilisée dans les fichiers manifestes de module, tandis que $PSVersionTable n’est pas.

$PSHOME

Contient le chemin complet du répertoire d’installation de PowerShell, généralement C:\Program Files\PowerShell\7 dans les systèmes Windows. Vous pouvez utiliser cette variable dans les chemins d’accès des fichiers PowerShell. Par exemple, la commande suivante recherche le mot Help dans les rubriques d'aide conceptuelle :

Select-String -Pattern Help -Path $PSHOME\en-US\*.txt

$PSItem

Identique à $_. Contient l’objet actif dans l’objet de pipeline. Vous pouvez utiliser cette variable dans les commandes qui effectuent une action sur chaque objet d’un pipeline.

Pour plus d'informations, voir about_PSItem.

$PSScriptRoot

Contient le chemin complet du répertoire parent du script en cours d’exécution.

Dans PowerShell 2.0, cette variable est valide uniquement dans les modules de script (.psm1). À compter de PowerShell 3.0, il est valide dans tous les scripts.

$PSSenderInfo

Contient des informations sur l’utilisateur qui a démarré psSession, y compris l’identité de l’utilisateur et le fuseau horaire de l’ordinateur d’origine. Cette variable est disponible uniquement dans les sessions PSSession.

La variable $PSSenderInfo inclut une propriété configurable par l’utilisateur, ApplicationArguments, qui contient par défaut uniquement les $PSVersionTable de la session d’origine. Pour ajouter des données à la propriété ApplicationArguments, utilisez le paramètre ApplicationArguments de l’applet de commande New-PSSessionOption.

$PSUICulture

Contient le nom de la culture de l’interface utilisateur configurée dans le système d’exploitation. La culture de l’interface utilisateur détermine les chaînes de texte utilisées pour les éléments d’interface utilisateur, tels que les menus et les messages. Il s’agit de la valeur de la propriété System.Globalization.CultureInfo.CurrentUICulture.Name du système. Pour obtenir l’objet System.Globalization.CultureInfo pour le système, utilisez l’applet de commande Get-UICulture.

$PSVersionTable

Contient une table de hachage en lecture seule qui affiche des détails sur la version de PowerShell en cours d’exécution dans la session active. Le tableau comprend les éléments suivants :

• PSVersion - Le numéro de version de PowerShell
• PSEdition Cette propriété a la valeur « Desktop » pour PowerShell 4 et ci-dessous, ainsi que PowerShell 5.1 sur les éditions Windows complètes. Cette propriété a la valeur de Core pour PowerShell 6 et versions ultérieures, ainsi que Windows PowerShell 5.1 sur des éditions à encombrement réduit comme Windows Nano Server ou Windows IoT.
• GitCommitId - ID de validation des fichiers sources, dans GitHub,
• système d’exploitation - Description du système d’exploitation sur lequel PowerShell s’exécute.
• Platform - Plateforme sur laquelle le système d’exploitation s’exécute. La valeur sur Linux et macOS est unix. Voir $IsMacOS et $IsLinux.
• PSCompatibleVersions - Versions de PowerShell compatibles avec la version actuelle
• PSRemotingProtocolVersion : version du protocole de gestion à distance PowerShell.
• SerializationVersion - La version de la méthode de sérialisation.
• WSManStackVersion : numéro de version de la pile WS-Management

$PWD

Contient un objet chemin qui représente le chemin d’accès complet du répertoire actuel pour l’instance d’exécution de PowerShell actuelle.

$Sender

Contient l’objet qui a généré cet événement. Cette variable est remplie uniquement dans le bloc Action d’une commande d’inscription d’événement. La valeur de cette variable est également disponible dans la propriété Sender de l’objet PSEventArgs qui est retourné par Get-Event.

$ShellId

Contient l’identificateur de l’interpréteur de commandes actuel.

$StackTrace

Contient une trace de pile pour l'erreur la plus récente.

$switch

Contient l’énumérateur et non les valeurs résultantes d’une instruction switch. La variable $switch existe uniquement pendant l’exécution de l’instruction switch ; il est supprimé lorsque l’instruction switch termine l’exécution. Pour plus d'informations, reportez-vous à about_Switch.

Les énumérateurs contiennent des propriétés et des méthodes que vous pouvez utiliser pour récupérer des valeurs de boucle et modifier l’itération de boucle actuelle. Pour plus d’informations, consultez Using Enumerators.

$this

La $this variable est utilisée dans les blocs de script qui étendent les classes pour faire référence à l’instance de la classe elle-même.

Le système de type extensible (ETS) de PowerShell vous permet d’ajouter des propriétés à des classes à l’aide de scriptsblocks. Dans un scriptblock qui définit une propriété de script ou une méthode de script, la $this variable fait référence à une instance d’objet de la classe qui est étendue. Par exemple, PowerShell utilise ETS pour ajouter la propriété BaseName à la classe FileInfo .

PS> Get-ChildItem .\README.md | Get-Member BaseName | Format-List

TypeName   : System.IO.FileInfo
Name       : BaseName
MemberType : ScriptProperty
Definition : System.Object BaseName {get=if ($this.Extension.Length -gt 0)
             {$this.Name.Remove($this.Name.Length - $this.Extension.Length
             )}else{$this.Name};}

Pour plus d’informations, consultez about_Types.ps1xml.

Dans une classe PowerShell, la variable $this fait référence à l’objet d’instance de la classe elle-même, ce qui permet d’accéder aux propriétés et méthodes définies dans la classe. Pour plus d’informations, consultez about_Classes.

La $this variable est également utilisée par les classes d’événements .NET qui prennent des blocs de script en tant que délégués pour le gestionnaire d’événements. Dans ce scénario, $this représente l’objet d’origine de l’événement, appelé expéditeur de l’événement.

$true

Contient True. Vous pouvez utiliser cette variable pour représenter true dans les commandes et les scripts.

Utilisation d’énumérateurs

Les variables $input, $foreachet $switch sont tous des énumérateurs utilisés pour itérer les valeurs traitées par leur bloc de code contenant.

Un énumérateur contient des propriétés et des méthodes que vous pouvez utiliser pour avancer ou réinitialiser l’itération, ou récupérer des valeurs d’itération. La manipulation directe d’énumérateurs n’est pas considérée comme une bonne pratique.

• Dans les boucles, les mots-clés de contrôle de flux break et continue doivent être préférés.

• Dans les fonctions qui acceptent l’entrée de pipeline, il est préférable d’utiliser des paramètres avec les attributs ValueFromPipeline ou ValueFromPipelineByPropertyName.

  Pour plus d'informations, voir about_Functions_Advanced_Parameters.

PasserSuivant

La méthode MoveNext avance l’énumérateur vers l’élément suivant de la collection. MoveNext renvoie True si l'énumérateur a été avancé avec succès, False si l'énumérateur a dépassé la fin de la collection.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

La méthode Reset définit l’énumérateur à sa position initiale, qui est avant le premier élément de la collection.

Current

La propriété Current obtient l’élément de la collection, ou du pipeline, à la position actuelle de l’énumérateur.

La propriété Current continue de renvoyer la même propriété jusqu'à ce que MoveNext soit appelé.

Examples

Exemple 1 : Utilisation de la variable $input

Dans l’exemple suivant, l’accès à la variable $input efface la variable jusqu’à la prochaine exécution du bloc de processus. L’utilisation de la méthode Reset réinitialise la variable $input à la valeur de pipeline actuelle.

function Test
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tInput: $input"
        "`tAccess Again: $input"
        $input.Reset()
        "`tAfter Reset: $input"
    }
}

"one","two" | Test

Iteration: 0
    Input: one
    Access Again:
    After Reset: one
Iteration: 1
    Input: two
    Access Again:
    After Reset: two

Le bloc de processus avance automatiquement la variable $input même si vous ne l’accédez pas.

$skip = $true
function Skip
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        if ($skip)
        {
            "`tSkipping"
            $skip = $false
        }
        else
        {
            "`tInput: $input"
        }
    }
}

"one","two" | Skip

Iteration: 0
    Skipping
Iteration: 1
    Input: two

Exemple 2 : Utilisation de $input en dehors du bloc de processus

En dehors du bloc de processus, la variable $input représente toutes les valeurs redirigées vers la fonction.

• L’accès à la variable $input efface toutes les valeurs.
• La méthode Reset réinitialise l’ensemble de la collection.
• La propriété Current n’est jamais peuplée.
• La méthode MoveNext retourne false, car la collection ne peut pas être avancée.
  • L’appel MoveNext efface la variable $input.

Function All
{
    "All Values: $input"
    "Access Again: $input"
    $input.Reset()
    "After Reset: $input"
    $input.MoveNext() | Out-Null
    "After MoveNext: $input"
}

"one","two","three" | All

All Values: one two three
Access Again:
After Reset: one two three
After MoveNext:

Exemple 3 : Utilisation de la propriété $input.Current

Avec la propriété Current, la valeur actuelle du pipeline est accessible plusieurs fois sans utiliser la méthode Reset. Le bloc de processus n’appelle pas automatiquement la méthode MoveNext.

La propriété Current n’est jamais peuplée, sauf si vous appelez explicitement MoveNext. La propriété Current est accessible plusieurs fois à l’intérieur du bloc de processus sans effacer sa valeur.

function Current
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tBefore MoveNext: $($input.Current)"
        $input.MoveNext() | Out-Null
        "`tAfter MoveNext: $($input.Current)"
        "`tAccess Again: $($input.Current)"
    }
}

"one","two" | Current

Iteration: 0
    Before MoveNext:
    After MoveNext: one
    Access Again: one
Iteration: 1
    Before MoveNext:
    After MoveNext: two
    Access Again: two

Exemple 4 : Utilisation de la variable $foreach

Contrairement à la variable $input, la variable $foreach représente toujours tous les éléments de la collection lorsqu’elle est accessible directement. Utilisez la propriété Current pour accéder à l’élément de collection actuel, ainsi que les méthodes Reset et MoveNext pour modifier sa valeur.

La boucle suivante s’exécute uniquement deux fois. Dans la deuxième itération, la collection est déplacée vers le troisième élément avant la fin de l’itération. Après la deuxième itération, il n’y a plus de valeurs à itérer, et la boucle se termine.

La propriété MoveNext n’affecte pas la variable choisie pour effectuer une itération dans la collection ().

$i = 0
foreach ($num in ("one","two","three"))
{
    "Iteration: $i"
    $i++
    "`tNum: $num"
    "`tCurrent: $($foreach.Current)"

    if ($foreach.Current -eq "two")
    {
        "Before MoveNext (Current): $($foreach.Current)"
        $foreach.MoveNext() | Out-Null
        "After MoveNext (Current): $($foreach.Current)"
        "Num hasn't changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num hasn't changed: two

L’utilisation de la méthode Reset réinitialise l’élément actuel dans la collection. L'exemple suivant passe en boucle les deux premiers éléments deux fois parce que la méthode Reset est appelée. Après les deux premières boucles, l’instruction if échoue et la boucle itère normalement les trois éléments.

$stopLoop = 0
foreach ($num in ("one","two", "three"))
{
    ("`t" * $stopLoop) + "Current: $($foreach.Current)"

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset()
        ("`t" * $stopLoop) + "Reset Loop: $stopLoop"
        $stopLoop++
    }
}

Current: one
Current: two
Reset Loop: 0
        Current: one
        Current: two
        Reset Loop: 1
                Current: one
                Current: two
                Current: three

Exemple 5 : Utilisation de la variable $switch

La variable $switch a exactement les mêmes règles que la variable $foreach. L’exemple suivant illustre tous les concepts d’énumérateur.

$values = "Start", "MoveNext", "NotEvaluated", "Reset", "End"
$stopInfinite = $false
switch ($values)
{
    "MoveNext" {
        "`tMoveNext"
        $switch.MoveNext() | Out-Null
        "`tAfter MoveNext: $($switch.Current)"
    }
    # This case is never evaluated.
    "NotEvaluated" {
        "`tAfterMoveNext: $($switch.Current)"
    }

    "Reset" {
        if (!$stopInfinite)
        {
            "`tReset"
            $switch.Reset()
            $stopInfinite = $true
        }
    }

    default {
        "Default (Current): $($switch.Current)"
    }
}

Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
    Reset
Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
Default (Current): End

Voir aussi

• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_OutputTypeAttribute
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Splatting
• about_Variables