6. Conversiones

Nota editorial

Importante

La Especificación del lenguaje de Windows PowerShell, versión 3.0 se publicó en diciembre de 2012 y está basada en Windows PowerShell 3.0. Esta especificación no refleja el estado actual de PowerShell. No hay ningún plan para actualizar esta documentación para reflejar el estado actual. Esta documentación se presenta aquí para obtener referencia histórica.

El documento de especificación está disponible como un documento de Microsoft Word del Centro de descarga de Microsoft en: https://www.microsoft.com/download/details.aspx?id=36389 Ese documento de Word se ha convertido para su presentación aquí en Microsoft Learn. Durante la conversión, se han realizado algunos cambios editoriales para dar cabida al formato de la plataforma Docs. Se han corregido algunos errores tipográficos y menores.

Una conversión de tipo se realiza cuando se usa un valor de un tipo en un contexto que requiere un tipo diferente. Si esta conversión se produce automáticamente, se conoce como conversión implícita. (Un ejemplo común de esto es con algunos operadores que necesitan convertir uno o varios de los valores designados por sus operandos). Se permite la conversión implícita siempre que se conserve el sentido del valor de origen, como no se pierde la precisión de un número cuando se convierte.

El operador de conversión (sección 7.2.9) permite la conversión explícita.

Las conversiones se describen a continuación, con información complementaria proporcionada según sea necesario en la descripción de cada operador en §6.19.

La conversión explícita de un valor al tipo que ya tiene provoca ningún cambio en ese valor ni en su representación.

Las reglas para entregar la conversión cuando el valor de una expresión se enlaza a un parámetro se tratan en la sección 6.17.

6.1 Conversión a void

Un valor de cualquier tipo se puede descartar explícitamente mediante la conversión a tipo void. No hay ningún resultado.

6.2 Conversión a bool

Las reglas para convertir cualquier valor a tipo bool son las siguientes:

• Un valor numérico o char de cero se convierte en false; un valor numérico o char no igual a cero se convierte en true.
• Un valor de tipo NULL se convierte en False.
• Una cadena de longitud 0 se convierte en False; Una cadena de longitud > 0 se convierte en True.
• Un parámetro switch con valor $true se convierte en True y uno con valor $false se convierte en False.
• Todos los demás valores de tipo de referencia no NULL se convierten en True.

Si el tipo implementa IList:

• Si la longitud del objeto es igual a > 2, el valor se convierte en True.
• Si la longitud del objeto es 1 y ese primer elemento no es en sí mismo un IList, si el valor de ese elemento es true, el valor se convierte en True.
• De lo contrario, si el recuento del primer elemento >= 1, el valor se convierte en True.
• De lo contrario, el valor se convierte en False.

6.3 Conversión a char

Las reglas para convertir cualquier valor en type char son las siguientes:

• La conversión de un valor de tipo bool, decimal, float o double está en error.
• Un valor de tipo NULL se convierte en el carácter NULL (U+0000).
• Valor de tipo entero cuyo valor se puede representar en el tipo char tiene ese valor; De lo contrario, la conversión está en error.
• La conversión de un valor de cadena que tiene una longitud distinta de 1 es errónea.
• Un valor de cadena de longitud 1 se convierte en un carácter con ese mismo valor.
• Valor de tipo numérico cuyo valor después del redondeo de cualquier parte fraccionaria se puede representar en el tipo de destino tiene ese valor redondeado; De lo contrario, la conversión está en error.
• Para otros valores de tipo de referencia, si el tipo de referencia admite dicha conversión, se usa esa conversión; De lo contrario, la conversión está en error.

6.4 Conversión a entero

Las reglas para convertir cualquier valor al tipo byte, int o long son las siguientes:

• El valor bool False se convierte en cero; El valor bool True se convierte en 1.
• Valor de tipo char cuyo valor se puede representar en el tipo de destino tiene ese valor; De lo contrario, la conversión está en error.
• Valor de tipo numérico cuyo valor después del redondeo de cualquier parte fraccionaria se puede representar en el tipo de destino tiene ese valor redondeado; De lo contrario, la conversión está en error.
• Un valor de tipo NULL se convierte en cero.
• Una cadena que representa un número se convierte como se describe en §6.16. Si después del truncamiento de la parte fraccionaria, el resultado se puede representar en el tipo de destino, la cadena está bien formada y tiene el tipo de destino; De lo contrario, la conversión está en error. Si la cadena no representa un número, se producirá un error en la conversión.
• Para otros valores de tipo de referencia, si el tipo de referencia admite dicha conversión, se usa esa conversión; De lo contrario, la conversión está en error.

6.5 Conversión a float y double

Las reglas para convertir cualquier valor en tipo float o double son las siguientes:

• El valor bool False se convierte en cero; El valor bool True se convierte en 1.
• Un valor char se representa exactamente.
• Un valor de tipo numérico se representa exactamente, si es posible; pero para las conversiones int, long y decimal a float y para las conversiones long y decimal a double, se pueden perder algunos de los bits menos significativos del valor entero.
• Un valor de tipo NULL se convierte en cero.
• Una cadena que representa un número se convierte como se describe en §6.16; De lo contrario, la conversión está en error.
• Para otros valores de tipo de referencia, si el tipo de referencia admite dicha conversión, se usa esa conversión; De lo contrario, la conversión está en error.

6.6 Conversión a decimal

Las reglas para convertir cualquier valor en decimal de tipo son las siguientes:

• El valor bool False se convierte en cero; El valor bool True se convierte en 1.
• Un valor de tipo char se representa exactamente.
• Un valor de tipo numérico se representa exactamente; sin embargo, si ese valor es demasiado grande o demasiado pequeño para caber en el tipo de destino, la conversión se produce un error.
• Un valor de tipo NULL se convierte en cero.
• Una cadena que representa un número se convierte como se describe en §6.16; De lo contrario, la conversión está en error.
• Para otros valores de tipo de referencia, si el tipo de referencia admite dicha conversión, se usa esa conversión; De lo contrario, la conversión está en error.
• La escala del resultado de una conversión correcta es tal que la parte fraccionaria no tiene ceros finales.

6.7 Conversión al objeto

El valor de cualquier tipo excepto el tipo NULL (4.1.2) se puede convertir en objeto de tipo. El valor conserva su tipo y representación.

6.8 Conversión a cadena

Las reglas para convertir cualquier valor en cadena de tipo son las siguientes:

• El valor bool $false se convierte en "False"; el valor bool $true se convierte en "True".
• Un valor de tipo char se convierte en una cadena de 1 carácter que contiene ese carácter.
• Un valor de tipo numérico se convierte en una cadena que tiene la forma de un literal numérico correspondiente. Pero el resultado no tiene espacios iniciales o finales, ningún signo más inicial, los enteros tienen base 10 y no hay ningún sufijo de tipo. Para una conversión decimal, se conserva la escala. Para los valores de -∞, +∞ y NaN, las cadenas resultantes son "-Infinity", "Infinity" y "NaN", respectivamente.
• Un valor de tipo NULL se convierte en la cadena vacía.
• Para una matriz dimensional, el resultado es una cadena que contiene el valor de cada elemento de esa matriz, de principio a fin, convertida en cadena, con elementos separados por el separador de campo de salida actual (§2.3.2.2). Para una matriz que tiene elementos que son matrices, solo se convierten los elementos de nivel superior. La cadena utilizada para representar el valor de un elemento que es una matriz depende de la implementación. Para una matriz multidimensional, se aplana (§9.12) y, a continuación, se trata como una matriz 1 dimensional.
• Un valor de tipo NULL se convierte en la cadena vacía.
• Un valor de tipo scriptblock se convierte en una cadena que contiene el texto de ese bloque sin los caracteres { y } delimitadores.
• Para un valor de tipo de enumeración, el resultado es una cadena que contiene el nombre de cada constante de enumeración codificada en ese valor, separada por comas.
• Para otros valores de tipo de referencia, si el tipo de referencia admite dicha conversión, se usa esa conversión; De lo contrario, la conversión está en error.

Cadena usada para representar el valor de un elemento que es una matriz tiene el formato System.Type[], System.Type[,], etc. Para otros tipos de referencia, se llama al método ToString. Para otros tipos enumerables, el valor de origen se trata como una matriz 1 dimensional.

6.9 Conversión a array

Las reglas para convertir cualquier valor en un tipo de matriz son las siguientes:

• Es posible que el tipo de destino no sea una matriz multidimensional.
• El valor de tipo NULL se conserva tal como está.
• Para un valor escalar distinto de $null o un valor de tipo hashtable, se crea una nueva matriz de 1 elemento cuyo valor es el escalar después de la conversión al tipo de elemento de destino.
• Para un valor de matriz 1 dimensional, se crea una nueva matriz del tipo de destino y cada elemento se copia con la conversión de la matriz de origen al elemento correspondiente de la matriz de destino.
• Para un valor de matriz multidimensional, esa matriz se aplana primero (§9.12) y, a continuación, se trata como un valor de matriz 1 dimensional.
• Un valor de cadena se convierte en una matriz de caracteres que tiene la misma longitud, donde cada carácter sucesivo de la cadena ocupa una posición correspondiente en la matriz.

Para otros tipos enumerables, se crea una nueva matriz de 1 elemento cuyo valor es el elemento correspondiente después de la conversión al tipo de elemento de destino, si existe dicha conversión. De lo contrario, la conversión está en error.

