Freigeben über

Add-Member

  • Referenz
Modul:
Microsoft.PowerShell.Utility

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

Um das Objekt zu verwenden Add-Member, führen Sie das Objekt Add-Memberan, oder verwenden Sie den InputObject-Parameter , um das Objekt anzugeben.

Der MemberType-Parameter gibt den Elementtyp an, den Sie hinzufügen möchten. Der Parameter Name weist dem neuen Element 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 Informationen, die in der exportierten Datei gespeichert sind, neu zu erstellen.

Ab Windows PowerShell 3.0 gibt es neue Features, Add-Member die das Hinzufügen von Notizeigenschaften zu Objekten erleichtern. Sie können die Parameter "NotePropertyName" und "NotePropertyValue" verwenden, um eine Notizeigenschaft zu definieren oder den Parameter "NotePropertyMembers" zu verwenden, der eine Hashtabelle mit Namen und Werten von Notizeigenschaften verwendet.

Ab Windows PowerShell 3.0 wird auch der PassThru-Parameter, der ein Ausgabeobjekt generiert, weniger häufig benötigt. Add-Member fügt nun die neuen Member direkt zum Eingabeobjekt weiterer Typen hinzu. Weitere Informationen finden Sie in der PassThru-Parameterbeschreibung .

Beispiele

Beispiel 1: Hinzufügen einer Notizeigenschaft zu einem PSObject

Im folgenden Beispiel wird dem FileInfo-Objekt, das die Test.txt Datei darstellt, 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.

Mit dem zweiten Befehl wird dem Objekt die Notizeigenschaft hinzugefügt.$a

Der dritte Befehl verwendet die Punktnotation, um den Wert der Status-Eigenschaft des Objekts in $aabzurufen. Wie die Ausgabe zeigt, lautet 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 Test.txt Datei darstellt, eine Size-Aliaseigenschaft hinzugefügt. Die neue Eigenschaft ist ein Alias für die Length-Eigenschaft .

Der erste Befehl verwendet das Get-ChildItem Cmdlet zum Abrufen des Test.txt FileInfo-Objekts .

Der zweite Befehl fügt die Size-Aliaseigenschaft 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 der StringUse-Notizeigenschaft eine Zeichenfolge hinzugefügt. Da Add-Member Zeichenfolgeneingabeobjekte keine Typen hinzufügen 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 Parameters NotePropertyMembers 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 Round static-Methode aus dem [math] Typ verwendet, um die Dateigröße auf die zweite Dezimalstelle zu runden.

Der Parameter Value 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 Objekt "Asset " erstellt.

Das New-Object Cmdlet erstellt ein PSObject , das in der $Asset Variablen gespeichert ist. Die [ordered] Typbeschleuniger erstellt ein geordnetes Wörterbuch, das in der $d Variablen gespeichert ist. Durch $Asset Die Weiterleitung werden Add-Member dem Objekt die Schlüsselwertpaare im Wörterbuch als NoteProperty-Elemente hinzugefügt. Der TypeName-Parameter weist dem PSObject den Typ Asset zu. Das Get-Member Cmdlet zeigt den Typ und die Eigenschaften des Objekts an. Die Eigenschaften werden jedoch in alphabetischer Reihenfolge aufgeführt, nicht in der Reihenfolge, in der sie hinzugefügt wurden.

$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 -MemberType Properties

TypeName: Asset

Name        MemberType   Definition
----        ----------   ----------
Name        NoteProperty string Name=Server30
PSVersion   NoteProperty string PSVersion=4.0
System      NoteProperty string System=Server Core

$Asset.PSObject.Properties | Format-Table Name, MemberType, TypeNameOfValue, Value

Name        MemberType TypeNameOfValue Value
----        ---------- --------------- -----
Name      NoteProperty System.String   Server30
System    NoteProperty System.String   Server Core
PSVersion NoteProperty System.String   4.0

Beim Überprüfen der unformatierten Liste der Eigenschaften werden die Eigenschaften in der Reihenfolge angezeigt, in der sie dem Objekt hinzugefügt wurden. Format-Table wird in diesem Beispiel verwendet, um die Ausgabe ähnlich zu Get-Membererstellen.

