about_Automatic_Variables

Description courte

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

Description longue

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

Voici une liste des variables automatiques dans PowerShell :

$$

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 la valeur true si la dernière commande a réussi et false si elle a échoué.

Pour les applets de commande et les fonctions avancées qui sont exécutées à plusieurs étapes dans un pipeline, par exemple dans les process end blocs et, l’appel de this.WriteError() ou, respectivement, $PSCmdlet.WriteError() à n’importe quel point, est défini $? sur false, comme c’est le cas this.ThrowTerminatingError() et $PSCmdlet.ThrowTerminatingError() .

L' Write-Error applet de commande affecte 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"
    $? # $false
}

Test-WriteError
$? # $true

Dans ce dernier cas, $PSCmdlet.WriteError() doit être utilisé à la place.

Pour les commandes natives (exécutables), a la valeur $? true lorsque a la valeur $LASTEXITCODE 0, et la valeur false lorsque $LASTEXITCODE est une autre valeur.

Notes

Jusqu’à PowerShell 7, contenant une instruction dans les parenthèses, la syntaxe de sous-expression (...) ou l’expression de tableau est $(...) @(...) toujours réinitialisée $? à true, de sorte que (Write-Error) affiche la $? valeur true. Cela a été modifié dans PowerShell 7, afin de $? refléter toujours la réussite réelle de la dernière commande exécutée dans ces expressions.

$^

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

$_

Comme pour $PSItem. Contient l’objet actuel dans l’objet de pipeline. Vous pouvez utiliser cette variable dans les commandes qui exécutent une action sur chaque objet ou sur les objets sélectionnés dans un pipeline.

$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 à l’aide du param mot clé ou en ajoutant une liste de paramètres séparés par des virgules 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énement. La valeur de cette variable peut également être trouvée dans la propriété SourceArgs de l’objet PSEventArgs Get-Event retourné par.

$ConsoleFileName

Contient le chemin d’accès du fichier de console ( .psc1 ) qui a été le plus récemment utilisé dans la session. Cette variable est remplie lorsque vous démarrez PowerShell à l’aide du paramètre PSConsoleFile ou lorsque vous utilisez l' Export-Console applet de commande pour exporter des noms de composant logiciel enfichable vers un fichier de console.

Lorsque vous utilisez l' Export-Console applet de commande sans paramètres, elle met à jour automatiquement le fichier de console qui a été utilisé le plus récemment dans la session. Vous pouvez utiliser cette variable automatique pour déterminer le fichier qui sera mis à 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 éviter qu’une erreur ne soit ajoutée au $Error tableau, utilisez le paramètre commun ErrorAction avec la valeur ignore. Pour plus d’informations, consultez about_CommonParameters.

$ErrorView

Contient la valeur contrôlant la vue dans laquelle les erreurs sont affichées. La $ErrorView variable accepte des chaînes ou des objets ErrorView et a une valeur par défaut de ConciseView . Si une chaîne autre qu’une valeur acceptée est définie, une erreur est générée.

Valeurs acceptées :

  • CategoryView -Affiche uniquement les informations de catégorie d’erreur.
  • ConciseView -Affiche uniquement le message d’erreur. Si l’erreur est une erreur de l’analyseur ou provient d’un script, un pointeur d’emplacement est inclus. Cette vue a été ajoutée dans PowerShell 7,0
  • NormalView -Fournit un affichage des erreurs PowerShell standard contenant le message d’erreur, l’emplacement, les informations de catégorie, etc.

$Event

Contient un objet PSEventArgs 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énement, telle que Register-ObjectEvent . La valeur de cette variable est le même que celui retourné par l’applet de commande Get-Event . Par conséquent, 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 de 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énement. La valeur de cette variable peut également être trouvée dans la propriété SourceEventArgs de l’objet PSEventArgs Get-Event retourné par.

$EventSubscriber

Contient un objet PSEventSubscriber 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énement. La valeur de cette variable est le même 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 qui sont disponibles pour les applets de commande.

$false

Contient la valeur false. Vous pouvez utiliser cette variable pour représenter la valeur 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 une chaîne non vide ou en un entier différent de zéro.

$foreach

Contient l’énumérateur (pas les valeurs résultantes) d’une boucle foreach . La $ForEach variable existe uniquement pendant l' ForEach exécution de la 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 boucle actuelle. Pour plus d’informations, consultez utilisation d’énumérateurs.

$HOME

Contient le chemin d’accès complet du répertoire de destination de l’utilisateur. cette variable est l’équivalent des "$env:homedrive$env:homepath" variables d’environnement Windows, en général C:\Users\<UserName> .

