about_Automatic_Variables

Article
11/06/2024

Description courte

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

Conceptuellement, la plupart de ces variables sont considérées comme étant en lecture seule. Même s’ils peuvent être écrits, pour une compatibilité descendante, ils ne doivent pas être écrits dans.

Voici une liste des variables automatiques dans PowerShell :

$$
$?
$^
$_
$args
$ConsoleFileName
$Error
$Event
$EventArgs
$EventSubscriber
$ExecutionContext
$false
$foreach
$HOME
$Host
$input
$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

Description longue

$$

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. Elle contient True si la dernière commande a réussi et False en cas d’échec. Les erreurs d’analyse n’entraînent pas l’exécution, de sorte qu’elles n’affectent pas la valeur de $?.

Pour les applets de commande et les fonctions avancées exécutées à plusieurs étapes dans un pipeline, par exemple dans les deux process et end les blocs, l’appel this.WriteError() ou $PSCmdlet.WriteError() respectivement à tout point défini $? sur False, comme le fait this.ThrowTerminatingError() et $PSCmdlet.ThrowTerminatingError().

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

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

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

Test-WriteError : Bad
At line:7 char:1
+ Test-WriteError
+ ~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Test-WriteError

The $? variable is: False
Now the $? variable is: True

À cette fin, $PSCmdlet.WriteError() il convient d’utiliser à la place.

Pour les commandes natives (exécutables), $? a la valeur True quand $LASTEXITCODE est 0, et a la valeur False lorsqu’il $LASTEXITCODE s’agit d’une autre valeur.

Remarque

Jusqu’à PowerShell 7, encapsulez une instruction entre parenthèses (...), syntaxe $(...)de sous-expression ou expression @(...) de tableau toujours reset$? à True. Par exemple, (Write-Error) affiche $? la valeur True. Ce comportement a changé dans PowerShell 7, ce qui $? reflète toujours la réussite réelle de la dernière exécution de commande dans ces expressions.

$^

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

$_

Comme pour $PSItem. Contient l’objet current 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, consultez about_PSItem.

$args

Contient un tableau de valeurs pour les paramètres non déclarés passés à une fonction, un script ou un bloc de script. Lorsque vous créez une fonction, vous pouvez déclarer les paramètres avec le param mot clé 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 $args variable 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 Action bloc d’une commande d’inscription d’événements. La valeur de cette variable est également disponible dans la propriété SourceArgs de l’objet PSEventArgs qui 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 l’applet Export-Console de commande pour exporter des noms de composants logiciels enfichables dans un fichier console.

Lorsque vous utilisez l’applet Export-Console de commande 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.

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 $Error tableau, utilisez le paramètre commun ErrorAction avec la valeur Ignorer. Pour plus d’informations, consultez about_CommonParameters.

$Event

Contient un PSEventArgs objet qui représente l’événement en cours de traitement. Cette variable est remplie uniquement dans le Action bloc 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 Get-Event de commande. Vous pouvez utiliser les propriétés de la Event variable, telles que $Event.TimeGenerated, dans un Action bloc de script.

$EventArgs

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

$EventSubscriber

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

$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 $ForEach variable existe uniquement pendant l’exécution de la ForEach boucle ; 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 current la boucle. Pour plus d’informations, consultez Utilisation des énumérateurs.

$HOME

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

Important

Windows peut rediriger l’emplacement du profil de l’utilisateur. Cela signifie que $HOME cela peut ne pas avoir la même valeur que "$env:HOMEDRIVE$env:HOMEPATH".

$Host

Contient un objet qui représente l’application current hôte pour PowerShell. Vous pouvez utiliser cette variable pour représenter l’hôte current 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 blocs de script (qui sont des fonctions non nommées) et les fichiers de script (qui sont des blocs de script enregistrés).

Dans une fonction sans begin, processou end bloc, la $input variable énumère la collection de toutes les entrées de la fonction.
Dans le begin bloc, la $input variable ne contient aucune donnée.
Dans le process bloc, la $input variable contient l’objet current dans le pipeline.
Dans le end bloc, la $input variable é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 le même bloc de script.

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

La $input variable est également disponible pour la commande spécifiée par le -Command paramètre de powershell.exe 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 | powershell -Command """$input World!"""

$LASTEXITCODE

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

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

Lorsqu’un script utilise le exit mot clé :

