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 ConvertFrom-StringData cmdlet 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 ConvertFrom-StringData cmdlet jest uważane za bezpieczne polecenie cmdlet, które można użyć 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 ConvertFrom-StringData cmdlet 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 innego niż biały znak w wierszu. Wszystkie znaki w wierszu po znaku # są ignorowane.

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

Ten przykład konwertuje zwykły ciąg o podwójnym cudzysłowie (a nie tutaj-ciąg) 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żyj funkcji ConvertFrom-StringData w sekcji DATA skryptu

W tym przykładzie ConvertFrom-StringData pokazano polecenie używane w sekcji DATA skryptu. Instrukcje poniżej sekcji DANE 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 DANE .

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

W tym przykładzie pokazano, że możesz użyć operatora potoku (|), aby wysłać ciąg do ConvertFrom-StringData. Wartość zmiennej $Here jest potokowana do ConvertFrom-StringData zmiennej i wynik w 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 ConvertFrom-StringData tabeli skrótów. 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 danych wartości w konwertowanym ciągu. Domyślny ogranicznik to znak równości (=). Ten parametr został dodany w programie PowerShell 7.

Type:	Char
Position:	1
Default value:	'='
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StringData

Określa ciąg, który ma zostać przekonwertowany. Możesz użyć tego parametru lub potoku ciągu do ConvertFrom-StringData. 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 innej niż biały znak w wierszu. Wszystkie znaki w wierszu po znaku # 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.

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

Dane wejściowe

String

Do tego polecenia cmdlet można przekazać ciąg zawierający parę klucz-wartość.

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.