Add-Member

Fügt einer Instanz eines PowerShell-Objekts benutzerdefinierte Eigenschaften und Methoden hinzu.

Syntax

Add-Member
   -InputObject <PSObject>
   -TypeName <String>
   [-PassThru]
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [-NotePropertyMembers] <IDictionary>
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [-NotePropertyName] <String>
   [-NotePropertyValue] <Object>
   [<CommonParameters>]
Add-Member
   -InputObject <PSObject>
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]

Beschreibung

Mit Add-Member dem Cmdlet können Sie Member (Eigenschaften und Methoden) zu einer Instanz eines PowerShell-Objekts hinzufügen. Sie können beispielsweise ein NoteProperty-Element hinzufügen, das eine Beschreibung des Objekts enthält, oder ein ScriptMethod-Element , das ein Skript ausführt, um das Objekt zu ändern.

Um zu verwenden Add-Member, leiten Sie das -Objekt an Add-Memberoder verwenden Sie den InputObject-Parameter , um das Objekt anzugeben.

Der MemberType-Parameter gibt den Typ des Members an, den Sie hinzufügen möchten. Der Name-Parameter weist dem neuen Member einen Namen zu, und der Value-Parameter legt den Wert des Elements fest.

Die Eigenschaften und Methoden, die Sie hinzufügen, werden nur der angegebenen bestimmten Instanz des Objekts hinzugefügt. Add-Member ändert den Objekttyp nicht. Verwenden Sie das Add-Type Cmdlet, um einen neuen Objekttyp zu erstellen.

Sie können das Export-Clixml Cmdlet auch verwenden, um die Instanz des Objekts, einschließlich der zusätzlichen Member, in einer Datei zu speichern. Anschließend können Sie das Import-Clixml Cmdlet verwenden, um die Instanz des -Objekts aus den In der exportierten Datei gespeicherten Informationen neu zu erstellen.

Ab Windows PowerShell 3.0 verfügt über neue Features, Add-Member die das Hinzufügen von Notizeigenschaften zu Objekten erleichtern. Sie können die Parameter NotePropertyName und NotePropertyValue verwenden, um eine Hinweiseigenschaft zu definieren, oder aber den NotePropertyMembers-Parameter verwenden, der eine Hashtabelle mit Hinweiseigenschaftsnamen und -werten akzeptiert.

Ab Windows PowerShell 3.0 wird außerdem der PassThru-Parameter zum Generieren eines Ausgabeobjekts seltener benötigt. Add-Member fügt nun die neuen Member direkt dem Eingabeobjekt weiterer Typen hinzu. Weitere Informationen finden Sie in der Beschreibung zum PassThru-Parameter.

Beispiele

Beispiel 1: Hinzufügen einer Notizeigenschaft zu einem PSObject

Im folgenden Beispiel wird dem FileInfo-Objekt, das die Datei darstelltTest.txt, eine Statusnoteneigenschaft mit dem Wert "Done" hinzugefügt.

Der erste Befehl verwendet das Get-ChildItem Cmdlet, um ein FileInfo-Objekt abzurufen, das die Test.txt Datei darstellt. Sie speichert sie in der $a Variablen.

Mit dem zweiten Befehl wird dem -Objekt in $adie Note-Eigenschaft hinzugefügt.

Der dritte Befehl verwendet Punktnotation, um den Wert der Status-Eigenschaft des -Objekts in $aabzurufen. Wie die Ausgabe zeigt, ist Doneder Wert .

$A = Get-ChildItem c:\ps-test\test.txt
$A | Add-Member -NotePropertyName Status -NotePropertyValue Done
$A.Status

Done

Beispiel 2: Hinzufügen einer Aliaseigenschaft zu einem PSObject

Im folgenden Beispiel wird dem Objekt, das die Datei darstelltTest.txt, eine Size-Aliaseigenschaft hinzugefügt. Die neue Eigenschaft ist ein Alias für die Length-Eigenschaft .

Der erste Befehl verwendet das Get-ChildItem Cmdlet, um das Test.txtFileInfo-Objekt abzurufen.

Mit dem zweiten Befehl wird die Size-Aliaseigenschaft hinzugefügt. Der dritte Befehl verwendet Punktnotation, um den Wert der neuen Size-Eigenschaft abzurufen.

$A = Get-ChildItem C:\Temp\test.txt
$A | Add-Member -MemberType AliasProperty -Name Size -Value Length
$A.Size

2394

Beispiel 3: Hinzufügen einer StringUse-Notizeigenschaft zu einer Zeichenfolge

In diesem Beispiel wird einer Zeichenfolge die Notizeigenschaft StringUse hinzugefügt. Da Add-Member String-Eingabeobjekten keine Typen hinzugefügt werden können, können Sie den PassThru-Parameter angeben, um ein Ausgabeobjekt zu generieren. Der letzte Befehl im Beispiel zeigt die neue Eigenschaft an.