Beispiel 6: Hinzufügen einer AliasProperty zu einem Objekt

In diesem Beispiel wird ein benutzerdefiniertes Objekt erstellt, das zwei NoteProperty-Elemente enthält. Der Typ für ein NoteProperty gibt den Typ des in der Eigenschaft gespeicherten Werts wieder. In diesem Fall ist die Age-Eigenschaft eine Zeichenfolge.

PS> $obj = [pscustomobject]@{
      Name = 'Doris'
      Age = '20'
}
PS> $obj | Add-Member -MemberType AliasProperty -Name 'intAge' -Value age -SecondValue uint32
PS> $obj | Get-Member

   TypeName: System.Management.Automation.PSCustomObject

Name        MemberType    Definition
----        ----------    ----------
intAge      AliasProperty intAge = (System.UInt32)age
Equals      Method        bool Equals(System.Object obj)
GetHashCode Method        int GetHashCode()
GetType     Method        type GetType()
ToString    Method        string ToString()
Age         NoteProperty  string Age=20
Name        NoteProperty  string Name=Doris

PS> $obj

Name  Age intAge
----  --- ------
Doris 20      20

PS> $obj.Age + 1

201

PS> $obj.intAge + 1

21

Die intAge-Eigenschaft ist ein AliasProperty für die Age-Eigenschaft , der Typ ist jedoch garantiert uint32.

Beispiel 7: Hinzufügen von Get- und Set-Methoden zu einem benutzerdefinierten Objekt

In diesen Beispielen wird gezeigt, wie Get- und Set-Methoden definiert werden, die auf eine tief geschachtelte Eigenschaft zugreifen.

$user = [pscustomobject]@{
    Name      = 'User1'
    Age       = 29
    StartDate = [datetime]'2019-05-05'
    Position  = [pscustomobject]@{
        DepartmentName = 'IT'
        Role = 'Manager'
    }
}
$addMemberSplat = @{
    MemberType = 'ScriptProperty'
    Name = 'Title'
    Value = { $this.Position.Role }                  # getter
    SecondValue = { $this.Position.Role = $args[0] } # setter
}
$user | Add-Member @addMemberSplat
$user | Get-Member

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType     Definition
----        ----------     ----------
Equals      Method         bool Equals(System.Object obj)
GetHashCode Method         int GetHashCode()
GetType     Method         type GetType()
ToString    Method         string ToString()
Age         NoteProperty   int Age=29
Name        NoteProperty   string Name=User1
Position    NoteProperty   System.Management.Automation.PSCustomObject Position=@{DepartmentName=IT; Role=Manager}
StartDate   NoteProperty   datetime StartDate=5/5/2019 12:00:00 AM
Title       ScriptProperty System.Object Title {get= $this.Position.Role ;set= $this.Position.Role = $args[0] ;}

$user.Title = 'Dev Manager'

Name      : User1
Age       : 29
StartDate : 5/5/2019 12:00:00 AM
Position  : @{DepartmentName=IT; Role=Dev Manager}
Title     : Dev Manager

Beachten Sie, dass die Title-Eigenschaft ein ScriptProperty-Objekt ist, das über eine Get - und Set-Methode verfügt. Wenn wir der Title-Eigenschaft einen neuen Wert zuweisen, wird die Set-Methode aufgerufen und ändert den Wert der Role-Eigenschaft in der Position-Eigenschaft .

Parameter

-Force

Standardmäßig kann kein neues Element hinzugefügt werden, Add-Member wenn das Objekt bereits über ein Element mit demselben verfügt. Wenn Sie den Parameter Force verwenden, Add-Member wird das vorhandene Element durch das neue Element ersetzt. Sie können den Parameter Force nicht verwenden, um ein Standardelement eines Typs zu ersetzen.

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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.

Typ:PSObject
Position:Named
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:True
Platzhalterzeichen akzeptieren:False

-MemberType

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

  • AliasProperty
  • CodeMethod
  • CodeProperty
  • NoteProperty
  • ScriptMethod
  • ScriptProperty

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

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

Typ:PSMemberTypes
Aliase:Type
Zulässige Werte:AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Name

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

