about_Ref

Brève description

Décrit comment créer et utiliser une variable de type référence.

Description longue

Vous pouvez passer des variables à des fonctions par référence ou par valeur. Lorsque vous transmettez une variable par valeur, vous transmettez une copie des données. Lorsque vous passez une variable par référence, vous passez une référence à la valeur d’origine. Cela permet à la fonction de modifier la valeur de la variable qui lui est transmise. Les types de référence sont créés à l’aide de [ref], qui est l’accélérateur de type pour le type [System.Management.Automation.PSReference].

L’objectif principal de [ref] est d’activer la transmission de variables PowerShell par référence aux paramètres de méthode .NET marqués comme ref, outou in. Vous pouvez également définir votre propre fonction PowerShell qui prend [ref] paramètres de type. Dans cette utilisation, [ref] est appliquée à une variable , et l’instance de [ref] résultante peut être utilisée pour modifier indirectement la valeur de cette variable.

Dans l’exemple suivant, la fonction modifie la valeur de la variable qui lui est passée. Dans PowerShell, les entiers sont des types valeur afin qu’ils soient passés par valeur. Par conséquent, la valeur de $var n’est pas modifiée en dehors de l’étendue de la fonction.

Function Test($Data)
{
    $Data = 3
}

$var = 10
Test -Data $var
$var

10

Dans l’exemple suivant, une variable contenant un Hashtable est passée à une fonction. Hashtable est un type d’objet. Par défaut, il est passé à la fonction par référence.

Lors de la transmission d’une variable par référence, la fonction peut modifier les données et cette modification persiste après l’exécution de la fonction.

Function Test($Data)
{
    $Data.Test = "New Text"
}

$var = @{}
Test -Data $var
$var

Name                           Value
----                           -----
Test                           New Text

La fonction ajoute une nouvelle paire clé-valeur qui persiste en dehors de l’étendue de la fonction.

Écriture de fonctions pour accepter les paramètres de référence

Vous pouvez coder vos fonctions pour prendre un paramètre comme référence, quel que soit le type de données transmis. Cela nécessite que vous spécifiiez le type de paramètres comme [ref].

Lorsque vous utilisez des références, vous devez utiliser la propriété Value du type [ref] pour accéder à vos données.

function Test {
    param([ref]$Data)
    $Data.Value = 3
}

Pour passer une variable à un paramètre qui attend une référence, vous devez taper caster votre variable en tant que référence.

Important

Les crochets et parenthèses sont obligatoires.

$var = 10
Test -Data ([ref]$var)
$var

3

Passage de références à des méthodes .NET

Certaines méthodes .NET peuvent nécessiter que vous transmettiez une variable en tant que référence. Lorsque la définition de la méthode utilise les mots clés in, outou ref sur un paramètre, elle attend une référence.

[int] | Get-Member -Static -Name TryParse

Name     MemberType Definition
----     ---------- ----------
TryParse Method     static bool TryParse(string s, [ref] int result)

La méthode TryParse tente d’analyser une chaîne sous la forme d’un entier. Si la méthode réussit, elle retourne $true, et le résultat est stocké dans la variable que vous avez passée par référence.

PS> $number = 0
PS> [int]::TryParse("15", ([ref]$number))
True
PS> $number
15

Références et étendues

Les références permettent de modifier la valeur d’une variable dans l’étendue parente dans une étendue enfant.

# Create a value type variable.
$i = 0
# Create a reference type variable.
$iRef = [ref]0
# Invoke a scriptblock to attempt to change both values.
&{$i++;$iRef.Value++}
# Output the results.
"`$i = $i;`$iRef = $($iRef.Value)"

$i = 0;$iRef = 1

Seule la variable du type référence a été modifiée.

Utilisation [ref] en tant que titulaire d’objets à usage général

Vous pouvez également utiliser [ref] comme titulaire d’objets à usage général. Dans cette utilisation, [ref] est appliquée à une valeur au lieu d’une variable. En règle générale, la valeur est une instance d’un type valeur , comme un nombre. Dans la plupart des scénarios, vous pouvez utiliser une variable ou un paramètre standard à la place. Toutefois, cette technique est utile dans les scénarios où le passage d’un titulaire de valeur explicite n’est pas souhaité (pour la concision) ou non possible, comme dans les valeurs de paramètre de bloc de script.

Par exemple, vous pouvez utiliser des valeurs de paramètre de bloc de script pour calculer la valeur de paramètre NewName de l’applet de commande Rename-Item. L’applet de commande Rename-Item vous permet de diriger les éléments vers celui-ci. La commande exécute le scriptblock passé à NewName pour chaque élément du pipeline. Le scriptblock s’exécute dans une étendue enfant. La modification d’une variable dans l’étendue de l’appelant directement ne vous aidera pas et vous ne pouvez pas passer d’arguments au scriptblock dans ce contexte.

Dans cet exemple, le scriptblock passé au paramètre NewName incrémente la valeur de $iRef chaque élément du pipeline. Le scriptblock crée un nouveau nom en ajoutant un nombre au début du nom de fichier.

$iRef = [ref] 0
Get-ChildItem -File $setPath |
    Rename-Item -NewName { '{0} - {1}' -f $iRef.Value++,$_.Name }

Différence entre [ref] et [System.Management.Automation.PSReference]

Une variable de type référence est créée à l’aide de l’accélérateur de type [ref] ou en spécifiant directement le type [System.Management.Automation.PSReference]. Même si [ref] est un accélérateur de type pour [System.Management.Automation.PSReference], ils se comportent différemment.

  • Lorsque vous utilisez [ref] pour convertir une variable, PowerShell crée un objet de référence qui contient une référence à l’instance d’origine de la variable.
  • Lorsque vous utilisez [System.Management.Automation.PSReference] pour convertir une variable, PowerShell crée un objet de référence qui contient une copie de la variable, plutôt qu’une référence à l’instance d’origine.

Par exemple, le script suivant crée une variable $x et deux objets de référence.

PS> $int = 1
PS> $aRef = [ref] $int
PS> $bRef = [System.Management.Automation.PSReference] $int
PS> $int
1
PS> $aRef, $bRef

Value
-----
    1
    1

À ce stade, les deux objets de référence ont la même valeur que $int. En ajoutant différentes valeurs aux objets de référence, nous pouvons voir que $aRef, qui a été créé à l’aide de [ref], est une référence à l’instance d’origine de $int. $bRef, qui a été créé à l’aide de [System.Management.Automation.PSReference], est une copie de la variable.

PS> $aRef.Value+=2
PS> $bRef.Value+=5
PS> $int
3
PS> $aRef, $bRef

Value
-----
    3
    6

Voir aussi

  • Last updated on