6. Konvertierungen

Redaktionelle Notiz

Wichtig

Die Windows PowerShell Language Specification 3.0 wurde im Dezember 2012 veröffentlicht und basiert auf Windows PowerShell 3.0. Diese Spezifikation spiegelt nicht den aktuellen Status von PowerShell wider. Es ist nicht geplant, diese Dokumentation zu aktualisieren, um den aktuellen Zustand widerzuspiegeln. Diese Dokumentation wird hier zur historischen Referenz vorgestellt.

Das Spezifikationsdokument ist im Microsoft Download Center als Microsoft Word-Dokument verfügbar unter der Adresse: https://www.microsoft.com/download/details.aspx?id=36389. Dieses Word-Dokument wurde hier auf Microsoft Learn für die Präsentation umgewandelt. Während der Konvertierung wurden einige redaktionelle Änderungen vorgenommen, um die Formatierung für die Docs-Plattform zu berücksichtigen. Einige Tippfehler und kleinere Fehler wurden korrigiert.

Eine Typkonvertierung wird durchgeführt, wenn der Wert eines Typs in einem Kontext verwendet wird, in dem ein anderer Typ erforderlich ist. Wenn eine solche Konvertierung automatisch erfolgt, wird sie als implizite Konvertierung bezeichnet. (Ein gängiges Beispiel hierfür sind Operatoren, die einen oder mehrere Werte konvertieren müssen, die von ihren Operanden angegeben werden.) Die implizite Konvertierung ist zulässig, wenn der Sinn des Quellwerts beibehalten wird, also beispielsweise kein Genauigkeitsverlust einer Zahl bei der Konvertierung erfolgt.

Mit dem Umwandlungsoperator (§7.2.9) ist die explizite Konvertierung möglich.

Konvertierungen werden weiter unten behandelt. Zusätzliche Informationen werden bei Bedarf in der Beschreibung der einzelnen Operatoren unter §6.19 aufgeführt.

Die explizite Konvertierung eines Werts in den Typ, den er bereits hat, bewirkt keine Änderung an diesem Wert oder seiner Darstellung.

Die Regeln zur Handhabung der Konvertierung, bei der der Wert eines Ausdrucks an einen Parameter gebunden wird, werden unter §6.17 behandelt.

6.1 Konvertierung in void

Der Wert eines beliebigen Typs kann explizit verworfen werden, indem er in den Typ void umgewandelt wird. Es gibt kein Ergebnis.

6.2 Konvertierung in bool

Die Regeln zum Konvertieren eines beliebigen Werts in den Typ bool lauten wie folgt:

• Ein numerischer oder char-Wert von 0 (null) wird in FALSE konvertiert. Ein numerischer oder char-Wert ungleich 0 (null) wird in TRUE konvertiert.
• Ein Wert vom Typ NULL wird in False konvertiert.
• Eine Zeichenfolge der Länge 0 wird in False konvertiert, und eine Zeichenfolge mit der Länge > 0 wird in True konvertiert.
• Ein Schalterparameter mit dem Wert $true wird in "True" konvertiert, und einer mit dem Wert $false wird in "False" konvertiert.
• Alle anderen Referenztypwerte, die nicht null sind, werden in True konvertiert.

Wenn der Typ IList implementiert:

• Wenn die Länge des Objekts > 2 ist, wird der Wert in "True" konvertiert.
• Wenn die Länge des Objekts 1 beträgt und das erste Element selbst keine IList ist, wird der Wert in TRUE konvertiert, wenn der Wert dieses Elements TRUE ist.
• Wenn die Count-Eigenschaft des ersten Elements >= 1 beträgt, wird der Wert sonst in TRUE umgewandelt.
• Andernfalls wird der Wert in False konvertiert.

6.3 Konvertierung in char

Die Regeln zum Konvertieren eines Werts in Typzeichen lauten wie folgt:

