ConvertFrom-StringData

Moduł:

Microsoft.PowerShell.Utility

Konwertuje ciąg zawierający co najmniej jedną parę klucz i wartość na tabelę skrótów.

Składnia

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

Opis

Polecenie cmdlet ConvertFrom-StringData konwertuje ciąg zawierający co najmniej jedną parę klucz i wartość na tabelę skrótów. Ponieważ każda para klucz-wartość musi znajdować się w osobnym wierszu, te ciągi są często używane jako format wejściowy. Domyślnie klucz musi być oddzielony od wartości znakiem równości ().

Polecenie cmdlet ConvertFrom-StringData jest uważane za bezpieczne polecenie cmdlet, które może być używane w sekcji DATA skryptu lub funkcji. W przypadku użycia w sekcji DATA zawartość ciągu musi być zgodna z regułami sekcji DATA. Aby uzyskać więcej informacji, zobacz about_Data_Sections.

ConvertFrom-StringData obsługuje sekwencje znaków ucieczki, które są dozwolone przez konwencjonalne narzędzia tłumaczenia maszynowego. Oznacza to, że polecenie cmdlet może interpretować ukośniki odwrotne (\) jako znaki ucieczki w danych ciągu przy użyciu metody Regex.Unescape, zamiast znaku backtick programu PowerShell (`), który normalnie sygnalizuje koniec wiersza w skrypce. Wewnątrz ciągu tutaj znak backtick nie działa. Możesz również zachować ukośnik odwrotny literału w wynikach, uciekając przed poprzednim ukośnikiem odwrotnym, w następujący sposób: \\. Niezasłane znaki ukośnika odwrotnego, takie jak te, które są często używane w ścieżkach plików, mogą być renderowane jako niedozwolone sekwencje ucieczki w wynikach.

Program PowerShell 7 dodaje parametr ogranicznika .

Przykłady

Przykład 1. Konwertowanie pojedynczego cudzysłów tutaj-ciągu na tabelę skrótów

Ten przykład konwertuje jednocytowy ciąg komunikatów użytkownika na tabelę skrótów. W ciągu jednocygowym wartości nie są zastępowane zmiennymi, a wyrażenia nie są obliczane. Polecenie cmdlet ConvertFrom-StringData konwertuje wartość w zmiennej $Here na tabelę skrótów.

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

Przykład 2. Konwertowanie danych ciągów przy użyciu innego ogranicznika

W tym przykładzie pokazano, jak przekonwertować dane ciągu, które używają innego znaku jako ogranicznika. W tym przykładzie dane ciągu używają znaku potoku (|) jako ogranicznika.

$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

Przykład 3. Konwertowanie tutaj-ciągu zawierającego komentarz

W tym przykładzie jest konwertowany ciąg here-string zawierający komentarz i wiele par klucz-wartość na tabelę skrótów.

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

# Category is optional.

Category = Storage
Cost = Free
'@

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

Wartość parametru StringData jest ciągiem tutaj, a nie zmienną zawierającą tutaj-ciąg. Dowolny format jest prawidłowy. Ten ciąg zawiera komentarz dotyczący jednego z ciągów. ConvertFrom-StringData ignoruje komentarze jednowierszowe, ale znak # musi być pierwszym znakiem bez odstępu w wierszu. Wszystkie znaki w wierszu po # są ignorowane.

Przykład 4. Konwertowanie ciągu na tabelę skrótów

W tym przykładzie jest konwertowany zwykły ciąg dwucytowy (a nie ciąg tutaj) na tabelę skrótów i zapisuje go w zmiennej $A.

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

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

Aby spełnić warunek, że każda para klucz-wartość musi znajdować się w osobnym wierszu, ciąg używa znaku nowego wiersza programu PowerShell (`n), aby oddzielić pary.

Przykład 5. Użycie ConvertFrom-StringData w sekcji DATA skryptu

W tym przykładzie pokazano polecenie używane w sekcji DATA skryptu. Instrukcje poniżej sekcji DATA wyświetlają tekst użytkownikowi.

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

