6. Conversions

Note éditoriale

Important

La spécification du langage Windows PowerShell 3.0 a été publiée en décembre 2012 et est basée sur Windows PowerShell 3.0. Cette spécification ne reflète pas l’état actuel de PowerShell. Il n’existe aucun plan de mise à jour de cette documentation pour refléter l’état actuel. Cette documentation est présentée ici pour référence historique.

Le document de spécification est disponible en tant que document Microsoft Word à partir du Centre de téléchargement Microsoft à l’adresse : https://www.microsoft.com/download/details.aspx?id=36389 ce document Word a été converti pour présentation ici sur Microsoft Learn. Pendant la conversion, certaines modifications éditoriales ont été apportées pour prendre en charge la mise en forme de la plateforme Docs. Certaines fautes de frappe et erreurs mineures ont été corrigées.

Une conversion de type est effectuée lorsqu’une valeur d’un type est utilisée dans un contexte qui nécessite un type différent. Si une telle conversion se produit automatiquement, elle est appelée conversion implicite. (Voici un exemple courant avec certains opérateurs qui doivent convertir une ou plusieurs des valeurs désignées par leurs opérandes.) La conversion implicite est autorisée à condition que la valeur source soit conservée, par exemple aucune perte de précision d’un nombre lorsqu’elle est convertie.

L’opérateur cast (§7.2.9) permet une conversion explicite.

Les conversions sont décrites ci-dessous, avec des informations supplémentaires fournies si nécessaire dans la description de chaque opérateur dans §6.19.

La conversion explicite d’une valeur vers le type qu’elle a déjà ne provoque aucune modification de cette valeur ou de sa représentation.

Les règles de traitement des conversions quand la valeur d’une expression est liée à un paramètre sont couvertes dans la section §6.17.

6.1 Conversion en vide

Une valeur de n’importe quel type peut être ignorée explicitement en la castant en type void. Il n’y a aucun résultat.

6.2 Conversion en bool

Les règles de conversion d’une valeur en type bool sont les suivantes :

• Une valeur numérique ou char de zéro est convertie en False ; une valeur numérique ou char de non-zéro est convertie en True.
• Une valeur de type Null est convertie en False.
• Une chaîne de longueur 0 est convertie en false ; une chaîne de longueur > 0 est convertie en True.
• Un paramètre de commutateur avec la valeur $true est converti en True, et une avec la valeur $false est convertie en False.
• Toutes les autres valeurs de type référence non Null sont converties en True.

Si le type implémente IList :

• Si la longueur de l’objet > 2, la valeur est convertie en True.
• Si la longueur de l’objet est 1 et que le premier élément n’est pas lui-même un IList, si la valeur de cet élément est true, la valeur est convertie en true.
• Sinon, si le Compte >du premier élément est égal à 1, la valeur est convertie en Vrai.
• Sinon, la valeur est convertie en False.

6.3 Conversion en caractères

Les règles de conversion de n’importe quelle valeur en type char sont les suivantes :

• La conversion d’une valeur de type bool, décimal, float ou double est en erreur.
• Une valeur de type Null est convertie en caractère Null (U+0000).
• Valeur de type entier dont la valeur peut être représentée dans le type char a cette valeur ; sinon, la conversion est en erreur.
• La conversion d’une valeur de chaîne ayant une longueur autre que 1 est en erreur.
• Une valeur de chaîne ayant une longueur 1 est convertie en char ayant la valeur d’un caractère.
• Une valeur de type numérique dont la valeur après l'arrondissement d'une partie fractionnaire peut être représentée dans le type de destination a cette valeur arrondie ; sinon, la conversion est erronée.
• Pour d’autres valeurs de type de référence, si le type de référence prend en charge une telle conversion, cette conversion est utilisée ; sinon, la conversion est en erreur.

6.4 Conversion en integer

Les règles de conversion d’une valeur en octets de type, int ou long sont les suivantes :