• Die Konvertierung eines Werts vom Typ "bool", "dezimal", "float" oder "double" ist fehlerhaft.
• Ein Wert des Nulltyps wird in das Nullzeichen (U+0000) konvertiert.
• Ein ganzzahliger Typwert, dessen Wert im Typ char dargestellt werden kann, hat diesen Wert; andernfalls ist die Konvertierung fehlerhaft.
• Die Konvertierung eines Zeichenfolgenwerts mit einer anderen Länge als 1 ist fehlerhaft.
• Ein Zeichenfolgenwert mit der Länge 1 wird in einen char-Typ mit dem Wert dieses Zeichens konvertiert.
• Ein Wert des numerischen Typs, dessen Wert nach der Rundung eines beliebigen Nachkommaanteils im Zieltyp dargestellt werden kann, weist diesen gerundeten Wert auf. Andernfalls ist die Konvertierung fehlerhaft.
• Bei anderen Referenztypwerten wird diese Konvertierung verwendet, wenn der Referenztyp eine solche Konvertierung unterstützt; andernfalls ist die Konvertierung fehlerhaft.

6.4 Konvertierung in ganze Zahl

Die Regeln zum Konvertieren eines beliebigen Werts in den Typ byte, int oder long lauten wie folgt:

• Der Boolwert False wird in Null konvertiert. der Boolwert True wird in 1 konvertiert.
• Ein Zeichentypwert, dessen Wert im Zieltyp dargestellt werden kann, weist diesen Wert auf; andernfalls ist die Konvertierung fehlerhaft.
• Ein Wert des numerischen Typs, dessen Wert nach der Rundung eines beliebigen Nachkommaanteils im Zieltyp dargestellt werden kann, weist diesen gerundeten Wert auf. Andernfalls ist die Konvertierung fehlerhaft.
• Ein Wert vom Typ NULL wird in 0 (null) konvertiert.
• Eine Zeichenfolge, die eine Zahl darstellt, wird wie in §6.16beschrieben konvertiert. Wenn nach des Nachkommaanteils das Ergebnis im Zieltyp dargestellt werden kann, ist die Zeichenfolge korrekt gebildet und hat den Zieltyp. Andernfalls ist die Konvertierung fehlerhaft. Wenn die Zeichenfolge keine Zahl darstellt, ist die Konvertierung fehlerhaft.
• Bei anderen Referenztypwerten wird diese Konvertierung verwendet, wenn der Referenztyp eine solche Konvertierung unterstützt; andernfalls ist die Konvertierung fehlerhaft.

6.5 Konvertierung in float und double

Die Regeln zum Konvertieren eines Werts in den Typ "Float" oder "Double" lauten wie folgt:

• Der Boolwert False wird in Null konvertiert. der Boolwert True wird in 1 konvertiert.
• Ein char-Wert wird genau angegeben.
• Ein Wert des numerischen Typs wird nach Möglichkeit genau angegeben. Bei Konvertierungen von int, long und decimal in float sowie bei Konvertierungen von long und decimal in double gehen einige der Bits mit dem niedrigsten Schwellenwert des integer-Werts möglicherweise verloren.
• Ein Wert vom Typ NULL wird in 0 (null) konvertiert.
• Eine Zeichenfolge, die eine Zahl darstellt, wird wie in §6.16beschrieben konvertiert; andernfalls ist die Konvertierung fehlerhaft.
• Bei anderen Referenztypwerten wird diese Konvertierung verwendet, wenn der Referenztyp eine solche Konvertierung unterstützt; andernfalls ist die Konvertierung fehlerhaft.

6.6 Konvertierung in dezimal

Die Regeln zum Konvertieren eines beliebigen Werts in den Typ Decimal lauten wie folgt:

• Der Boolwert False wird in Null konvertiert. der Boolwert True wird in 1 konvertiert.
• Ein Wert des Typs char wird genau angegeben.
• Ein numerischer Typwert wird genau dargestellt; Wenn dieser Wert jedoch zu groß oder zu klein ist, um in den Zieltyp einzupassen, ist die Konvertierung fehlerhaft.
• Ein Wert vom Typ NULL wird in 0 (null) konvertiert.
• Eine Zeichenfolge, die eine Zahl darstellt, wird wie in §6.16beschrieben konvertiert; andernfalls ist die Konvertierung fehlerhaft.
• Bei anderen Referenztypwerten wird diese Konvertierung verwendet, wenn der Referenztyp eine solche Konvertierung unterstützt; andernfalls ist die Konvertierung fehlerhaft.
• Das Ergebnis einer erfolgreichen Konvertierung wird so dargestellt, dass der Nachkommaanteil keine nachgestellten Nullen enthält.