In diesem Beispiel wird der Parameter NotePropertyMembers verwendet. Der Wert des NotePropertyMembers-Parameters ist eine Hashtabelle. Der Schlüssel ist der Name der Notizeigenschaft , StringUse, und der Wert ist der Wert der Note-Eigenschaft , Display.

$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse

Display

Beispiel 4: Hinzufügen einer Skriptmethode zu einem FileInfo-Objekt

In diesem Beispiel wird die SizeInMB-Skriptmethode einem FileInfo-Objekt hinzugefügt, das die Dateigröße auf das nächste MegaByte berechnet. Mit dem zweiten Befehl wird ein ScriptBlock erstellt, der die statische Round-Methode aus dem [math] Typ verwendet, um die Dateigröße auf die zweite Dezimalstelle zu runden.

Der Value-Parameter verwendet auch die $This automatische Variable, die das aktuelle Objekt darstellt. Die $This Variable ist nur in Skriptblöcken gültig, die neue Eigenschaften und Methoden definieren.

Der letzte Befehl verwendet die Punktnotation, um die neue SizeInMB-Skriptmethode für das Objekt in der $A Variablen aufzurufen.

$A = Get-ChildItem C:\Temp\test.txt
$S = {[math]::Round(($this.Length / 1MB), 2)}
$A | Add-Member -MemberType ScriptMethod -Name "SizeInMB" -Value $S
$A.SizeInMB()

0.43

Beispiel 5: Erstellen eines benutzerdefinierten Objekts

In diesem Beispiel wird ein benutzerdefiniertes Asset-Objekt erstellt.

Das New-Object Cmdlet erstellt ein PSObject. Im Beispiel wird das PSObject in der $Asset Variablen gespeichert.

Der zweite Befehl verwendet den [ordered] Typbeschleuniger, um ein geordnetes Wörterbuch mit Namen und Werten zu erstellen. Der Befehl speichert das Ergebnis in der $D Variablen.

Der dritte Befehl verwendet den NotePropertyMembers-Parameter des Add-Member Cmdlets, um das Wörterbuch in der $D Variablen dem PSObject hinzuzufügen. Die TypeName-Eigenschaft weist dem PSObject den neuen Namen Asset zu.

Der letzte Befehl leitet das neue Asset-Objekt an das Get-Member Cmdlet weiter. Die Ausgabe zeigt, dass das Objekt über den Typnamen Asset und die Notizeigenschaften verfügt, die wir im geordneten Wörterbuch definiert haben.

$Asset = New-Object -TypeName PSObject
$d = [ordered]@{Name="Server30";System="Server Core";PSVersion="4.0"}
$Asset | Add-Member -NotePropertyMembers $d -TypeName Asset
$Asset.PSObject.Properties | Select-Object Name, Value

Name      Value
----      -----
Name      Server30
System    Server Core
PSVersion 4.0

Parameter

-Force

Gibt an, dass dieses Cmdlet einen neuen Member hinzufügt, auch wenn das Objekt über einen benutzerdefinierten Member mit demselben Namen verfügt. Sie können den Force-Parameter nicht verwenden, um ein Standardmember eines Typs zu ersetzen.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Gibt das Objekt an, dem das neue Element hinzugefügt wird. Geben Sie eine Variable ein, die die Objekte enthält, oder geben Sie einen Befehl oder einen Ausdruck ein, mit dem die Objekte abgerufen werden.

Type:PSObject
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-MemberType

Gibt den Typ des hinzuzufügenden Elements an. Dieser Parameter ist erforderlich. Zulässige Werte für diesen Parameter:

  • HinweisEigenschaften
  • AliasProperty
  • ScriptProperty
  • CodeProperty
  • ScriptMethod
  • CodeMethod

Informationen zu diesen Werten finden Sie unter PSMemberTypes-Enumeration im PowerShell SDK.

Nicht alle Objekte verfügen über jeden Membertyp. Wenn Sie einen Membertyp angeben, den das Objekt nicht aufweist, gibt PowerShell einen Fehler zurück.

Type:PSMemberTypes
Aliases:Type
Accepted values:AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Name

Gibt den Namen des Mitglieds an, den dieses Cmdlet hinzufügt.

Type:String
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyMembers

Gibt eine Hashtabelle oder ein sortiertes Wörterbuch an, in dem die Schlüssel Noteneigenschaftsnamen und die Werte Notizeigenschaftswerte sind.

Weitere Informationen zu Hashtabellen und geordneten Wörterbüchern in PowerShell finden Sie unter about_Hash_Tables.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Type:IDictionary
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyName

Gibt den Namen der Notizeigenschaft an.