• La valeur bool False est convertie en zéro ; la valeur bool True est convertie en 1.
• Une valeur de type char qui peut être représentée dans le type de destination garde cette valeur ; sinon, la conversion est erronée.
• Une valeur de type numérique dont la valeur après l'arrondissement d'une partie fractionnaire peut être représentée dans le type de destination a cette valeur arrondie ; sinon, la conversion est erronée.
• Une valeur de type Null est convertie en zéro.
• Chaîne qui représente un nombre est convertie comme décrit dans §6.16. Si, après la troncation de la partie fractionnaire, le résultat peut être représenté dans le type de destination, la chaîne est bien formée et a le type de destination ; sinon, la conversion est en erreur. Si la chaîne ne représente pas un nombre, la conversion est en erreur.
• Pour d’autres valeurs de type de référence, si le type de référence prend en charge une telle conversion, cette conversion est utilisée ; sinon, la conversion est en erreur.

6.5 Conversion en float et double

Les règles de conversion d’une valeur en type float ou double sont les suivantes :

• La valeur bool False est convertie en zéro ; la valeur bool True est convertie en 1.
• Une valeur char est représentée exactement.
• Une valeur de type numérique est représentée exactement, si possible ; toutefois, pour les conversions int, longues et décimales en float, et pour les conversions longues et décimales en double, certains des bits les moins significatifs de la valeur entière peuvent être perdus.
• Une valeur de type Null est convertie en zéro.
• Chaîne qui représente un nombre est convertie comme décrit dans §6.16; sinon, la conversion est en erreur.
• Pour d’autres valeurs de type de référence, si le type de référence prend en charge une telle conversion, cette conversion est utilisée ; sinon, la conversion est en erreur.

6.6 Conversion en décimale

Les règles de conversion d’une valeur en décimale de type sont les suivantes :

• La valeur bool False est convertie en zéro ; la valeur bool True est convertie en 1.
• Une valeur de type char est représentée exactement.
• Une valeur de type numérique est représentée exactement ; toutefois, si cette valeur est trop grande ou trop petite pour s’adapter au type de destination, la conversion est en erreur.
• Une valeur de type Null est convertie en zéro.
• Chaîne qui représente un nombre est convertie comme décrit dans §6.16; sinon, la conversion est en erreur.
• Pour d’autres valeurs de type de référence, si le type de référence prend en charge une telle conversion, cette conversion est utilisée ; sinon, la conversion est en erreur.
• L’échelle du résultat d’une conversion réussie est telle que la partie fractionnaire n’a pas de zéros de fin.

6.7 Conversion en objet

La valeur de n’importe quel type, à l’exception du type Null (4.1.2) peut être convertie en objet de type. La valeur conserve son type et sa représentation.

6.8 Conversion en chaîne

Les règles de conversion d’une valeur en chaîne de type sont les suivantes :

• La valeur bool $false est convertie en « False » ; la valeur bool $true est convertie en « True ».
• Une valeur de type char est convertie en chaîne de 1 caractère contenant ce caractère.
• Une valeur de type numérique est convertie en chaîne ayant la forme d’un littéral numérique correspondant. Toutefois, le résultat n’a pas d’espaces de début ou de fin, pas de signe plus en début, les entiers sont en base 10 et il n’existe aucun suffixe de type. Pour une conversion décimale, l’échelle est conservée. Pour les valeurs de -∞, +∞ et NaN, les chaînes résultantes sont respectivement « -Infinity », « Infinity » et « NaN ».
• Une valeur de type Null est convertie en chaîne vide.
• Pour un tableau 1 dimensionnel, le résultat est une chaîne contenant la valeur de chaque élément de ce tableau, du début à la fin, convertie en chaîne, avec des éléments séparés par le séparateur de champ de sortie actuel (§2.3.2.2). Pour un tableau ayant des éléments qui sont eux-mêmes des tableaux, seuls les éléments de niveau supérieur sont convertis. La chaîne utilisée pour représenter la valeur d’un élément qui est un tableau, est définie par l’implémentation. Pour un tableau multidimensionnel, il est aplatit (§9.12) puis traité comme un tableau 1 dimensionnel.
• Une valeur de type Null est convertie en chaîne vide.
• Une valeur de type scriptblock est convertie en une chaîne contenant le texte de ce bloc, sans les caractères délimitants { et }.
• Pour une valeur de type d’énumération, le résultat est une chaîne contenant le nom de chaque constante d’énumération encodée dans cette valeur, séparée par des virgules.
• Pour d’autres valeurs de type de référence, si le type de référence prend en charge une telle conversion, cette conversion est utilisée ; sinon, la conversion est en erreur.