6.7 Konvertierung in ein Objekt

Der Wert eines beliebigen Typs mit Ausnahme des Nulltyps (4.1.2) kann in typobjekt konvertiert werden. Der Wert behält seinen Typ und seine Darstellung bei.

6.8 Umwandlung in String

Die Regeln zum Konvertieren eines beliebigen Werts in den Typ string lauten wie folgt:

• Der boolesche Wert $false wird in "False" konvertiert; der boolesche Wert $true wird in "True" konvertiert.
• Ein Zeichentypwert wird in eine 1-stellige Zeichenfolge konvertiert, die dieses Zeichen enthält.
• Ein Wert des numerischen Typs wird in eine Zeichenfolge mit der Form eines entsprechenden numerischen Literals konvertiert. Das Ergebnis hat jedoch keine führenden oder nachgestellten Leerzeichen, kein führendes Pluszeichen, Ganzzahlen haben die Basis 10 und es gibt kein Typensuffix. Bei einer Dezimalkonvertierung wird die Skalierung beibehalten. Für die Werte -∞, +∞ und NaN sind die resultierenden Zeichenfolgen „-Unendlichkeit“, „Unendlichkeit“ und „NaN“.
• Ein Wert vom Typ NULL wird in die leere Zeichenfolge konvertiert.
• Bei einem eindimensionalen Array ist das Ergebnis eine Zeichenfolge, die den Wert jedes Elements in diesem Array von Anfang bis Ende enthält und in den Typ string konvertiert wird, wobei die Elemente durch das aktuelle Ausgabefeldtrennzeichen (§2.3.2.2) getrennt werden. Für ein Array mit Elementen, die selbst Arrays sind, werden nur die Elemente der obersten Ebene konvertiert. Die Zeichenfolge, die zum Darstellen des Werts eines Elements verwendet wird, das ein Array ist, wird durch die Implementierung definiert. Bei einem mehrdimensionalen Array wird sie vereinfacht (§9.12) und dann als eindimensionales Array behandelt.
• Ein Wert vom Typ NULL wird in die leere Zeichenfolge konvertiert.
• Ein Scriptblock-Typwert wird in eine Zeichenfolge umgewandelt, die den Text dieses Blocks ohne die begrenzenden Zeichen { und } enthält.
• Bei einem Enumerationstypwert ist das Ergebnis eine Zeichenfolge, die den Namen jeder Enumerationskonstante enthält, die in diesem Wert codiert ist, getrennt durch Kommas.
• Bei anderen Referenztypwerten wird diese Konvertierung verwendet, wenn der Referenztyp eine solche Konvertierung unterstützt; andernfalls ist die Konvertierung fehlerhaft.

Die Zeichenfolge, die verwendet wird, um den Wert eines Elements darzustellen, das ein Array ist, weist die Form System.Type[], System.Type[,]usw. auf. Bei anderen Verweistypen wird die Methode ToString aufgerufen. Bei anderen aufzählbaren Typen wird der Quellwert wie ein 1dimensionales Array behandelt.

6.9 Konvertierung zu einem Array

Die Regeln zum Konvertieren eines Beliebigen Werts in einen Arraytyp lauten wie folgt:

• Der Zieltyp darf kein mehrdimensionales Array sein.
• Ein Wert vom Typ NULL wird unverändert beibehalten.
• Bei einem Skalarwert ungleich $null oder einem Wert vom Typ hashtable wird ein neues Array mit einem Element erstellt, dessen Wert der Skalarwert nach der Konvertierung in den Zielelementtyp ist.
• Bei einem eindimensionalen Arraywert wird ein neues Array des Zieltyps erstellt, und jedes Element wird mit einer Konvertierung aus dem Quellarray in das entsprechende Element im Zielarray kopiert.
• Bei einem mehrdimensionalen Arraywert wird das Array erst vereinfacht (§9.12) und dann als eindimensionaler Arraywert behandelt.
• Ein Zeichenfolgenwert wird in ein Array von Zeichen umgewandelt, das die gleiche Länge wie der Zeichenfolgenwert hat. Die aufeinanderfolgenden Zeichen aus der Zeichenfolge nehmen dabei entsprechende Positionen im Array ein.