Ponieważ tekst zawiera nazwy zmiennych, musi być ujęta w ciąg o pojedynczym cudzysłowie, aby zmienne zostały interpretowane dosłownie i nie zostały rozwinięte. Zmienne nie są dozwolone w sekcji DATA.

Przykład 6. Użyj operatora potoku, aby przekazać ciąg

W tym przykładzie pokazano, że możesz użyć operatora potoku (|) do wysłania ciągu do ConvertFrom-StringData. Wartość zmiennej $Here jest potokowana do ConvertFrom-StringData i wynik zmiennej $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.

Przykład 7. Używanie znaków ucieczki w celu dodania nowych wierszy i znaków zwracanych

W tym przykładzie pokazano użycie znaków ucieczki do tworzenia nowych wierszy i zwracania znaków w danych źródłowych. Sekwencja ucieczki \n służy do tworzenia nowych wierszy w bloku tekstu skojarzonego z nazwą lub elementem w wynikowej tabeli skrótów.

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.

Przykład 8. Użyj znaku ucieczki ukośnika odwrotnego, aby poprawnie renderować ścieżkę pliku

W tym przykładzie pokazano, jak używać znaku ucieczki ukośnika odwrotnego w danych ciągu, aby umożliwić poprawne renderowanie ścieżki pliku w wynikowej tabeli skrótów ConvertFrom-StringData. Podwójny ukośnik odwrotny gwarantuje, że znaki ukośnika odwrotnego literału są poprawnie renderowane w danych wyjściowych tabeli skrótów.

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

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

Parametry

-Delimiter

Znak używany do oddzielenia klucza od wartości danych w ciągu, który jest konwertowany. Domyślny ogranicznik to znak równości (=) znak. Ten parametr został dodany w programie PowerShell 7.

Typ:	Char
Position:	0
Domyślna wartość:	'='
Wymagane:	False
Akceptowanie danych wejściowych potoku:	False
Akceptowanie symboli wieloznacznych:	False

-StringData

Określa ciąg, który ma zostać przekonwertowany. Tego parametru lub potoku można użyć do ConvertFrom-StringDataciągu . Nazwa parametru jest opcjonalna.

Wartość tego parametru musi być ciągiem zawierającym co najmniej jedną parę klucz-wartość. Każda para klucz-wartość musi znajdować się w osobnym wierszu lub każda para musi być oddzielona znakami nowego wiersza (`n).

Komentarze można uwzględnić w ciągu, ale komentarze nie mogą znajdować się w tym samym wierszu co para klucz-wartość. ConvertFrom-StringData ignoruje komentarze jednowierszowe. Znak # musi być pierwszym znakiem bez odstępu w wierszu. Wszystkie znaki w wierszu po # są ignorowane. Komentarze nie są uwzględniane w tabeli skrótów.

Tutaj ciąg jest ciągiem składającym się z co najmniej jednego wiersza. Znaki cudzysłowu w ciągu tutaj są interpretowane dosłownie jako część danych ciągu. Aby uzyskać więcej informacji, zobacz about_Quoting_Rules.

Typ:	String
Position:	0
Domyślna wartość:	None
Wymagane:	True
Akceptowanie danych wejściowych potoku:	True
Akceptowanie symboli wieloznacznych:	False

Dane wejściowe

String

Możesz przekazać ciąg zawierający parę klucz-wartość, aby ConvertFrom-StringData.

Dane wyjściowe

Hashtable

To polecenie cmdlet zwraca tabelę skrótów tworzoną na podstawie par klucz-wartość.

Uwagi

Tutaj ciąg jest ciągiem składającym się z co najmniej jednego wiersza, w którym znaki cudzysłowu są interpretowane dosłownie.

To polecenie cmdlet może być przydatne w skryptach, które wyświetlają komunikaty użytkowników w wielu językach mówionych. Tabele skrótów w stylu słownika umożliwiają odizolowanie ciągów tekstowych od kodu, takiego jak pliki zasobów, oraz formatowanie ciągów tekstowych do użycia w narzędziach tłumaczenia.