La chaîne utilisée pour représenter la valeur d’un élément qui est un tableau a la forme System.Type[], System.Type[,], et ainsi de suite. Pour d’autres types de référence, la méthode ToString est appelée. Pour d’autres types énumérables, la valeur source est traitée comme un tableau 1 dimensionnel.

6.9 Conversion en array

Les règles de conversion d’une valeur en type de tableau sont les suivantes :

• Le type cible peut ne pas être un tableau multidimensionnel.
• Une valeur de type Null est conservée telle qu’elle est.
• Pour une valeur scalaire autre que $null ou une valeur de table de hachage de type, un nouveau tableau d’éléments 1 est créé dont la valeur est la scalaire après la conversion vers le type d’élément cible.
• Pour une valeur de tableau 1 dimensionnelle, un nouveau tableau du type cible est créé et chaque élément est copié avec la conversion du tableau source vers l’élément correspondant dans le tableau cible.
• Pour une valeur de tableau multidimensionnelle, ce tableau est d’abord aplatit (§9.12), puis traité comme une valeur de tableau 1 dimensionnée.
• Une valeur de chaîne est convertie en tableau de caractères ayant la même longueur avec des caractères successifs de la chaîne occupant des positions correspondantes dans le tableau.

Pour d’autres types énumérables, un nouveau tableau d’éléments 1 est créé dont la valeur est l’élément correspondant après la conversion vers le type d’élément cible, si une telle conversion existe. Sinon, il y a une erreur de conversion.

6.10 Conversion en xml

L’objet est converti en chaîne de type, puis en objet Document XML de type xml.

6.11 Conversion en regex

Une expression qui désigne une valeur de chaîne de type peut être convertie en type regex.

6.12 Conversion en scriptblock

Les règles de conversion d’une valeur en type scriptblock sont les suivantes :

• Une valeur de chaîne est traitée comme le nom d’une commande éventuellement suivie par les arguments d’un appel à cette commande.

6.13 Conversion en types d’énumération

Les règles de conversion d’une valeur en type d’énumération sont les suivantes :

• Une valeur de chaîne de type qui contient l’une des valeurs nommées (en ce qui concerne le cas) d’un type d’énumération est convertie en cette valeur nommée.
• Une valeur de type string qui contient une liste de valeurs nommées séparées par des virgules (en respectant la casse) pour un type d’énumération est convertie en OR au niveau du bit de toutes ces valeurs nommées.

6.14 Conversion vers d’autres types de référence

Les règles de conversion d’une valeur en type référence autre qu’un type de tableau ou une chaîne sont les suivantes :

• Une valeur de type Null est conservée telle qu’elle est.
• Sinon, le comportement est défini par l'implémentation.

Un certain nombre d'éléments de machinerie entrent en jeu ici ; cela inclut l’utilisation possible de constructeurs avec un unique argument ou de constructeurs par défaut si la valeur est une table de hachage, des opérateurs de conversion implicites et explicites, et des méthodes Parse pour le type cible ; l’utilisation de Convert.ConvertTo ; et le mécanisme de conversion ETS.

6.15 Conversions arithmétiques habituelles

Si aucun opérande ne désigne une valeur ayant un type numérique, alors

