ConvertFrom-StringData

Referência

Módulo:: Microsoft.PowerShell.Utility

Converte uma cadeia de caracteres que contém um ou mais pares de chave/valor em uma tabela de hash.

Syntax

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

Description

O ConvertFrom-StringData cmdlet converte uma cadeia de caracteres que contém um ou mais pares de chave e valor em uma tabela de hash. Como cada par chave-valor deve estar em uma linha separada, as cadeias de caracteres aqui geralmente são usadas como o formato de entrada. Por padrão, a chave deve ser separada do valor por um caractere de sinal de igual (=).

O ConvertFrom-StringData cmdlet é considerado um cmdlet seguro que pode ser usado na DATA seção de um script ou função. Quando usado em uma DATA seção, o conteúdo da cadeia de caracteres deve estar em conformidade com as regras de uma seção DATA. Para obter mais informações, consulte about_Data_Sections.

ConvertFrom-StringData dá suporte a sequências de caracteres de escape permitidas pelas ferramentas convencionais de tradução automática. Ou seja, o cmdlet pode interpretar backslashes (\) como caracteres de escape nos dados de cadeia de caracteres usando o Método Regex.Unescape, em vez do caractere de backtick do PowerShell (') que normalmente sinalizaria o fim de uma linha em um script. Dentro da cadeia de caracteres here, o caractere de acento grave não funciona. Você também pode preservar uma barra invertida literal em seus resultados escapando-a com uma barra invertida anterior, como esta: \\. Caracteres de barra invertida sem escape, como aqueles que geralmente são usados em caminhos de arquivo, podem ser processados como sequências de escape ilegais em seus resultados.

Exemplos

Exemplo 1: Converter uma cadeia de caracteres aqui entre aspas única em uma tabela de hash

Este exemplo converte uma cadeia de caracteres aqui de aspas única de mensagens de usuário em uma tabela de hash. Em uma cadeia de caracteres entre aspas simples, os valores não são substituídos por variáveis e as expressões não são avaliadas. O ConvertFrom-StringData cmdlet converte o valor na variável em $Here uma tabela de 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.

Exemplo 2: Converter uma cadeia de caracteres aqui que contém um comentário

Este exemplo converte uma cadeia de caracteres aqui que contém um comentário e vários pares chave-valor em uma tabela de hash.

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

# Category is optional.

Category = Storage
Cost = Free
'@

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

O valor do parâmetro StringData é uma cadeia de caracteres aqui, em vez de uma variável que contém uma cadeia de caracteres aqui. Qualquer um dos dois formatos é válido. A cadeia de caracteres here inclui um comentário sobre uma das cadeias de caracteres. ConvertFrom-StringData ignora comentários de linha única, mas o # caractere deve ser o primeiro caractere não whitespace na linha. Todos os caracteres na linha depois de # ignorados.

Exemplo 3: Converter uma cadeia de caracteres em uma tabela de hash

Este exemplo converte uma cadeia de caracteres com aspas duplas regulares (não uma cadeia de caracteres aqui) em uma tabela de hash e a salva na $A variável.

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

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

Para atender à condição de que cada par chave-valor deve estar em uma linha separada, a cadeia de caracteres usa o caractere newline do PowerShell ('n) para separar os pares.

Exemplo 4: Usar ConvertFrom-StringData na seção DATA de um script

Este exemplo mostra um ConvertFrom-StringData comando usado na seção DATA de um script. As instruções abaixo da seção DATA exibem o texto para o usuário.

$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.

Já que o texto inclui nomes de variáveis, ele deve ser colocado em uma cadeia de caracteres entre aspas simples, de modo que as variáveis sejam interpretadas literalmente e não expandidas. As variáveis não são permitidas na seção DATA .

Exemplo 5: Usar o operador de pipeline para passar uma cadeia de caracteres

Este exemplo mostra que você pode usar um operador de pipeline (|) para enviar uma cadeia de caracteres para ConvertFrom-StringData. O valor da $Here variável é canalizado ConvertFrom-StringData e o resultado na $Hash variável.

$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.

Exemplo 6: Usar caracteres de escape para adicionar novas linhas e retornar caracteres

Este exemplo mostra o uso de caracteres de escape para criar novas linhas e retornar caracteres nos dados de origem. A sequência \n de escape é usada para criar novas linhas dentro de um bloco de texto associado a um nome ou item na tabela de 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.

Exemplo 7: Usar o caractere de escape de barra invertida para renderizar corretamente um caminho de arquivo

Este exemplo mostra como usar o caractere de escape de barra invertida nos dados de cadeia de caracteres para permitir que um caminho de arquivo seja renderizado corretamente na tabela de hash resultante ConvertFrom-StringData . As duas barras invertidas garantem que os caracteres de barra invertida literal sejam processados corretamente na saída da tabela de hash.

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

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

Parâmetros

-StringData

Especifica a cadeia de caracteres a ser convertida. Você pode usar esse parâmetro ou canalizar uma cadeia de caracteres para ConvertFrom-StringData. O nome do parâmetro é opcional.

O valor desse parâmetro deve ser uma cadeia de caracteres que contém um ou mais pares chave-valor. Cada par chave-valor deve estar em uma linha separada ou cada par deve ser separado por caracteres de nova linha ('n).

Você pode incluir comentários na cadeia de caracteres, mas os comentários não podem estar na mesma linha que um par chave-valor. ConvertFrom-StringData ignora comentários de linha única. O # caractere deve ser o primeiro caractere não whitespace na linha. Todos os caracteres na linha depois de # ignorados. Os comentários não são incluídos na tabela de hash.

Uma cadeia de caracteres aqui é uma cadeia de caracteres que consiste em uma ou mais linhas. As aspas dentro da cadeia de caracteres aqui são interpretadas literalmente como parte dos dados da cadeia de caracteres. Para obter mais informações, consulte about_Quoting_Rules.

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

Entradas

String

Você pode canalizar uma cadeia de caracteres que contém um par chave-valor para ConvertFrom-StringData.

Saídas

Hashtable

Esse cmdlet retorna uma tabela de hash que ele cria com base nos pares chave-valor.

Observações

Uma cadeia de caracteres here é uma cadeia de caracteres com uma ou mais linhas, nas quais as aspas são interpretadas literalmente.

Esse cmdlet pode ser útil em scripts que exibem mensagens do usuário em vários idiomas falados. Você pode usar as tabelas de hash em estilo de dicionário para isolar as cadeias de caracteres de texto do código como ocorre em arquivos de recursos, além de formatar as cadeias de caracteres de texto para uso em ferramentas de tradução.