$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.setbackgroundcolor("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 et les blocs de script (qui sont des fonctions sans nom).

  • Dans une fonction sans Begin bloc, Process ou End , 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 qui se trouve actuellement dans le pipeline.

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

    Notes

    Vous ne pouvez pas utiliser la $input variable à la fois dans le bloc de processus et dans le bloc de fin dans la même fonction ou le même bloc de script.

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

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 utilisation d’énumérateurs.

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

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

$IsCoreCLR

Contient $True si la session active est en cours d’exécution sur le Runtime .net Core (CoreCLR). Sinon, contient $False .

$IsLinux

Contient $True si la session active est exécutée sur un système d’exploitation Linux. Sinon, contient $False .

$IsMacOS

Contient $True si la session active est exécutée sur un système d’exploitation MacOS. Sinon, contient $False .

$IsWindows

contient $TRUE si la session active est exécutée sur un système d’exploitation Windows. Sinon, contient $FALSE .

$LastExitCode

Contient le code de sortie du dernier programme natif qui a été exécuté.

$Matches

La $Matches variable fonctionne avec les -match -notmatch opérateurs et. Lorsque vous envoyez une entrée scalaire à l' -match opérateur or et que l’une d’elles -notmatch détecte une correspondance, elle retourne une valeur booléenne et remplit 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' -match opérateur.

Pour plus d’informations sur l' -match opérateur, 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. Elle est remplie de la même façon que -match les -notmatch opérateurs et. Pour plus d’informations sur l' switch instruction, consultez about_Switch.

Notes

Lorsque $Matches est renseigné dans une session, il conserve la valeur correspondante jusqu’à ce qu’il soit remplacé par une autre correspondance. Si -match est réutilisé et qu’aucune correspondance n’est trouvée, il ne rétablit pas la $Matches valeur $null . La valeur précédemment mise en correspondance est conservée $Matches jusqu’à ce qu’une autre correspondance soit trouvée.

$MyInvocation

Contient des informations sur la commande actuelle, telles que le nom, les paramètres, les valeurs de paramètre et les informations sur la façon dont la commande a été démarrée, appelée ou appelée, comme 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, comme le chemin d’accès et le nom de fichier du script ( $MyInvocation.MyCommand.Path ) ou le nom d’une fonction ( $MyInvocation.MyCommand.Name ) pour identifier la commande actuelle. Cela s’avère particulièrement utile pour rechercher le nom du script actuel.

À compter de PowerShell 3,0, MyInvocation possède 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 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 commande actuelle. La valeur de cette propriété est remplie uniquement lorsque l’appelant est un script.

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

$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é 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 commande active, 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 pour revenir à l’invite de commandes d’origine, exécutez 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 incluant cette valeur afin qu’elle soit toujours visible.

$null

$null 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, autrement dit comme un espace réservé explicite, afin que vous puissiez utiliser $null pour représenter une valeur vide dans une série 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 $null variable vers l’applet de commande ForEach-Object , elle génère une valeur pour $null , comme c’est le cas 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' aucune valeur de paramètre n' est utilisée. Une valeur de paramètre de $null 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 celui qui suit, ce qui ne fonctionnerait $null pas si a été 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 active.

$PROFILE

Contient le chemin d’accès 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

Ou vous pouvez 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 qui sont passés à un script ou une fonction et leurs valeurs actuelles. Cette variable a une valeur uniquement dans une portée où les paramètres sont déclarés, comme un script ou une fonction. Vous pouvez l’utiliser pour afficher ou modifier les valeurs actuelles des paramètres ou pour passer des valeurs de paramètres à un autre script ou à une autre fonction.

Dans cet exemple, la fonction Test2 passe $PSBoundParameters à la fonction Test1 . Les $PSBoundParameters sont affichés dans le format de la clé et de la 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 les méthodes de l’objet dans votre applet de commande ou code de fonction pour répondre aux conditions d’utilisation. Par exemple, la propriété ParameterSetName contient le nom du jeu de paramètres en cours d’utilisation, et la méthode ShouldProcess ajoute les paramètres WhatIf et Confirm à l’applet de commande de manière dynamique.

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

À compter de PowerShell 7, $PSCulture reflète la culture de l’instance d’exécution PowerShell actuelle (session). Si la culture est modifiée dans une instance d’exécution PowerShell, la $PSCulture valeur de cette instance d’exécution est mise à jour.

La culture détermine le format d’affichage des éléments, tels que les nombres, les devises 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. Dans le cas contraire, elle contient une valeur null . Par conséquent, vous pouvez l’utiliser pour indiquer si le débogueur 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 possède 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.

$PSHOME

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

Select-String -Pattern Variable -Path $pshome\*.txt

$PSItem

Comme pour $_. Contient l’objet actuel dans l’objet de pipeline. Vous pouvez utiliser cette variable dans les commandes qui exécutent une action sur chaque objet ou sur les objets sélectionnés dans un pipeline.

$PSScriptRoot

Contient le chemin d’accès 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é la session PSSession, y compris l’identité de l’utilisateur et le fuseau horaire de l’ordinateur d’origine. Cette variable est disponible uniquement dans sessions PSSession.

La $PSSenderInfo variable inclut une propriété configurable par l’utilisateur, ApplicationArguments, qui, par défaut, contient uniquement le $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 qui est actuellement utilisé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 System. Globalization. CultureInfo. Current Propriété UICulture.Name du système. Pour obtenir l’objet System. Globalization. CultureInfo du système, utilisez l' Get-UICulture applet de 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 session active. Le tableau comprend les éléments suivants :

  • Psversion : numéro de version de PowerShell
  • PSEdition cette propriété a la valeur « Desktop » pour powershell 4 et versions antérieures, ainsi que powershell 5,1 sur les éditions complètes de Windows. cette propriété a la valeur de Core pour powershell 6 et versions ultérieures, ainsi que powershell powershell 5,1 sur les éditions à encombrement réduit, comme Windows Nano Server ou Windows IoT.
  • GitCommitId : ID de validation des fichiers sources, en GitHub,
  • OS -Description du système d’exploitation sur lequel PowerShell s’exécute.
  • Plateforme plate -forme sur laquelle le système d’exploitation s’exécute. La valeur sur Linux et macOS est UNIX. Localisez $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 de WS-Management

$PWD

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

Notes

PowerShell prend en charge plusieurs instances d’exécution par processus. Chaque instance d’exécution a son propre répertoire actif. Ce n’est pas le même que le répertoire actif 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 d’action d’une commande d’inscription d’événement. La valeur de cette variable peut également se trouver dans la propriété sender de l’objet PSEventArgs qui Get-Event retourne.

$ShellId

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

$StackTrace

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

$switch

Contient l’énumérateur qui ne correspond pas aux valeurs résultantes d’une Switch instruction. La $switch variable existe uniquement lorsque l' Switch instruction est en cours d’exécution ; elle est supprimée à la fin de l’exécution de l' switch instruction. Pour plus d’informations, consultez 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 utilisation d’énumérateurs.

$this

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 à l’objet qui est étendu.

Dans une classe personnalisée, la $this variable fait référence à l’objet de classe lui-même autorisant l’accès aux propriétés et méthodes définies dans la classe.

$true

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

Utilisation d’énumérateurs

Les $input $foreach variables, et $switch sont tous des énumérateurs utilisés pour itérer au sein des valeurs traitées par leur bloc de code conteneur.

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

  • Dans les boucles, les mots clés de contrôle de workflow break et continue 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 à l’élément suivant de la collection. MoveNext retourne True si l’énumérateur a été avancé avec succès, False si l’énumérateur a dépassé la fin de la collection.

Notes

La valeur booléenne retournée par MoveNext est envoyée au flux de sortie. Vous pouvez supprimer la sortie en la cast ou en la [void] canalisant vers out-NULL.

$input.MoveNext() | Out-Null
[void]$input.MoveNext()

Reset

La Reset méthode affecte à l’énumérateur sa position initiale, qui précède le premier élément de la collection.

Current

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

La Current propriété continue à 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 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 $input variable même si vous n’y 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 Process

En dehors du bloc de processus $input , la variable représente toutes les valeurs redirigées dans 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 la valeur 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 l' $input.Current propriété

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

La Current propriété ne sera jamais remplie, sauf si vous appelez explicitement MoveNext. La Current propriété est accessible plusieurs fois dans le 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 $input à la variable, la $foreach variable représente toujours tous les éléments de la collection lorsque vous y accédez directement. Utilisez la Current propriété pour accéder à l’élément de collection actuel, et les Reset méthodes MoveNext pour modifier sa valeur.

Notes

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

La boucle suivante s’exécute deux fois seulement. 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 aucune valeur à itérer, et la boucle se termine.

La propriété MoveNext n’affecte pas la variable choisie pour itérer au sein de 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 has not changed: $num"
    }
}
Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num has not changed: two

L’utilisation de la Reset méthode réinitialise l’élément actuel dans la collection. L’exemple suivant effectue une boucle à deux reprises sur les deux premiers éléments, car la Reset méthode est appelée. Après les deux premières boucles, l' if instruction échoue et la boucle itère les trois éléments normalement.

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() | Out-Null
        ("`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 de l’énumérateur.

Notes

Notez que le cas NotEvaluated n’est jamais exécuté, même s’il n’y a pas d' break 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

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