Bei anderen aufzählbaren Typen wird ein neues Array mit einem Element erstellt, dessen Wert nach der Konvertierung in den Zielelementtyp das entsprechende Element ist, falls eine solche Konvertierung erfolgt. Andernfalls ist die Konvertierung fehlerhaft.

6.10 Konvertierung in XML

Das Objekt wird in typische Zeichenfolge und dann in ein XML-Dokumentobjekt vom Typ xmlkonvertiert.

6.11 Konvertierung in regex

Ein Ausdruck, der einen Wert vom Typ String angibt, kann in den Typ regexkonvertiert werden.

6.12 Konvertierung in scriptblock

Die Regeln zum Konvertieren eines beliebigen Wertes in Typ scriptblock sind wie folgt:

• Ein Zeichenfolgenwert wird als Name eines Befehls behandelt, dem optional Argumente für einen Aufruf dieses Befehls folgen.

6.13 Konvertierung in Enumerationstypen

Die Regeln zum Konvertieren eines beliebigen Wertes in einen Enumerationstyp lauten wie folgt:

• Ein Wert vom Typ string, der einen der benannten Werte (unter Berücksichtigung der Groß- und Kleinschreibung) für einen Enumerationstyp enthält, wird in diesen benannten Wert konvertiert.
• Ein Wert vom Typ string, der eine durch Kommas getrennte Liste von benannten Werten (unter Berücksichtigung der Groß- und Kleinschreibung) für einen Enumerationstyp enthält, wird in den bitweisen Operator all dieser benannten Werte konvertiert.

6.14 Konvertierung in andere Verweistypen

Die Regeln zum Konvertieren eines Werts in einen anderen Bezugstyp als ein Arraytyp oder eine Zeichenfolge lauten wie folgt:

• Ein Wert vom Typ NULL wird unverändert beibehalten.
• Andernfalls ist das Verhalten implementierungsspezifisch definiert.

Hier kommen mehrere Mechanismen ins Spiel: Dazu gehören die mögliche Verwendung von Konstruktoren mit einem Argument oder Standardkonstruktoren, wenn der Wert eine Hashtabelle ist, implizite und explizite Konvertierungsoperatoren und Parse-Methoden für den Zieltyp sowie die Nutzung von Convert.ConvertTo und des ETS-Konvertierungsmechanismus.

6.15 Übliche arithmetische Konvertierungen

Wenn kein Operand einen Wert mit numerischem Typ angibt, dann

• Wenn der linke Operand einen Wert vom Typ Bool angibt, ist die Konvertierung fehlerhaft.
• Andernfalls werden alle Operanden, die den Wert $null angeben, in 0 (null) vom Typ int konvertiert, und der Prozess wird mit den unten aufgeführten numerischen Konvertierungen fortgesetzt.
• Andernfalls, wenn der linke Operand einen Wert vom Typ char und der rechte Operand einen Wert vom Typ Bool angibt, ist die Konvertierung fehlerhaft.
• Falls der linke Operand einen Wert vom Typ string angibt, aber keine Zahl darstellt (§6.16), ist die Konvertierung fehlerhaft.
• Wenn der rechte Operand hingegen einen Wert vom Typ string angibt, aber keine Zahl darstellt (§6.16), ist die Konvertierung fehlerhaft.
• Andernfalls werden alle Operanden, die Werte vom Typ string bezeichnen, in Zahlen konvertiert (§6.16), und der Prozess wird mit den unten aufgeführten numerischen Konvertierungen fortgesetzt.
• Andernfalls ist die Konvertierung fehlerhaft.

Numerische Konvertierungen:

• Wenn ein Operand einen Wert vom Typ "Dezimalwert" angibt, wird der durch den anderen Operanden festgelegte Wert bei Bedarf in diesen Typ konvertiert. Das Ergebnis weist den Typ decimal auf.
• Wenn ein Operand andernfalls einen Wert vom Typ "Double" angibt, wird der vom anderen Operanden angegebene Wert bei Bedarf in diesen Typ konvertiert. Das Ergebnis hat den Typ double.
• Wenn ein Operand jedoch einen Wert vom Typ float angibt, wird der vom anderen Operanden angegebene Typ bei Bedarf in diesen Typ konvertiert. Das Ergebnis hat den Typ double.
• Sollte ein Operand einen Wert vom Typ long angeben, wird der vom anderen Operanden angegebene Wert bei Bedarf in diesen Typ konvertiert. Das Ergebnis hat den ersten Typ in der Sequenz long und double, der seinen Wert darstellen kann.
• Andernfalls werden von beiden Operanden angegebenen Werte bei Bedarf in diesen Typ konvertiert. Das Ergebnis hat den ersten Typ in der Sequenz int, long, double, der seinen Wert ohne Kürzung darstellen kann.

6.16 Konvertierung von string in einen numerischen Typ

Je nach Inhalt kann eine Zeichenfolge explizit oder implizit in einen numerischen Wert konvertiert werden. Sie haben folgende Möglichkeiten:

• Eine leere Zeichenfolge wird in den Wert Null konvertiert.
• Führende und nachstehende Leerzeichen werden ignoriert. Eine Zeichenfolge darf jedoch nicht nur aus Leerzeichen bestehen.
• Eine Zeichenfolge, die nur Leerzeichen und/oder Zeilenterminatoren enthält, wird in den Wert Null konvertiert.
• Ein führendes + oder - ist zulässig.
• Eine ganzzahlige Zahl kann ein Hexadezimalpräfix (0x oder 0X) aufweisen.
• Ein Exponent mit optionalem Vorzeichen ist zulässig.
• Typsuffixe und Multiplikatoren sind nicht zulässig.
• Die in Groß- und Kleinschreibung unterschiedenen Zeichenfolgen „-Unendlichkeit“, „Unendlichkeit“ und „NaN“ werden als die Werte -∞, +∞ bzw. NaN erkannt.

6.17 Konvertierung während der Parameterbindung

Informationen zur Parameterbindung finden Sie unter §8.14.

Wenn der Wert eines Ausdrucks an einen Parameter gebunden wird, gibt es zusätzliche Konvertierungsüberlegungen, wie unten beschrieben:

• Wenn der Parametertyp Schalter (§4.2.5, §8.10.5) ist und der Parameter kein Argument enthält, wird der Wert des Parameters im ausgeführten Befehl auf $truegesetzt. Wenn der Parametertyp anders als "Switch" ist, ist ein Parameter ohne Argument fehlerhaft.
• Wenn der Parametertyp Schalter ist und der Argumentwert $nullist, wird der Parameterwert auf $falsegesetzt.
• Wenn der Parametertyp objekt oder identisch mit dem Typ des Arguments ist, wird der Wert des Arguments ohne Konvertierung übergeben.
• Wenn der Parametertyp kein Objekt oder Skriptblock ist, wird ein Argument mit typ scriptblock ausgewertet und das Ergebnis als Wert des Arguments übergeben. (Dies wird als verzögerte Skriptblockbindungbezeichnet.) Wenn der Parametertyp Objekt oder Scriptblock ist, wird ein Argument mit Typ Scriptblock unverändert übergeben.
• Wenn der Parametertyp eine Auflistung vom Typ T2 ist und das Argument ein Skalar vom Typ T1 ist, wird dieser Skalar in eine Auflistung vom Typ T2 konvertiert, die ein Element enthält. Bei Bedarf wird der Skalarwert mithilfe der Konvertierungsregeln dieses Abschnitts in den Typ T2 konvertiert.
• Wenn der Parametertyp ein anderer Skalartyp als Objekt ist und das Argument eine Auflistung ist, ist das Argument fehlerhaft.
• Wenn der erwartete Parametertyp eine Auflistung vom Typ T2 ist und das Argument eine Auflistung vom Typ T1 ist, wird das Argument in eine Auflistung vom Typ T2 konvertiert, die dieselbe Länge wie die Argumentauflistung aufweist. Bei Bedarf werden die Werte des Argumentauflistungselements mithilfe der Konvertierungsregeln dieses Abschnitts in den Typ T2 konvertiert.
• Wenn die oben genannten Schritte und die oben in diesem Kapitel angegebenen Konvertierungen nicht ausreichen, werden die Regeln in §6.18 angewendet. Wenn diese Parameter fehlschlagen, schlägt die Parameterbindung fehl.

