ConvertFrom-StringData

Módulo:

Microsoft.PowerShell.Utility

Convierte una cadena que contiene uno o más par clave-valor en una tabla hash.

Syntax

ConvertFrom-StringData
                [-StringData] <String>
                [[-Delimiter] <Char>]
                [<CommonParameters>]

Description

El ConvertFrom-StringData cmdlet convierte una cadena que contiene uno o varios pares clave y valor en una tabla hash. Dado que cada par clave-valor debe estar en una línea independiente, las cadenas here se suelen usar como formato de entrada. De forma predeterminada, la clave debe estar separada del valor por un carácter de signo igual (=).

El ConvertFrom-StringData cmdlet se considera un cmdlet seguro que se puede usar en la sección DATA de un script o una función. Cuando se usa en una sección DATA , el contenido de la cadena debe cumplir las reglas de una sección DATA . Para obtener más información, consulte about_Data_Sections.

ConvertFrom-StringData admite secuencias de caracteres de escape permitidas por las herramientas convencionales de traducción automática. Es decir, el cmdlet puede interpretar barras diagonales inversas (\) como caracteres de escape en los datos de cadena mediante el método Regex.Unescape, en lugar del carácter de barra diagonal inversa de PowerShell (`) que normalmente indicaría el final de una línea en un script. Dentro de la cadena de tipo "here-string", el carácter de tilde aguda no funciona. También puede conservar una barra diagonal inversa literal en los resultados escapándola con una barra diagonal inversa anterior, como esta: \\. Los caracteres de barra diagonal inversa sin escape, como los que suelen usarse en las rutas de acceso de archivos, pueden mostrarse como secuencias de escape no válidas en los resultados.

PowerShell 7 agrega el parámetro Delimiter .

Ejemplos

Ejemplo 1: Convertir una cadena aquí entre comillas únicas en una tabla hash

En este ejemplo se convierte una cadena de mensajes de usuario entre comillas únicas en una tabla hash. En una cadena entre comillas simples, los valores no se sustituyen por variables y las expresiones no se evalúan. El ConvertFrom-StringData cmdlet convierte el valor de la $Here variable en una tabla hash.

$Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
ConvertFrom-StringData -StringData $Here

Name                           Value
----                           -----
Msg3                           The specified variable does not exist.
Msg2                           Credentials are required for this command.
Msg1                           The string parameter is required.

Ejemplo 2: Conversión de datos de cadena mediante un delimitador diferente

En este ejemplo se muestra cómo convertir datos de cadena que usan un carácter diferente como delimitador. En este ejemplo, los datos de cadena usan el carácter de barra vertical (|) como delimitador.

$StringData = @'
color|red
model|coupe
year|1965
condition|mint
'@
$carData = ConvertFrom-StringData -StringData $StringData -Delimiter '|'
$carData

Name                           Value
----                           -----
condition                      mint
model                          coupe
color                          red
year                           1965

Ejemplo 3: Convertir una cadena aquí que contiene un comentario

En este ejemplo se convierte una cadena aquí que contiene un comentario y varios pares clave-valor en una tabla hash.

ConvertFrom-StringData -StringData @'
Name = Disks.ps1

# Category is optional.

Category = Storage
Cost = Free
'@

Name                           Value
----                           -----
Cost                           Free
Category                       Storage
Name                           Disks.ps1

El valor del parámetro StringData es una cadena aquí, en lugar de una variable que contiene una cadena aquí. Cualquier formato es válido. La cadena de tipo "here-string" incluye un comentario sobre una de las cadenas. ConvertFrom-StringData omite los comentarios de una sola línea, pero el # carácter debe ser el primer carácter que no sea de espacio en blanco en la línea. Todos los caracteres de la línea después # de se omiten.

Ejemplo 4: Convertir una cadena en una tabla hash

En este ejemplo se convierte una cadena normal entre comillas dobles (no una cadena here-string) en una tabla hash y la guarda en la $A variable .

$A = ConvertFrom-StringData -StringData "Top = Red `n Bottom = Blue"
$A

Name             Value
----             -----
Bottom           Blue
Top              Red

Para satisfacer la condición de que cada par clave-valor debe estar en una línea independiente, la cadena usa el carácter de nueva línea de PowerShell (`n) para separar los pares.

Ejemplo 5: Uso de ConvertFrom-StringData en la sección DATA de un script

En este ejemplo se muestra un ConvertFrom-StringData comando usado en la sección DATA de un script. Las instrucciones debajo de la sección DATA muestran el texto al usuario.

$TextMsgs = DATA {
ConvertFrom-StringData @'
Text001 = The $Notebook variable contains the name of the user's system notebook.
Text002 = The $MyNotebook variable contains the name of the user's private notebook.
'@
}
$TextMsgs

Name             Value
----             -----
Text001          The $Notebook variable contains the name of the user's system notebook.
Text002          The $MyNotebook variable contains the name of the user's private notebook.

Dado que el texto incluye nombres de variables, debe incluirse en una cadena entre comillas simples para que las variables se interpreten literalmente y no se expandan. Las variables no se permiten en la sección DATA .

Ejemplo 6: Uso del operador de canalización para pasar una cadena

En este ejemplo se muestra que puede usar un operador de canalización (|) para enviar una cadena a ConvertFrom-StringData. El valor de la $Here variable se canaliza a ConvertFrom-StringData y el resultado de la $Hash variable.

$Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
$Hash = $Here | ConvertFrom-StringData
$Hash

Name     Value
----     -----
Msg3     The specified variable does not exist.
Msg2     Credentials are required for this command.
Msg1     The string parameter is required.

Ejemplo 7: Usar caracteres de escape para agregar nuevas líneas y devolver caracteres

En este ejemplo se muestra el uso de caracteres de escape para crear nuevas líneas y devolver caracteres en los datos de origen. La secuencia \n de escape se usa para crear nuevas líneas dentro de un bloque de texto asociado a un nombre o elemento de la tabla hash resultante.

ConvertFrom-StringData @"
Vincentio = Heaven doth with us as we with torches do,\nNot light them for themselves; for if our virtues\nDid not go forth of us, 'twere all alike\nAs if we had them not.
Angelo = Let there be some more test made of my metal,\nBefore so noble and so great a figure\nBe stamp'd upon it.
"@ | Format-List

Name  : Angelo
Value : Let there be some more test made of my metal,
        Before so noble and so great a figure
        Be stamp'd upon it.

Name  : Vincentio
Value : Heaven doth with us as we with torches do,
        Not light them for themselves; for if our virtues
        Did not go forth of us, 'twere all alike
        As if we had them not.

Ejemplo 8: Usar el carácter de escape de barra diagonal inversa para representar correctamente una ruta de acceso de archivo

En este ejemplo se muestra cómo usar el carácter de escape de barra diagonal inversa en los datos de cadena para permitir que una ruta de acceso de archivo se represente correctamente en la tabla hash resultante ConvertFrom-StringData . La barra diagonal inversa doble garantiza que los caracteres de barra diagonal inversa literal se representen correctamente en los resultados de la tabla hash.

ConvertFrom-StringData "Message=Look in c:\\Windows\\System32"

Name                           Value
----                           -----
Message                        Look in c:\Windows\System32

Parámetros

-Delimiter

Carácter utilizado para separar la clave de los datos de valor de la cadena que se va a convertir. El delimitador predeterminado es el carácter de signo igual (=). Este parámetro se agregó en PowerShell 7.

Type:	Char
Position:	1
Default value:	'='
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StringData

Especifica la cadena que se va a convertir. Puede usar este parámetro o canalizar una cadena a ConvertFrom-StringData. El nombre de parámetro es opcional.

El valor de este parámetro debe ser una cadena que contenga uno o varios pares clave-valor. Cada par clave-valor debe estar en una línea independiente, o cada par debe estar separado por caracteres de nueva línea (`n).

Puede incluir comentarios en la cadena, pero los comentarios no pueden estar en la misma línea que un par clave-valor. ConvertFrom-StringData omite los comentarios de una sola línea. El # carácter debe ser el primer carácter que no sea de espacio en blanco en la línea. Todos los caracteres de la línea después # de se omiten. Los comentarios no se incluyen en la tabla hash.

Una cadena aquí es una cadena que consta de una o varias líneas. Las comillas dentro de la cadena aquí se interpretan literalmente como parte de los datos de cadena. Para obtener más información, consulte about_Quoting_Rules.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

Entradas

String

Puede canalizar una cadena que contiene un par clave-valor a este cmdlet.

Salidas

Hashtable

Este cmdlet devuelve una tabla hash que crea a partir de los pares clave-valor.

Notas

Una cadena de tipo "here-string" es una cadena que consta de una o varias líneas en las que las comillas se interpretan literalmente.

Este cmdlet puede ser útil en scripts que muestran mensajes de usuario en varios idiomas hablados. Puede usar las tablas hash de estilo diccionario para aislar las cadenas de texto del código, como en los archivos de recursos, y para dar formato a las cadenas de texto para usarlas en herramientas de traducción.