Add-Member

Add-Member
    -InputObject <PSObject>
    -TypeName <String>
    [-PassThru]
    [<CommonParameters>]

Add-Member
    [-NotePropertyMembers] <IDictionary>
    -InputObject <PSObject>
    [-TypeName <String>]
    [-Force]
    [-PassThru]
    [<CommonParameters>]

Add-Member
    [-NotePropertyName] <String>
    [-NotePropertyValue] <Object>
    -InputObject <PSObject>
    [-TypeName <String>]
    [-Force]
    [-PassThru]
    [<CommonParameters>]

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

The Add-Member cmdlet lets you add members (properties and methods) to an instance of a PowerShell object. For instance, you can add a NoteProperty member that contains a description of the object or a ScriptMethod member that runs a script to change the object.

To use Add-Member, pipe the object to Add-Member, or use the InputObject parameter to specify the object.

The MemberType parameter indicates the type of member that you want to add. The Name parameter assigns a name to the new member, and the Value parameter sets the value of the member.

The properties and methods that you add are added only to the particular instance of the object that you specify. Add-Member does not change the object type. To create a new object type, use the Add-Type cmdlet.

You can also use the Export-Clixml cmdlet to save the instance of the object, including the additional members, in a file. Then you can use the Import-Clixml cmdlet to re-create the instance of the object from the information that is stored in the exported file.

Beginning in Windows PowerShell 3.0, Add-Member has new features that make it easier to add note properties to objects. You can use the NotePropertyName and NotePropertyValue parameters to define a note property or use the NotePropertyMembers parameter, which takes a hash table of note property names and values.

Also, beginning in Windows PowerShell 3.0, the PassThru parameter, which generates an output object, is needed less frequently. Add-Member now adds the new members directly to the input object of more types. For more information, see the PassThru parameter description.

The following example adds a Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file.

The first command uses the Get-ChildItem cmdlet to get a FileInfo object representing the Test.txt file. It saves it in the $a variable.

The second command adds the note property to the object in $a.

The third command uses dot notation to get the value of the Status property of the object in $a. As the output shows, the value is "Done".

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

Done

The following example adds a Size alias property to the object that represents the Test.txt file. The new property is an alias for the Length property.

The first command uses the Get-ChildItem cmdlet to get the Test.txt FileInfo object.

The second command adds the Size alias property. The third command uses dot notation to get the value of the new Size property.

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

2394

This example adds the StringUse note property to a string. Because Add-Member cannot add types to String input objects, you can specify the PassThru parameter to generate an output object. The last command in the example displays the new property.

This example uses the NotePropertyMembers parameter. The value of the NotePropertyMembers parameter is a hash table. The key is the note property name, StringUse, and the value is the note property value, Display.

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

Display

This example adds the SizeInMB script method to a FileInfo object which calculates the file size to the nearest MegaByte. The second command creates a ScriptBlock that uses the Round static method from the [math] type to round the file size to the second decimal place.

The Value parameter also uses the $This automatic variable, which represents the current object. The $This variable is valid only in script blocks that define new properties and methods.

The last command uses dot notation to call the new SizeInMB script method on the object in the $A variable.

$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

This function copies all of the properties of one object to another object.

The foreach loop uses the Get-Member cmdlet to get each of the properties of the From object. The commands within the foreach loop are performed in series on each of the properties.

The Add-Member command adds the property of the From object to the To object as a NoteProperty. The value is copied using the Value parameter. It uses the Force parameter to add members with the same member name.

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
    }
}

This example creates an Asset custom object.

The New-Object cmdlet creates a PSObject. The example saves the PSObject in the $Asset variable.

The second command uses the [ordered] type accelerator to create an ordered dictionary of names and values. The command saves the result in the $D variable.

The third command uses the NotePropertyMembers parameter of the Add-Member cmdlet to add the dictionary in the $D variable to the PSObject. The TypeName property assigns a new name, Asset, to the PSObject.

The last command pipes the new Asset object to the Get-Member cmdlet. The output shows that the object has a type name of Asset and the note properties that we defined in the ordered dictionary.

$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

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

You can pipe any object type to this cmdlet.

When you use the PassThru parameter, this cmdlet returns the newly-extended object. Otherwise, this cmdlet does not generate any output.

You can add members only to PSObject objects. To determine whether an object is a PSObject object, use the -is operator.

For instance, to test an object stored in the $obj variable, type $obj -is [PSObject].

The names of the MemberType, Name, Value, and SecondValue parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: MemberType, Name, Value, and SecondValue.

If you include the parameter names, the parameters can appear in any order.

You can use the $this automatic variable in script blocks that define the values of new properties and methods. The $this variable refers to the instance of the object to which the properties and methods are being added. For more information about the $this variable, see about_Automatic_Variables.