Typ:String
Position:1
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-NotePropertyMembers

Gibt ein Hashtable- oder geordnetes Wörterbuch an, das Schlüsselwertpaar enthält, das NoteProperty-Namen und deren Werte darstellt. 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.

Typ:IDictionary
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-NotePropertyName

Gibt den Namen der Notizeigenschaft an.

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

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:String
Position:0
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-NotePropertyValue

Gibt den Wert der Notizeigenschaft an.

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

Dieser Parameter wurde in Windows PowerShell 3.0 eingeführt.

Typ:Object
Position:1
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 werden dem Eingabeobjekt die neuen Elemente hinzugefügt. Wenn das Eingabeobjekt jedoch eine Zeichenfolge ist, Add-Member kann das Element nicht zum Eingabeobjekt hinzugefügt werden. Verwenden Sie für diese Objekte den PassThru-Parameter , um ein Ausgabeobjekt zu erstellen.

In Windows PowerShell 2.0 wurden Add-Member Elemente 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.

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-SecondValue

Gibt optionale zusätzliche Informationen zu AliasProperty-, ScriptProperty- oder CodeProperty-Elementen an.

Wenn sie beim Hinzufügen eines AliasProperty-Elements 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 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 bei Verwendung der entsprechenden AliasProperty in eine ganze Zahl konvertiert werden soll.

Bei einer CodeProperty muss der Wert ein Verweis auf eine Methode sein, die einen Set-Accessor implementiert. Verwenden Sie die GetMethod() Methode eines Typverweises, um einen Verweis auf eine Methode abzurufen. Die Methode muss einen einzelnen Parameter verwenden, der ein PSObject ist. Der Get-Accessor wird mithilfe des Value-Parameters zugewiesen.

Für ein ScriptProperty muss der Wert ein Skriptblock sein, der einen Set-Accessor implementiert. Der Get-Accessor wird mithilfe des Value-Parameters zugewiesen.

Typ:Object
Position:3
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-TypeName

Gibt einen Namen für den Typ an.

Wenn der Typ eine Klasse im Systemnamespace oder ein Typ ist, der über eine Typbeschleuniger verfügt, 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.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Value

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

  • Bei einer AliasProperty muss der Wert der Name der Eigenschaft sein, die aliased wird.
  • Bei einem CodeMethod muss der Wert ein Verweis auf eine Methode sein. Verwenden Sie die GetMethod() Methode eines Typverweises, um einen Verweis auf eine Methode abzurufen.
  • Bei einer CodeProperty muss der Wert ein Verweis auf eine Methode sein, die einen Get-Accessor implementiert. Verwenden Sie die GetMethod() Methode eines Typverweises, um einen Verweis auf eine Methode abzurufen. Referenz. Die Methode muss einen einzelnen Parameter verwenden, der ein PSObject ist. Der Set-Accessor wird mithilfe des SecondValue-Parameters zugewiesen.
  • Bei einem ScriptMethod muss der Wert ein Skriptblock sein.
  • Für ein ScriptProperty muss der Wert ein Skriptblock sein, der einen Get-Accessor implementiert. Der Set-Accessor wird mithilfe des SecondValue-Parameters zugewiesen.
Typ:Object
Position:2
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

Eingaben

PSObject

Sie können jedes Objekt an dieses Cmdlet weiterleiten.

Ausgaben

None

Standardmäßig gibt dieses Cmdlet keine Ausgabe zurück.

Object

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

Hinweise

Sie können Nur Elemente zu PSObject-Typobjekten hinzufügen. Verwenden Sie den -is Operator, um zu bestimmen, ob ein Objekt ein PSObject-Objekt ist. Um beispielsweise ein objekt zu testen, das in der $obj Variablen gespeichert ist, geben Sie folgendes ein $obj -is [psobject].

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

Die Namen der Parameter "MemberType", "Name", "Value" und "SecondValue" sind optional. Wenn Sie die Parameternamen weglassen, müssen die werte für nicht benannte Parameter in dieser 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, zu der die Eigenschaften und Methoden hinzugefügt werden. Weitere Informationen zur $this Variablen finden Sie unter about_Automatic_Variables.