6.10 Conversión a xml

El objeto se convierte en cadena de tipo y, a continuación, en un objeto Document XML de tipo xml.

6.11 Conversión a regex

Una expresión que designa un valor de tipo string se puede convertir al tipo regex.

6.12 Conversión a scriptblock

Las reglas para convertir cualquier valor en el tipo scriptblock son las siguientes:

• Un valor de cadena se trata como el nombre de un comando seguido opcionalmente por argumentos para llamar a ese comando.

6.13 Conversión a tipos de enumeración

Las reglas para convertir cualquier valor en un tipo de enumeración son las siguientes:

• Un valor de tipo string que contiene uno de los valores con nombre (teniendo en cuenta mayúsculas y minúsculas) para un tipo de enumeración se convierte en ese valor con nombre.
• Un valor de tipo string que contiene una lista separada por comas de valores con nombre (teniendo en cuenta mayúsculas y minúsculas) para un tipo de enumeración se convierte en el OR bit a bit de todos los valores con nombre.

6.14 Conversión a otros tipos de referencia

Las reglas para convertir cualquier valor en un tipo de referencia distinto de un tipo de matriz o cadena son las siguientes:

• El valor de tipo NULL se conserva tal como está.
• De lo contrario, el comportamiento se define en la implementación.

Aquí entran en juego una serie de piezas de maquinaria. Incluyen el posible uso de constructores de argumento único o constructores predeterminados si el valor es una tabla hash, operadores de conversión implícitos y explícitos, y métodos Parse para el tipo de destino; el uso de Convert.ConvertTo y el mecanismo de conversión de ETS.

6.15 Conversiones aritméticas habituales

Si ninguno de los operandos designa un valor que tiene un tipo numérico,

• Si el operando izquierdo designa un valor de tipo bool, hay un error en la conversión.
• De lo contrario, todos los operandos que designan el valor $null se convierten en cero de tipo int y el proceso continúa con las conversiones numéricas enumeradas a continuación.
• De lo contrario, si el operando izquierdo designa un valor de tipo char y el operando derecho designa un valor de tipo bool, la conversión se produce un error.
• De lo contrario, si el operando izquierdo designa un valor de tipo string pero no representa un número (§6.16), la conversión se produce un error.
• De lo contrario, si el operando derecho designa un valor de tipo string pero no representa un número (§6.16), la conversión se produce un error.
• De lo contrario, todos los operandos que designan valores de cadena de tipo se convierten en números (§6.16) y el proceso continúa con las conversiones numéricas enumeradas a continuación.
• De lo contrario, la conversión está en error.

Conversiones numéricas:

• Si un operando designa un valor de tipo decimal, el valor designado por el otro operando se convierte en ese tipo, si es necesario. El resultado tiene el tipo decimal.
• De lo contrario, si un operando designa un valor de tipo double, el valor designado por el otro operando se convierte en ese tipo, si es necesario. El resultado tiene el tipo double.
• De lo contrario, si un operando designa un valor de tipo float, los valores designados por ambos operandos se convierten en el tipo double, si es necesario. El resultado tiene el tipo double.
• De lo contrario, si un operando designa un valor de tipo long, el valor designado por el otro valor de operando se convierte en ese tipo, si es necesario. El resultado tiene el tipo first en la secuencia long y double que puede representar su valor.
• De lo contrario, los valores designados por ambos operandos se convierten en tipo int, si es necesario. El resultado tiene el tipo first de la secuencia int, long, double que puede representar su valor sin truncamiento.

6.16 Conversión de cadena a tipo numérico

Dependiendo de su contenido, una cadena se puede convertir explícita o implícitamente en un valor numérico. Específicamente

• Una cadena vacía se convierte en el valor cero.
• Los espacios iniciales y finales se omiten; sin embargo, una cadena no puede constar solo de espacios.
• Una cadena que contiene solo espacios en blanco o terminadores de línea se convierte en el valor cero.
• Se permite un signo inicial + o - .
• Un número entero puede tener un prefijo hexadecimal (0x o 0X).
• Se permite un exponente con signo opcional.
• No se permiten sufijos de tipo ni multiplicadores.
• Las cadenas que distinguen mayúsculas de minúsculas "-Infinity", "Infinity" y "NaN" se reconocen como los valores -∞, +∞ y NaN, respectivamente.

6.17 Conversión durante el enlace de parámetros

Para obtener información sobre el enlace de parámetros, consulte §8.14.

Cuando el valor de una expresión se enlaza a un parámetro, hay consideraciones de conversión adicionales, como se describe a continuación:

• Si el tipo de parámetro es switch (§4.2.5, §8.10.5) y el parámetro no tiene ningún argumento, el valor del parámetro en el comando llamado se establece en $true. Si el tipo de parámetro es distinto de switch, se produce un error en un parámetro que no tiene ningún argumento.
• Si el tipo de parámetro es switch y el valor del argumento es $null, el valor del parámetro se establece en $false.
• Si el tipo de parámetro es object o es el mismo que el tipo del argumento, el valor del argumento se pasa sin conversión.
• Si el tipo de parámetro no es object o scriptblock, se evalúa un argumento que tiene el tipo scriptblock y su resultado se pasa como valor del argumento. (Esto se conoce como enlace de bloque de script retrasado). Si el tipo de parámetro es object o scriptblock, un argumento que tiene el tipo scriptblock se pasa tal cual está.
• Si el tipo de parámetro es una colección de tipo T2 y el argumento es escalar de tipo T1, ese escalar se convierte en una colección de tipo T2 que contiene un elemento. Si es necesario, el valor escalar se convierte en el tipo T2 mediante las reglas de conversión de esta sección.
• Si el tipo de parámetro es un tipo escalar distinto de objeto y el argumento es una colección, el argumento es un error.
• Si el tipo de parámetro esperado es una colección de tipo T2 y el argumento es una colección de tipo T1, el argumento se convierte en una colección de tipo T2 que tiene la misma longitud que la colección de argumentos. Si es necesario, los valores del elemento de colección de argumentos se convierten en el tipo T2 mediante las reglas de conversión de esta sección.
• Si los pasos anteriores y las conversiones especificadas anteriormente en este capítulo no son suficientes, se aplican las reglas de §6.18. Si esos fallan, el enlace de parámetros falla.

6.18 Conversión de .NET

Para una conversión implícita, primero se prueban las conversiones integradas de PowerShell. Si no pueden resolver la conversión, se prueban los convertidores personalizados de .NET siguientes, en orden, de arriba a abajo. Si se encuentra una conversión, pero produce una excepción, se ha producido un error en la conversión.

• PSTypeConverter: hay dos maneras de asociar la implementación de la clase PSTypeConverter con su clase de destino: a través del archivo de configuración de tipos (types.ps1xml) o aplicando el atributo System.ComponentModel.TypeConverterAttribute a la clase de destino. Consulte la documentación del SDK de PowerShell para obtener más información.

• TypeConverter: este tipo CLR proporciona una manera unificada de convertir tipos de valores a otros tipos, así como para acceder a valores estándar y subpropiedades. El tipo de convertidor más común es aquel que se convierte en y desde una representación de texto. El convertidor de tipos de una clase está enlazado a la clase con un System.ComponentModel.TypeConverterAttribute. A menos que este atributo se invalide, todas las clases que heredan de esta clase usan el mismo convertidor de tipos que la clase base. Consulte el SDK de PowerShell y la documentación de Microsoft .NET Framework para obtener más información.

• Parse Method: si el tipo de origen es string y el tipo de destino tiene un método denominado Parse, se llama a ese método para realizar la conversión.

• Constructores: si el tipo de destino tiene un constructor que toma un único argumento cuyo tipo es el del tipo de origen, se llama a ese constructor para realizar la conversión.

• Operador de conversión implícita: Si el tipo de origen tiene un operador de conversión implícito que convierte al tipo de destino, se invoca ese operador para realizar la conversión.

• Operador de conversión explícita: Si el tipo de origen tiene un operador de conversión explícito que convierte al tipo de destino, se llama a ese operador para realizar la conversión. Si el tipo de destino dispone de un operador de conversión explícito que convierte desde el tipo de origen, se invoca a dicho operador para realizar la conversión.

• IConvertable: se llama a System.Convert.ChangeType para realizar la conversión.

6.19 Conversión a ordered

Las reglas para convertir cualquier valor en el pseudotipo ordenado son las siguientes:

• Si el valor es un literal hash (§2.3.5.6), el resultado es un objeto con un tipo definido por implementación que se comporta como una tabla hash y el orden de las claves coincide con el orden especificado en el literal hash.
• De lo contrario, el comportamiento se define en la implementación.

Solo los literales hash (sección 2.3.5.6) se pueden convertir en ordered. El resultado es una instancia de System.Collections.Specialized.OrderedDictionary.

6.20 Conversión a pscustomobject

Las reglas para convertir cualquier valor en el pseudotipo pscustomobject son las siguientes:

• Un valor de tipo hashtable se convierte en un objeto de PowerShell. Cada clave de la tabla hash se convierte en noteProperty con el valor correspondiente.
• De lo contrario, el comportamiento se define en la implementación.

La conversión siempre se permite, pero no cambia el tipo del valor.