• Si l’opérande gauche désigne une valeur de type bool, la conversion est en erreur.
• Sinon, tous les opérandes désignant la valeur $null sont convertis en zéro de type int et le processus continue avec les conversions numériques répertoriées ci-dessous.
• Sinon, si l’opérande gauche désigne une valeur de type char et que l’opérande droit désigne une valeur de type bool, la conversion est en erreur.
• Sinon, si l’opérande gauche désigne une valeur de chaîne de type mais ne représente pas un nombre (§6.16), la conversion est en erreur.
• Sinon, si l’opérande droit désigne une valeur de type chaîne mais ne représente pas un nombre (§6.16), la conversion est erronée.
• Sinon, toutes les opérandes désignant des valeurs de chaîne de type sont converties en nombres (§6.16), et le processus continue avec les conversions numériques répertoriées ci-dessous.
• Sinon, il y a une erreur de conversion.

Conversions numériques :

• Si un opérande désigne une valeur de type décimal, la valeur désignée par l’autre opérande est convertie en ce type, si nécessaire. Le résultat a le type decimal.
• Sinon, si un opérande désigne une valeur de type double, la valeur désignée par l’autre opérande est convertie en ce type, si nécessaire. Le résultat a le type double.
• Sinon, si un opérande désigne une valeur de type float, les valeurs désignées par les deux opérandes sont converties en double de type, si nécessaire. Le résultat a le type double.
• Sinon, si un opérande désigne une valeur de type long, la valeur désignée par l’autre valeur d’opérande est convertie en ce type, si nécessaire. Le résultat a le premier type de la séquence long et double qui peut représenter sa valeur.
• Sinon, les valeurs désignées par les deux opérandes sont converties en type int, si nécessaire. Le résultat a le premier type de la séquence int, long, double qui peut représenter sa valeur sans troncation.

6.16 Conversion de chaîne en type numérique

Selon son contenu, une chaîne peut être convertie explicitement ou implicitement en valeur numérique. Spécifiquement

• Une chaîne vide est convertie en valeur zéro.
• Les espaces de début et de fin sont ignorés ; toutefois, une chaîne peut ne pas comporter d’espaces uniquement.
• Une chaîne contenant uniquement des espaces blancs et/ou des terminateurs de ligne est convertie en valeur zéro.
• Un signe de début + ou - est autorisé.
• Un nombre entier peut avoir un préfixe hexadécimal (0x ou 0X).
• Un exposant éventuellement signé est autorisé.
• Les suffixes de type et les multiplicateurs ne sont pas autorisés.
• Les chaînes à casse distincte « -Infinity », « Infinity » et « NaN » sont reconnues respectivement comme les valeurs -∞, +∞ et NaN.

6.17 Conversion pendant la liaison de paramètre

Pour plus d’informations sur la liaison de paramètres, consultez §8.14.

Lorsque la valeur d’une expression est liée à un paramètre, il existe des considérations de conversion supplémentaires, comme décrit ci-dessous :

• Si le type de paramètre est switch (§4.2.5, §8.10.5) et que le paramètre n’a aucun argument, la valeur du paramètre dans la commande appelée est définie sur $true. Si le type de paramètre est différent du commutateur, un paramètre n’ayant aucun argument n’est en erreur.
• Si le type de paramètre est switch et que la valeur de l’argument est $null, la valeur du paramètre est définie sur $false.
• Si le type de paramètre est objet ou est identique au type de l’argument, la valeur de l’argument est passée sans conversion.
• Si le type de paramètre n’est pas un objet ou un scriptblock, un argument ayant le type scriptblock est évalué et son résultat est passé comme valeur de l’argument. (Il s’agit de la liaison de bloc de script retardée .) Si le type de paramètre est objet ou scriptblock, un argument ayant le type scriptblock est passé tel qu’il est.
• Si le type de paramètre est une collection de type T2 et que l’argument est un scalaire de type T1, ce scalaire est converti en collection de type T2 contenant un élément. Si nécessaire, la valeur scalaire est convertie en type T2 à l’aide des règles de conversion de cette section.
• Si le type de paramètre est un type scalaire autre que l’objet et que l’argument est une collection, l’argument est en erreur.
• Si le type de paramètre attendu est une collection de type T2 et que l’argument est une collection de type T1, l’argument est converti en collection de type T2 ayant la même longueur que la collection d’arguments. Si nécessaire, les valeurs d’élément de collection d’arguments sont converties en type T2 à l’aide des règles de conversion de cette section.
• Si les étapes ci-dessus et les conversions spécifiées précédemment dans ce chapitre ne suffisent pas, les règles de §6.18 sont appliquées. En cas d’échec, la liaison de paramètre échoue.