$LASTEXITCODE est défini sur la valeur spécifiée par le exit mot clé. Pour plus d’informations, consultez about_Language_Keywords.
Lorsqu’un script est appelé directement, par ./Test.ps1exemple, 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 exit mot clé
- Le script appelle une commande native
- Le script utilise le exit mot clé
Lorsqu’un script est appelé à powershell.exe l’aide du paramètre File , $LASTEXITCODE est défini sur :
- 1 si le script s’est arrêté en raison d’une exception
- Valeur spécifiée par le exit mot clé, si elle est utilisée dans le script
- 0 si le script s’est terminé avec succès
Lorsqu’un script est appelé à powershell.exe l’aide du paramètre Command , $LASTEXITCODE est défini sur :
- 1 si le script s’est arrêté en raison d’une exception ou si le résultat de la dernière commande définie $? sur $false
- 0 si le script s’est terminé correctement et que le résultat de la dernière commande définie $? sur $true

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

$Matches

La $Matches variable fonctionne avec les opérateurs et -notmatch les -match opérateurs. Lorsque vous envoyez une entrée scalaire à l’opérateur ou -notmatch à l’opérateur-match, et qu’elle détecte une correspondance, elles retournent une valeur booléenne et remplissent la $Matches variable automatique avec une table de hachage de toutes les valeurs de chaîne qui ont été mises en correspondance. La $Matches table de hachage 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 about_Comparison_Operators. Pour plus d’informations sur les expressions régulières, consultez about_Regular_Expressions.

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

Remarque

Lorsqu’elle $Matches est remplie dans une session, elle conserve la valeur correspondante jusqu’à ce qu’elle soit remplacée par une autre correspondance. Si -match elle est utilisée à nouveau et qu’aucune correspondance n’est trouvée, elle n’est pas reset$Matches à $null. La valeur précédemment correspondante est conservée $Matches jusqu’à ce qu’une autre correspondance soit trouvée.

$MyInvocation

Contient des informations sur la current commande, 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, appelée ou appelée, telle que le nom du script qui a appelé la current commande.

$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 current script, par exemple le nom d’une fonction ($MyInvocation.MyCommand.Name) pour identifier la current commande. Cela est utile pour trouver le nom du current script.

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

PSScriptRoot : contient le chemin complet du script qui a appelé la current commande. La valeur de cette propriété est remplie 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 current commande. La valeur de cette propriété est remplie uniquement lorsque l’appelant est un script.

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

$NestedPromptLevel

Contient le niveau d’invite current . 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é lorsque vous la quittez.

Par exemple, PowerShell présente une invite de commandes imbriquée lorsque vous utilisez la $Host.EnterNestedPrompt méthode. PowerShell présente également une invite de commandes 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 current commande, enregistre le contexte d’exécution et incrémente la valeur de la $NestedPromptLevel variable. 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 $NestedPromptLevel variable vous aide à suivre le niveau d’invite. 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 comme un objet avec une valeur, ou un espace réservé, afin de représenter $null une valeur vide dans une collection de valeurs.

Par exemple, lorsqu’elle $null est incluse dans une collection, elle est comptabilisée comme l’un des objets.

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

Si vous dirigez la variable vers l’applet $null ForEach-Object de commande, 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 aucune valeur de paramètre. Une valeur de paramètre de $null remplacement remplace la valeur de paramètre par défaut.

Toutefois, étant donné que PowerShell traite la $null variable comme un espace réservé, vous pouvez l’utiliser dans des scripts comme ceux suivants, qui ne fonctionnent pas si $null elles ont été ignorées.

$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 current session PowerShell.

$PROFILE

Contient le chemin complet du profil PowerShell pour l’utilisateur current et l’application current hôte. 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 current valeurs. 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 current valeurs des paramètres ou passer des valeurs de paramètre à un autre script ou fonction.

Dans cet exemple, la fonction Test2 transmet la $PSBoundParameters fonction Test1 . Les $PSBoundParameters valeurs sont affichées 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 dynamiquement les paramètres WhatIf et Confirm à l’applet de commande.

Pour plus d’informations sur la $PSCmdlet variable automatique, 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

Contient le nom de la culture actuellement utilisée dans le système d’exploitation. 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 . Permet Get-Culture d’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, elle contient une valeur Null . 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 a des points d’arrêt et des propriétés InvocationInfo. La propriété InvocationInfo a plusieurs propriétés utiles, notamment la propriété Location . La propriété Location indique le chemin d’accès 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, alors que $PSVersionTable ce n’est pas le cas.

$PSHOME

Contient le chemin complet du répertoire d’installation de PowerShell, généralement dans $env:windir\System32\PowerShell\v1.0 les systèmes Windows. Vous pouvez utiliser cette variable dans les chemins d’accès des fichiers PowerShell. Par exemple, la commande suivante recherche les rubriques d’aide conceptuelle pour le mot Aide :

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

$PSItem