6.18 .NET-Konvertierung

Bei einer impliziten Konvertierung werden die integrierten Konvertierungen von PowerShell zuerst ausprobiert. Wenn sie die Konvertierung nicht auflösen können, werden die unten aufgeführten benutzerdefinierten .NET-Konverter von oben nach unten ausprobiert. Wenn eine Konvertierung gefunden wird, aber eine Ausnahme ausgelöst wird, ist die Konvertierung fehlgeschlagen.

• PSTypeConverter: Es gibt zwei Möglichkeiten, die Implementierung der PSTypeConverter Klasse mit der Zielklasse zu verknüpfen: über die Typkonfigurationsdatei (types.ps1xml) oder durch Anwenden des System.ComponentModel.TypeConverterAttribute Attributs auf die Zielklasse. Weitere Informationen finden Sie in der PowerShell SDK-Dokumentation.

• TypeConverter: Dieser CLR Typ bietet eine einheitliche Möglichkeit zum Konvertieren von Wertetypen in andere Typen sowie für den Zugriff auf Standardwerte und Untereigenschaften. Der häufigste Konvertertyp ist derjenige, der in und aus einer Textdarstellung konvertiert. Der Typkonverter für eine Klasse wird mit einem System.ComponentModel.TypeConverterAttribute an die Klasse gebunden. Sofern dieses Attribut nicht außer Kraft gesetzt wird, verwenden alle Klassen, die von dieser Klasse erben, denselben Typkonverter wie die Basisklasse. Weitere Informationen finden Sie in der PowerShell SDK und in der Dokumentation zu Microsoft .NET Framework.

• Parse-Methode: Wenn der Quelltyp Zeichenfolge ist und der Zieltyp eine Methode mit dem Namen Parsehat, wird diese Methode aufgerufen, um die Konvertierung auszuführen.

• Konstruktoren: Wenn der Zieltyp über einen Konstruktor verfügt, der ein einzelnes Argument verwendet, dessen Typ der Quelltyp ist, wird dieser Konstruktor aufgerufen, um die Konvertierung auszuführen.

• Impliziter Umwandlungsoperator: Wenn der Quelltyp über einen impliziten Umwandlungsoperator verfügt, der in den Zieltyp konvertiert wird, wird dieser Operator aufgerufen, um die Konvertierung auszuführen.

• Expliziter Umwandlungsoperator: Wenn der Quellentyp über einen expliziten Umwandlungsoperator verfügt, der in den Zieltyp konvertiert, wird dieser Operator aufgerufen, um die Konvertierung durchzuführen. Wenn der Zieltyp über einen expliziten Umwandlungsoperator verfügt, der vom Quellentyp konvertiert, wird dieser Operator aufgerufen, um die Konvertierung durchzuführen.

• IConvertable: System.Convert.ChangeType wird aufgerufen, um die Konvertierung auszuführen.

6.19 Konvertierung in ordered

Die Regeln zum Konvertieren eines beliebigen Werts in den Pseudotyp ordered lauten wie folgt:

• Ist der Wert ein Hashliteral (§2.3.5.6), ist das Ergebnis ein Objekt mit einem implementierungsdefiniertem Typ, der sich wie eine Hashtabelle verhält und die Reihenfolge der Schlüssel mit der im Hashliteral angegebenen Reihenfolge übereinstimmt.
• Andernfalls ist das Verhalten implementierungsspezifisch definiert.

Nur Hashliterale (§2.3.5.6) können in ordered konvertiert werden. Das Ergebnis ist eine Instanz von System.Collections.Specialized.OrderedDictionary.

6.20 Konversion in pscustomobject

Die Regeln zum Konvertieren eines beliebigen Werts in den Pseudo-Typ 'pscustomobject' lauten wie folgt:

• Ein Wert vom Typ Hashtable wird in ein PowerShell-Objekt konvertiert. Jeder Schlüssel in der Hashtable wird zu einem NoteProperty mit dem entsprechenden Wert.
• Andernfalls ist das Verhalten implementierungsspezifisch definiert.

Die Konvertierung ist immer zulässig, ändert jedoch nicht den Typ des Werts.