6.18 Conversion .NET

Pour une conversion implicite, les conversions intégrées de PowerShell sont essayées en premier. S’ils ne peuvent pas résoudre la conversion, les convertisseurs personnalisés .NET ci-dessous sont essayés, dans l’ordre, de haut en bas. Si une conversion est trouvée, mais qu’elle lève une exception, la conversion a échoué.

• PSTypeConverter: il existe deux façons d’associer l’implémentation de la classe PSTypeConverter à sa classe cible : via le fichier de configuration de type (types.ps1xml) ou en appliquant l’attribut System.ComponentModel.TypeConverterAttribute à la classe cible. Pour plus d’informations, reportez-vous à la documentation du Kit de développement logiciel (SDK) PowerShell.

• TypeConverter: ce type CLR offre un moyen unifié de convertir des types de valeurs en d’autres types, ainsi que d’accéder aux valeurs standard et aux sous-propriétés. Le type de convertisseur le plus courant est celui qui se convertit vers et à partir d’une représentation textuelle. Le convertisseur de type d'une classe est associé à la classe avec un System.ComponentModel.TypeConverterAttribute. Sauf si cet attribut est substitué, toutes les classes qui héritent de cette classe utilisent le même convertisseur de type que la classe de base. Pour plus d’informations, reportez-vous au Kit de développement logiciel (SDK) PowerShell et à la documentation de Microsoft .NET Framework.

• méthode Parse: si le type source est chaîne et que le type de destination a une méthode appelée Parse, cette méthode est appelée pour effectuer la conversion.

• constructeurs: si le type de destination a un constructeur prenant un argument unique dont le type est celui du type source, ce constructeur est appelé pour effectuer la conversion.

• opérateur de cast implicite: si le type source a un opérateur de cast implicite qui se convertit en type de destination, cet opérateur est appelé pour effectuer la conversion.

• Opérateur de conversion explicite: Si le type source dispose d'un opérateur de conversion explicite qui convertit vers le type de destination, cet opérateur est appelé pour effectuer la conversion. Si le type de destination a un opérateur de cast explicite qui convertit à partir du type source, cet opérateur est appelé pour effectuer la conversion.

• IConvertable : System.Convert.ChangeType est appelée pour effectuer la conversion.

6.19 Conversion en ordered

Les règles de conversion d’une valeur en pseudo-type ordonné sont les suivantes :

• Si la valeur est un littéral de hachage (§2.3.5.6), le résultat est un objet avec un type défini par l’implémentation qui se comporte comme une table de hachage et l’ordre des clés correspond à l’ordre spécifié dans le littéral de hachage.
• Sinon, le comportement est défini par l'implémentation.

Seuls les littéraux de hachage (§2.3.5.6) peuvent être convertis en ordered. Le résultat est un exemple de System.Collections.Specialized.OrderedDictionary.

6.20 Conversion en pscustomobject

Les règles de conversion d’une valeur en pseudo-type pscustomobject sont les suivantes :

• Une valeur de type table de hachage est convertie en objet PowerShell. Chaque clé de la table de hachage devient noteProperty avec la valeur correspondante.
• Sinon, le comportement est défini par l'implémentation.

La conversion est toujours autorisée, mais ne modifie pas le type de la valeur.