Add-Member
Fügt einer instance 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 Einem instance eines PowerShell-Objekts Member (Eigenschaften und Methoden) hinzufügen. Für instance können Sie ein NoteProperty-Element hinzufügen, das eine Beschreibung des Objekts enthält, oder einen ScriptMethod-Member, der ein Skript ausführt, um das Objekt zu ändern.
Um zu verwenden Add-Member
, übergeben Sie das -Objekt an Add-Member
, oder 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 Parameter Name 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 instance 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 instance 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 vereinfachen.
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 Status-Notizeigenschaft 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.
Der zweite Befehl fügt die Note-Eigenschaft dem -Objekt in $a
hinzu.
Der dritte Befehl verwendet die Punktnotation, um den Wert der Status-Eigenschaft des -Objekts in $a
abzurufen. Wie die Ausgabe zeigt, lautet der Wert "Done".
$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.txt
FileInfo-Objekt abzurufen.
Der zweite Befehl fügt die Eigenschaft Size alias hinzu. Der dritte Befehl verwendet die 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 StringUse-Notizeigenschaft 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 Notizeigenschaft , 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 zu einem FileInfo-Objekt hinzugefügt, das die Dateigröße auf das nächste MegaByte berechnet. Der zweite Befehl erstellt einen ScriptBlock , der die statische Round-Methode vom [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: Kopieren aller Eigenschaften eines Objekts in ein anderes Objekt
Diese Funktion kopiert alle Eigenschaften eines Objekts in ein anderes Objekt.
Die foreach
Schleife verwendet das Get-Member
Cmdlet, um jede der Eigenschaften des From-Objekts abzurufen. Die Befehle innerhalb der foreach
Schleife werden für jede der Eigenschaften in Reihe ausgeführt.
Der Add-Member
Befehl fügt die Eigenschaft des From-Objekts dem To-Objekt als NoteProperty hinzu. Der Wert wird mithilfe des Value-Parameters kopiert. Er verwendet den Force-Parameter , um Member mit demselben Membernamen hinzuzufügen.
function Copy-Property ($From, $To)
{
$properties = Get-Member -InputObject $From -MemberType Property
foreach ($p in $properties)
{
$To | Add-Member -MemberType NoteProperty -Name $p.Name -Value $From.$($p.Name) -Force
}
}
Beispiel 6: Create 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 die [ordered]
Typbeschleunigung, um ein sortiertes 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 sortierten 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 | Get-Member
TypeName: Asset
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Name NoteProperty System.String Name=Server30
PSVersion NoteProperty System.String PSVersion=4.0
System NoteProperty System.String System=Server Core
Parameter
-Force
Gibt an, dass dieses Cmdlet ein neues Element hinzufügt, auch wenn das Objekt über ein benutzerdefiniertes Element mit demselben Namen verfügt. Sie können den Force-Parameter nicht verwenden, um einen Standardmember eines Typs zu ersetzen.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
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 |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-MemberType
Gibt den Typ des hinzuzufügenden Members an. Dieser Parameter ist erforderlich. Zulässige Werte für diesen Parameter:
- NoteProperty
- 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 |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
Gibt den Namen des Members an, den dieses Cmdlet hinzufügt.
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NotePropertyMembers
Gibt eine Hashtabelle oder ein sortiertes Wörterbuch mit Hinweiseigenschaftsnamen und -werten an. Geben Sie eine Hashtabelle oder ein Wörterbuch ein, in dem die Schlüssel Hinweiseigenschaftsnamen und die Werte Hinweiseigenschaftswerte 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 |
Required: | True |
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 |
Required: | True |
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 |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Gibt ein Objekt zurück, das das Element darstellt, mit dem Sie arbeiten. Standardmäßig wird von diesem Cmdlet keine Ausgabe generiert.
Fügt für die meisten Objekte Add-Member
die neuen Member dem Eingabeobjekt hinzu.
Wenn das Eingabeobjekt jedoch eine Zeichenfolge ist, Add-Member
kann das Element nicht dem Eingabeobjekt 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 |
Required: | False |
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 in eine ganze Zahl konvertiert werden soll, wenn auf den entsprechenden AliasProperty zugegriffen wird.
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 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TypeName
Gibt einen Namen für den Typ an.
Wenn es sich bei dem Typ um eine Klasse im Systemnamespace oder um einen Typ mit typbeschleunigung handelt, 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 |
Required: | False |
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 optional zusätzliche Informationen mithilfe des SecondValue-Parameters bereitstellen.
Type: | Object |
Position: | 2 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Eingaben
Sie können einen beliebigen Objekttyp an dieses Cmdlet übergeben.
Ausgaben
None or System.Object
Wenn Sie den PassThru-Parameter verwenden, gibt dieses Cmdlet das neu erweiterte Objekt zurück. Andernfalls wird von diesem Cmdlet keine Ausgabe generiert.
Hinweise
Sie können nur PSObject-Objekten Member hinzufügen. Verwenden Sie den -is
Operator, um zu bestimmen, ob ein Objekt ein PSObject-Objekt ist.
Geben Sie für instance zum Testen eines in der $obj
Variablen gespeicherten Objekts ein$obj -is [PSObject]
.
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 instance des Objekts, dem die Eigenschaften und Methoden hinzugefügt werden. Weitere Informationen zur $this
Variablen finden Sie unter about_Automatic_Variables.