ConvertFrom-StringData
Converte uma cadeia de caracteres que contém um ou mais pares de chave/valor para uma tabela de hash.
Sintaxe
ConvertFrom-StringData [-StringData] <string> [<CommonParameters>]
Descrição
O cmdlet ConvertFrom-StringData converte uma cadeia de caracteres que contém um ou mais pares de chave/valor em uma tabela de hash. Como cada par de chave/valor deve estar em uma linha separada, cadeias de caracteres here normalmente são usadas como o formato de entrada.
O cmdlet ConvertFrom-StringData é considerado como 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.
Parâmetros
-StringData <string>
Especifica a cadeia de caracteres a ser convertida. É possível 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 incluída entre aspas simples (uma cadeia de caracteres entre aspas simples) ou uma cadeia de caracteres incluída entre aspas duplas (uma cadeia de caracteres entre aspas duplas) ou uma cadeia de caracteres here que contém um ou mais pares de chave/valor. Cada par de chave/valor deve estar em uma linha separada ou deve ser separado pelos caracteres de nova linha ('n).
É possível incluir comentários na cadeia de caracteres, mas os comentários não podem estar na mesma linha que um par de chave/valor. Os comentários não são incluídos na tabela de hash.
Uma cadeia de caracteres here é uma cadeia de caracteres que consiste em uma ou mais linhas dentro das quais aspas são interpretadas literalmente. Para obter mais informações, consulte about_Quoting_Rules.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue) |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
System.String Você pode enviar uma cadeia de caracteres que contém um par de chave/valor para ConvertFrom-StringData. |
Saídas |
System.Collections.Hashtable ConvertFrom-StringData retorna uma tabela de hash criada a partir dos pares de chave/valor. |
Observações
Uma cadeia de caracteres here é uma cadeia de caracteres que consiste em uma ou mais linhas dentro das quais aspas são interpretadas literalmente. Para obter mais informações, consulte about_Quoting_Rules.
ConvertFrom-StringData pode ser útil em scripts que exibem mensagens de usuário em vários idiomas. É possível usar tabelas de hash em estilo de dicionário para isolar cadeias de caracteres de texto do código, como em arquivos de recursos, e formar cadeias de caracteres de texto para uso em ferramentas de tradução.
Exemplo 1
C:\PS>$here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
C:\PS> 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.
Descrição
-----------
Esses comandos convertem uma cadeia de caracteres here entre aspas simples 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 para variáveis e as expressões não são avaliadas.
O primeiro comando cria uma cadeia de caracteres here e salva-a na variável $here.
O segundo comando usa o cmdlet ConvertFrom-StringData para converter a cadeia de caracteres here na variável $here em uma tabela de hash.
Exemplo 2
C:\PS>$p = @"
ISE = Windows PowerShell Integrated Scripting Environment
"@
C:\PS> $p | get-member
TypeName: System.String
Name MemberType Definition
---- ---------- ----------
Clone Method System.Object Clone()
...
C:\PS> $hash = convertfrom-stringdata -stringdata $p
C:\PS> $hash | get-member
TypeName: System.Collections.Hashtable
Name MemberType Definition
---- ---------- ----------
Add Method System.Void Add(Object key, Object
...
Descrição
-----------
Esses comandos demonstram que ConvertFrom-StringData realmente converte um cadeia de caracteres here em uma tabela de hash.
O primeiro comando cria uma cadeia de caracteres here entre aspas duplas que inclui um par de chave/valor e salva-a na variável $p.
O segundo comando usa um operador de pipeline (|) para enviar a variável $p ao 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 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 ao cmdlet Get-Member. O resultado mostra que o conteúdo da variável $hash é uma tabela de hash (System.Collections.Hashtable).
Exemplo 3
C:\PS>convertfrom-stringdata -stringdata @'
Name = Disks.ps1
# Category is optional.
Category = Storage
Cost = Free
'@
Name Value
---- -----
Cost Free
Category Storage
Name Disks.ps1
Descrição
-----------
Esse comando converte uma cadeia de caracteres here entre aspas simples que contém vários pares de chave/valor em uma tabela de hash.
Nesse comando, o valor do parâmetro StringData é uma cadeia de caracteres here, em vez de uma variável que contém uma cadeia de caracteres here. Qualquer formato é válido.
A cadeia de caracteres here 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 de chave/valor.
Exemplo 4
C:\PS>$a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue"
C:\PS> "Top = " + $a.Top
Top = Red
C:\PS> "Bottom = " + $a.Bottom
Bottom = Blue
Descrição
-----------
Esse exemplo converte uma cadeia de caracteres entre aspas duplas (não uma cadeia de caracteres here) em uma tabela de hash e salva-a na variável $a.
Para satisfazer a condição de que cada par de 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
C:\PS>$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.
'@
}
C:\PS> $TextMsgs.Text001
The $Notebook variable contains the name of the user's system notebook.
C:\PS> $TextMsgs.Text002
The $MyNotebook variable contains the name of the user's private notebook.
Descrição
-----------
Esse exemplo mostra um comando ConvertFrom-StringData usado na seção DATA de um script. As instruções abaixo da seção DATA exibem o texto para o usuário.
Como o texto inclui nomes de variável, ele deve ser incluído em uma cadeia de caracteres entre aspas simples para que as variáveis sejam interpretadas literalmente e não expandidas. Variáveis não são permitidas na seção DATA.
Exemplo 6
C:\PS>$here = @'
Msg1 = The string parameter is required.
Msg2 = Credentials are required for this command.
Msg3 = The specified variable does not exist.
'@
C:\PS> $hash = $here | convertfrom-stringdata
C:\PS> $hash
Name Value
---- -----
Msg3 The specified variable does not exist.
Msg2 Credentials are required for this command.
Msg1 The string parameter is required.
Descrição
-----------
Esse exemplo mostra que é possível usar um operador de pipeline (|) para enviar uma cadeia de caracteres a ConvertFrom-StringData.
O primeiro comando salva uma cadeia de caracteres here na variável $here. O segundo comando usa um operador de pipeline (|) para enviar a variável $here ao cmdlet ConvertFrom-StringData. O comando salva o resultado na variável $hash.
O comando final exibe o conteúdo da variável $hash.
Consulte também
Conceitos
about_Data_Sections
about_Quoting_Rules
about_Script_Internationalization