Verwenden Sie diesen Parameter mit dem NotePropertyValue-Parameter. Dieser Parameter ist optional.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

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

-NotePropertyValue

Gibt den Wert der Note-Eigenschaft an.

Verwenden Sie diesen Parameter mit dem Parameter NotePropertyName . Dieser Parameter ist optional.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Type:Object
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Gibt ein Objekt zurück, das das Element darstellt, mit dem Sie arbeiten. Standardmäßig generiert dieses Cmdlet keine Ausgabe.

Für die meisten Objekte Add-Member fügt das Eingabeobjekt die neuen Member hinzu. Wenn das Eingabeobjekt jedoch eine Zeichenfolge ist, Add-Member kann das Element dem Eingabeobjekt nicht hinzugefügt werden. Verwenden Sie für diese den PassThru-Parameter, um ein Ausgabeobjekt zu erstellen.

In Windows PowerShell 2.0 Add-Member wurden Member nur dem PSObject-Wrapper von -Objekten und nicht dem -Objekt hinzugefügt. Verwenden Sie den PassThru-Parameter , um ein Ausgabeobjekt für jedes Objekt zu erstellen, das über einen PSObject-Wrapper verfügt.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-SecondValue

Gibt optionale weitere Informationen zu AliasProperty-, ScriptProperty-, CodeProperty- oder CodeMethod-Elementen an.

Wenn beim Hinzufügen einer AliasProperty-Eigenschaft verwendet wird, muss dieser Parameter ein Datentyp sein. Dem Wert von AliasProperty wird eine Konvertierung in den angegebenen Datentyp hinzugefügt.

Wenn Sie beispielsweise einen AliasProperty-Wert hinzufügen, der einen alternativen Namen für eine Zeichenfolgeneigenschaft bereitstellt, können Sie auch einen SecondValue-Parameter von System.Int32 angeben, um anzugeben, dass der Wert dieser Zeichenfolgeneigenschaft beim Zugriff mit dem entsprechenden AliasProperty in eine ganze Zahl konvertiert werden soll.

Sie können den SecondValue-Parameter verwenden, um beim Hinzufügen eines ScriptProperty-Elements einen zusätzlichen ScriptBlock anzugeben. Der erste ScriptBlock, der im Value-Parameter angegeben ist, wird verwendet, um den Wert einer Variablen abzurufen. Der zweite ScriptBlock, der im SecondValue-Parameter angegeben wird, wird verwendet, um den Wert einer Variablen festzulegen.

Type:Object
Position:3
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TypeName

Gibt einen Namen für den Typ an.

Wenn der Typ eine Klasse im Systemnamespace oder ein Typ mit typbeschleunigung ist, können Sie den kurzen Namen des Typs eingeben. Für andere Typen ist der vollständige Typname erforderlich. Dieser Parameter ist nur wirksam, wenn das InputObject ein PSObject ist.

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Value

Gibt den Anfangswert des hinzugefügten Elements an. Wenn Sie ein AliasProperty-, CodeProperty-, ScriptProperty- oder CodeMethod-Element hinzufügen, können Sie mithilfe des SecondValue-Parameters zusätzliche Informationen bereitstellen.

Type:Object
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Eingaben

PSObject

Sie können jeden Beliebigen Objekttyp an dieses Cmdlet weiterleiten.

Ausgaben

None or System.Object

Wenn Sie den PassThru-Parameter verwenden, gibt dieses Cmdlet das neu erweiterte Objekt zurück. Andernfalls generiert dieses Cmdlet keine Ausgabe.

Hinweise

Sie können Elemente nur Objekten vom Typ PSObject hinzufügen. Verwenden Sie den -is Operator, um zu bestimmen, ob es sich bei einem Objekt um ein PSObject-Objekt handelt.

PSObject-Typobjekte verwalten ihre Liste der Member in der Reihenfolge, in der die Member dem -Objekt hinzugefügt wurden.

Geben $obj -is [psobject]Sie beispielsweise ein, um ein in der $obj Variablen gespeichertes Objekt zu testen.

Die Namen der Parameter MemberType, Name, Value und SecondValue sind optional. Wenn Sie die Parameternamen weglassen, müssen die unbenannten Parameterwerte in der folgenden Reihenfolge angezeigt werden: MemberType, Name, Value und SecondValue.

Wenn Sie die Parameternamen angeben, können die Parameter in beliebiger Reihenfolge angegeben werden.

Sie können die $this automatische Variable in Skriptblöcken verwenden, die die Werte neuer Eigenschaften und Methoden definieren. Die $this Variable bezieht sich auf die Instanz des Objekts, dem die Eigenschaften und Methoden hinzugefügt werden. Weitere Informationen zur $this Variablen finden Sie unter about_Automatic_Variables.