ConvertFrom-StringData
Converte uma cadeia de caracteres contendo um ou mais pares de chave e valor em uma tabela de hash.
Sintaxe
Default (Predefinição)
ConvertFrom-StringData
[-StringData] <String>
[<CommonParameters>]
Description
O cmdlet ConvertFrom-StringData 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 são frequentemente usadas como o formato de entrada.
O cmdlet ConvertFrom-StringData é considerado um cmdlet seguro que pode ser usado na seção DATA de um script ou função. Quando usado em uma seção DATA, 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 suporta sequências de caracteres de escape permitidas pelas ferramentas convencionais de tradução automática. Ou seja, o cmdlet pode interpretar barras invertidas (\) como caracteres de escape nos dados da cadeia de caracteres usando o método Regex.Unescape, em vez do caractere de backtick do Windows PowerShell (') que normalmente sinalizaria o fim de uma linha em um script. Dentro da cadeia de caracteres here, o caractere backtick 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 são comumente usados em caminhos de arquivo, podem renderizar como sequências de escape ilegais em seus resultados.
Exemplos
Exemplo 1: Converter uma cadeia de caracteres entre aspas simples em uma tabela de hash
PS C:\> $Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
PS C:\> 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.
Esses comandos convertem uma única sequência de mensagens de usuário entre aspas em uma tabela de hash. Em uma cadeia de aspas simples, os valores não são substituídos por variáveis e as expressões não são avaliadas.
O primeiro comando cria uma cadeia de caracteres aqui e a salva na variável $Here.
O segundo comando usa o cmdlet ConvertFrom-StringData para converter a cadeia de caracteres here-string na variável $Here em uma tabela de hash.
Exemplo 2: Converter uma cadeia de caracteres entre aspas duplas em uma tabela de hash
PS C:\> $P = @"
ISE = Windows PowerShell Integrated Scripting Environment
"@
PS C:\> $P | Get-Member
TypeName: System.String
Name MemberType Definition
---- ---------- ----------
Clone Method System.Object Clone()
PS C:\> $Hash = ConvertFrom-StringData -StringData $P
PS C:\> $Hash | Get-Member
TypeName: System.Collections.Hashtable
Name MemberType Definition
---- ---------- ----------
Add Method System.Void Add(Object key, Object
Esses comandos demonstram que ConvertFrom-StringData realmente converte uma cadeia de caracteres here, em uma tabela de hash.
O primeiro comando cria uma cadeia de caracteres entre aspas duplas que inclui um par chave/valor e a salva na variável $P.
O segundo comando usa um operador de pipeline (|) para enviar a variável $P para o cmdlet Get-Member. O resultado mostra que $P é uma cadeia de caracteres (System.String).
O terceiro comando usa o cmdlet ConvertFrom-StringData para converter a cadeia de caracteres here-string em $P em uma tabela de hash. O comando armazena o resultado na variável $Hash.
O comando final usa um operador de pipeline (|) para enviar a variável $Hash para o cmdlet Get-Member
Exemplo 3: Converter uma cadeia de caracteres aqui em uma tabela de hash
PS C:\> ConvertFrom-StringData -StringData @'
Name = Disks.ps1
# Category is optional.
Category = Storage
Cost = Free
'@
Name Value
---- -----
Cost Free
Category Storage
Name Disks.ps1
Este comando converte uma cadeia de caracteres entre aspas simples que contém vários pares chave/valor em uma tabela de hash.
Neste comando, 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 formatos é válido.
A cadeia de caracteres aqui inclui um comentário sobre uma das cadeias de caracteres. Os comentários são válidos em cadeias de caracteres, desde que o comentário esteja em uma linha diferente de um par chave/valor.
Exemplo 4: Converter uma cadeia de caracteres em uma tabela de hash
PS C:\> $A = ConvertFrom-StringData -StringData "Top = Red `n Bottom = Blue"
PS C:\> "Top = " + $A.Top
Top = Red PS C:\> "Bottom = " + $A.Bottom
Bottom = Blue
Este exemplo converte uma cadeia de caracteres regular com aspas duplas (não uma cadeia de caracteres here) em uma tabela de hash e a salva na variável $A.
Para satisfazer a condição de que cada par chave/valor deve estar em uma linha separada, ele usa o caractere de nova linha do Windows PowerShell ('n) para separar os pares.
O resultado é uma tabela de hash da entrada. Os comandos restantes exibem a saída.
Exemplo 5: Usar ConvertFrom-StringData na seção DATA de um script
PS C:\> $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.
'@
}
PS C:\> $TextMsgs.Text001
The $Notebook variable contains the name of the user's system notebook. PS C:\> $TextMsgs.Text002
The $MyNotebook variable contains the name of the user's private notebook.
Este exemplo mostra um comando ConvertFrom-StringData usado na seção DATA de um script. As instruções abaixo da seção DADOS exibem o texto para o usuário.
Como o texto inclui nomes de variáveis, ele deve ser incluído em uma cadeia de aspas simples para que as variáveis sejam interpretadas literalmente e não expandidas. As variáveis não são permitidas na secção DADOS.
Exemplo 6: Usar o operador de pipeline para passar uma cadeia de caracteres
PS C:\> $Here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
PS C:\> $Hash = $Here | ConvertFrom-StringData
PS C:\> $Hash
Name Value
---- -----
Msg3 The specified variable does not exist.
Msg2 Credentials are required for this command.
Msg1 The string parameter is required.
Este exemplo mostra que você pode usar um operador de pipeline (|) para enviar uma cadeia de caracteres para ConvertFrom-StringData.
O primeiro comando salva uma cadeia de caracteres here-string na variável $Here. O segundo comando usa um operador de pipeline (|) para enviar a variável $Here para ConvertFrom-StringData. O comando salva o resultado na variável $Hash.
O comando final exibe o conteúdo da variável $Hash.
Exemplo 7: Usar caracteres de escape para adicionar novas linhas e retornar caracteres
PS C:\> 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.
Este exemplo mostra o uso de caracteres de escape para criar novas linhas e retornar caracteres em ConvertFrom-StringData. Neste exemplo, a sequência de escape \n é usada para criar novas linhas dentro de um bloco de texto (o valor, na tabela de hash resultante) que está associado a um nome ou item (o nome, na tabela de hash resultante).
Exemplo 8: Usar o caractere de escape de barra invertida para renderizar corretamente um caminho de arquivo
PS C:\> ConvertFrom-StringData "Message=Look in c:\\Windows\\System32"
Name Value
---- -----
Message Look in c:\Windows\System32
Este exemplo mostra como usar o caractere de escape de barra invertida nos dados da cadeia de caracteres para permitir que um caminho de arquivo seja renderizado corretamente na tabela de hash
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 entre aspas simples, uma cadeia de caracteres entre aspas duplas ou uma cadeia de caracteres que contenha 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. 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 dentro das quais as aspas são interpretadas literalmente. Para obter mais informações, consulte about_Quoting_Rules.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.
Entradas
String
Você pode canalizar uma cadeia de caracteres contendo um par chave/valor para ConvertFrom-StringData.
Saídas
Hashtable
Esse cmdlet retorna uma tabela de hash que ele cria a partir dos pares chave/valor.
Notas
Uma cadeia de caracteres aqui é uma cadeia de caracteres que consiste em uma ou mais linhas dentro das 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 no estilo dicionário para isolar cadeias de caracteres de texto do código, como em arquivos de recursos, e formatar as cadeias de caracteres de texto para uso em ferramentas de tradução.