ConvertFrom-StringData (Microsoft.PowerShell.Utility)

ConvertFrom-StringData

Модуль:: Microsoft.PowerShell.Utility

Преобразует строку, содержащую одну или несколько пар ключ-значение, в хеш-таблицу.

Синтаксис

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

Описание

Командлет ConvertFrom-StringData преобразует строку, содержащую одну или несколько пар «ключ-значение», в хеш-таблицу. Поскольку каждая пара ключ-значение должна находиться на отдельной строке, в качестве входного формата часто используются строки. По умолчанию ключ должен быть отделен от значения знаком равенства (=).

Командлет ConvertFrom-StringData считается безопасным командлетом, который можно использовать в разделе DATA скрипта или функции. При использовании в разделе DATA содержимое строки должно соответствовать правилам для раздела DATA. Дополнительные сведения см. в разделе about_Data_Sections.

ConvertFrom-StringData поддерживает escape-символы, разрешенные обычными инструментами машинного перевода. То есть командлет может интерпретировать обратную косую черту (\) как escape-символы в строковых данных с помощью метода Regex.Unescape вместо символа обратной косой черты PowerShell (`), который обычно сигнализирует об окончании строки в сценарии. Внутри этой строки символ обратного кавычка не работает. Вы также можете сохранить в результатах обратную косую черту, экранируя ее предшествующей обратной косой чертой, например: \\. Неэкранированные символы обратной косой черты, например те, которые обычно используются в путях к файлам, могут отображаться в результатах как недопустимые escape-последовательности.

В PowerShell 7 добавлен параметр Разделитель.

Примеры

Пример 1. Преобразование строки, заключенной в одинарные кавычки, в хеш-таблицу.

В этом примере строка пользовательских сообщений, заключенная в одинарные кавычки, преобразуется в хеш-таблицу. В строке, заключенной в одинарные кавычки, переменные не заменяются значениями, а выражения не вычисляются. Командлет ConvertFrom-StringData преобразует значение переменной $Here в хеш-таблицу.

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

Пример 2. Преобразование строковых данных с использованием другого разделителя

В этом примере показано, как преобразовать строковые данные, в которых в качестве разделителя используется другой символ. В этом примере строковые данные используют символ вертикальной черты (|) в качестве разделителя.

$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

Пример 3: Преобразование здесь строки, содержащей комментарий

В этом примере строка, содержащая комментарий и несколько пар ключ-значение, преобразуется в хеш-таблицу.

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

# Category is optional.

Category = Storage
Cost = Free
'@

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

Значением параметра StringData является здесь строка, а не переменная, содержащая здесь строку. Любой формат действителен. Здесь строка включает комментарий к одной из строк. ConvertFrom-StringData игнорирует однострочные комментарии, но символ # должен быть первым непробельным символом в строке. Все символы в строке после # игнорируются.

Пример 4. Преобразование строки в хеш-таблицу

В этом примере обычная строка в двойных кавычках (а не строка здесь) преобразуется в хеш-таблицу и сохраняется в переменной $A.

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

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

Чтобы удовлетворить условию, согласно которому каждая пара ключ-значение должна находиться на отдельной строке, в строке используется символ новой строки PowerShell (`n) для разделения пар.

Пример 5. Используйте ConvertFrom-StringData в разделе DATA скрипта.

В этом примере показана команда ConvertFrom-StringData, используемая в разделе DATA сценария. Операторы под разделом DATA отображают текст пользователю.

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

Поскольку текст включает имена переменных, его необходимо заключить в строку с одинарными кавычками, чтобы переменные интерпретировались буквально, а не раскрывались. Переменные не допускаются в разделе DATA.

Пример 6. Использование оператора конвейера для передачи строки

В этом примере показано, что вы можете использовать оператор конвейера (|) для отправки строки в ConvertFrom-StringData. Значение переменной $Here передается в ConvertFrom-StringData, а результат — в переменную $Hash.

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

Пример 7. Используйте escape-символы для добавления новых строк и возврата символов.

В этом примере показано использование escape-символов для создания новых строк и возврата символов в исходных данных. Escape-последовательность \n используется для создания новых строк внутри блока текста, который связан с именем или элементом в результирующей хэш-таблице.

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.

Пример 8. Используйте escape-символ обратной косой черты для правильного отображения пути к файлу.

В этом примере показано, как использовать escape-символ обратной косой черты в строковых данных, чтобы обеспечить правильное отображение пути к файлу в результирующей хэш-таблице ConvertFrom-StringData. Двойная обратная косая черта гарантирует, что буквальные символы обратной косой черты корректно отображаются в выходных данных хэш-таблицы.

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

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

Параметры

-Delimiter

Символ, используемый для отделения ключа от данных значения в преобразуемой строке. Разделителем по умолчанию является знак равенства (=). Этот параметр был добавлен в PowerShell 7.

Тип :: Чар
Позиция:: 1
Значение по умолчанию:: '='
Необходимый:: False
Примите ввод конвейера:: False
Принимайте подстановочные знаки:: False

-StringData

Указывает строку, которую необходимо преобразовать. Вы можете использовать этот параметр или передать строку в ConvertFrom-StringData. Имя параметра не является обязательным.

Значением этого параметра должна быть строка, содержащая одну или несколько пар ключ-значение. Каждая пара ключ-значение должна находиться на отдельной строке или каждая пара должна быть разделена символами новой строки (`n).

Вы можете включать комментарии в строку, но они не могут находиться в одной строке с парой ключ-значение. ConvertFrom-StringData игнорирует однострочные комментарии. Символ # должен быть первым символом без пробелов в строке. Все символы в строке после # игнорируются. Комментарии не включаются в хеш-таблицу.

Здесь строка — это строка, состоящая из одной или нескольких строк. Кавычки внутри строки интерпретируются буквально как часть данных строки. Дополнительные сведения см. в разделе about_Quoting_Rules.

Тип :: String
Позиция:: 0
Значение по умолчанию:: None
Необходимый:: True
Примите ввод конвейера:: True
Принимайте подстановочные знаки:: False

Входы

Строка

В этот командлет можно передать строку, содержащую пару ключ-значение.

Выходы

Хеш-таблица

Этот командлет возвращает хеш-таблицу, созданную на основе пар ключ-значение.

Примечания

Здесь строка — это строка, состоящая из одной или нескольких строк, внутри которых кавычки интерпретируются буквально.

Этот командлет может быть полезен в сценариях, отображающих сообщения пользователя на нескольких разговорных языках. Хэш-таблицы в стиле словаря можно использовать для изоляции текстовых строк от кода, например, в файлах ресурсов, а также для форматирования текстовых строк для использования в инструментах перевода.