Comme pour $_. Contient l’objet current 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, consultez 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 $PSSenderInfo variable inclut une propriété configurable par l’utilisateur, ApplicationArguments, qui, par défaut, contient uniquement la $PSVersionTable session d’origine. Pour ajouter des données à la propriété ApplicationArguments , utilisez le paramètre ApplicationArguments de l’applet New-PSSessionOption de commande.

$PSUICulture

Contient le nom de la culture de l’interface utilisateur configurée dans le système d’exploitation. La culture d'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 Get-UICulture commande.

$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 current session. Le tableau comprend les éléments suivants :

BuildVersion - Numéro de build de la current version
CLRVersion - Version du Common Language Runtime (CLR)
PSCompatibleVersions - Versions de PowerShell compatibles avec la current version
PSEdition - Cette propriété a la valeur « Desktop », pour les versions du client Windows Server et Windows. Cette propriété a la valeur « Core » pour PowerShell exécutée sous Nano Server ou Windows IoT.
PSRemotingProtocolVersion : version du protocole de gestion à distance PowerShell.
PSVersion - Numéro de version PowerShell
SerializationVersion - Version de la méthode de sérialisation
WSManStackVersion - Numéro de version de la pile WS-Management

$PWD

Contient un objet path qui représente le chemin d’accès complet de l’emplacement current du répertoire pour l’espace current d’exécution PowerShell.

Remarque

PowerShell prend en charge plusieurs runspaces par processus. Chaque runspace a son propre current répertoire. Ce n’est pas le même que le current répertoire du processus : [System.Environment]::CurrentDirectory.

$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 Get-Event retourne.

$ShellId

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

$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 Switch instruction. La $switch variable existe uniquement pendant l’exécution de l’instruction Switch ; elle est supprimée lorsque l’instruction termine l’exécution switch . Pour plus d’informations, consultez about_Switch.

$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 blocs de script. Dans un bloc de script 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 $this variable 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 d’événement.

$true

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

Utilisation d’énumérateurs

Les $inputvariables et $switch les $foreachvariables sont tous des énumérateurs utilisés pour itérer dans 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 reset itérer, 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 arrêtent et continuent doivent être préférés.
Dans les fonctions qui acceptent l’entrée de pipeline, il est recommandé d’utiliser des paramètres avec les attributs ValueFromPipeline ou ValueFromPipelineByPropertyName.

Pour plus d’informations, consultez about_Functions_Advanced_Parameters.

MoveNext

La méthode MoveNext avance l’énumérateur vers l’élément suivant de la collection. MoveNext retourne True si l’énumérateur a été correctement avancé, False si l’énumérateur a passé la fin de la collection.

Remarque

La valeur booléenne retournée par MoveNext est envoyée au flux de sortie. Vous pouvez supprimer la sortie en la tapant [void] ou en la pipant vers Out-Null.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

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

Current

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

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

Exemples

Exemple 1 : Utilisation de la variable $input

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

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 $input variable 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 $input variable représente toutes les valeurs redirigées vers la fonction.

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

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 $input.Current propriété

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

La Current propriété n’est jamais remplie, sauf si vous appelez explicitement MoveNext. La Current propriété 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 $input variable, la $foreach variable représente toujours tous les éléments de la collection lorsqu’elle est accessible directement. Utilisez la Current propriété pour accéder à l’élément current de collection et les Reset méthodes MoveNext pour modifier sa valeur.

Remarque

Chaque itération de la foreach boucle appelle automatiquement la méthode MoveNext .

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 itérer dans la collection ($Num).

$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 réinitialise l’élément Reset current dans la collection. L’exemple suivant effectue une boucle dans les deux premiers éléments , car la Reset méthode est appelée. Après les deux premières boucles, l’instruction if échoue et la boucle itère normalement les trois éléments.

Important

Cela peut entraîner une boucle infinie.

$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 $switch variable a exactement les mêmes règles que la $foreach variable. L’exemple suivant illustre tous les concepts d’énumérateur.

Remarque

Notez comment le cas NotEvaluated n’est jamais exécuté, même s’il n’y a pas break d’instruction après la méthode MoveNext .

$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

Partager via

about_Automatic_Variables

Description courte

Description longue

$$

$?

$^

$_

$args

$ConsoleFileName

Error$

$Event

$EventArgs

$EventSubscriber

$ExecutionContext

$false

$foreach

$HOME

$Host

$input

$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

Utilisation d’énumérateurs

MoveNext

Reset

Current

Exemples

Exemple 1 : Utilisation de la variable $input

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

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

Exemple 4 : Utilisation de la variable $foreach

Exemple 5 : Utilisation de la variable $switch

Voir aussi

Ressources supplémentaires