Add-Member

Applies To: Windows PowerShell 2.0

Adds custom properties and methods to an instance of a Windows PowerShell object.

Syntax

Add-Member [-MemberType] {<AliasProperty> | <CodeProperty> | <Property> | <NoteProperty> | <ScriptProperty> | <Properties> | <PropertySet> | <Method> | <CodeMethod> | <ScriptMethod> | <Methods> | <ParameterizedProperty> | <MemberSet> | <Event> | <All>} [-Name] <string> [[-Value] <Object>] [[-SecondValue] <Object>] -InputObject <psobject> [-Force] [-PassThru] [<CommonParameters>]

Description

The Add-Member cmdlet lets you add members (properties and methods) to an instance of a Windows PowerShell object. For example, 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. Use the MemberType parameter to specify the type of member that you want to add, use the Name parameter to assign a name to the new member, and use the Value parameter to set 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.

Parameters

-Force

Adds a new member even the object has a custom member with the same name. You cannot use the Force parameter to replace a standard member of a type.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-InputObject <psobject>

Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.

Required?	true
Position?	named
Default Value
Accept Pipeline Input?	true (ByValue)
Accept Wildcard Characters?	false

-MemberType <PSMemberTypes>

Specifies the type of the member to add. This parameter is mandatory.

The valid values for this parameter are:

-- AliasProperty: A property that defines a new name for an existing property.

-- CodeMethod: A method that references a static method of a Microsoft .NET Framework class.

-- CodeProperty: A property that references a static property of a .NET Framework class.

-- MemberSet: A predefined collection of properties and methods, such as PSBase, PSObject, and PSTypeNames.

-- Method: A method of the underlying .NET Framework object.

-- NoteProperty: A property with a static value.

-- ParameterizedProperty: A property that takes parameters and parameter values.

-- Property: A property of the underlying .NET Framework object.

-- PropertySet: A predefined collection of object properties.

-- ScriptMethod: A method whose value is the output of a script.

-- ScriptProperty: A property whose value is the output of a script.

-- All: Gets all member types.

-- Methods: Gets all types of methods of the object (e.g. method, codemethod, scriptmethod)

-- Properties: Gets all types of properties of the object (e.g. property, codeproperty, aliasproperty, scriptproperty).

Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns an error.

The Event member type is not valid for Add-Member.

Required?	true
Position?	1
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	true

-Name <string>

Specifies the name of the member to be added.

If you omit the "Name" parameter name, the value of the -Name parameter must be the second unnamed parameter value in the command. If you include the parameter name, the parameters can appear in any order.

Required?	true
Position?	2
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PassThru

Passes the newly extended object to the pipeline. By default, this cmdlet does not generate any output.

Required?	false
Position?	named
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-SecondValue <Object>

Specifies optional additional information about AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members. If used when adding an AliasProperty, this parameter must be a data type. A conversion (cast) to the specified data type is added to the value of the AliasProperty. For example, if you add an AliasProperty that provides an alternate name for a string property, you can also specify a SecondValue parameter of System.Int32 to indicate that the value of that string property should be converted to an integer when accessed by using the corresponding AliasProperty.

You can use the SecondValue parameter to specify an additional ScriptBlock when adding a ScriptProperty member. In that case, the first ScriptBlock, specified in the Value parameter, is used to get the value of a variable. The second ScriptBlock, specified in the SecondValue parameter, is used to set the value of a variable.

Required?	false
Position?	4
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-Value <Object>

Specifies the initial value of the added member. If you add an AliasProperty, CodeProperty, or CodeMethod member, you can supply optional, additional information by using the SecondValue parameter.

Required?	false
Position?	3
Default Value
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This command supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, and WarningVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

Inputs	System.Management.Automation.PSObject You can pipe any object type to Add-Member.
Outputs	None or System.Object When you use the PassThru parameter, Add-Member returns the newly-extended object. Otherwise, this cmdlet does not generate any output.

Notes

You can add members only to PSObject objects. To determine whether an object is a PSObject object, use the "is" operator. For example, 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, 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.

Example 1

C:\PS>$a = dir c:\ps-test\test.txt

C:\PS> $a | add-member -membertype noteproperty -name Status -value Done

C:\PS> $a.Status

Done

Description
-----------
These commands add the Status note property with a value of "Done" to the object that represents the Test.txt file. 

The first command uses the Get-ChildItem cmdlet (alias = "dir) to get 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".

Example 2

C:\PS>$a = dir c:\ps-test\test.txt

C:\PS> $a | add-member -membertype aliasproperty -name FileLength -value Length 

C:\PS> $a.filelength

Description
-----------
These commands add the FileLength alias property to the object that represents the Test.txt file. The new property is an alias for the Length property. 

The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file.

The second command adds the FileLength alias property.

The third command uses dot notation to get the value of the new FileLength property.

Example 3

C:\PS>$a = "a string"

C:\PS> $a = $a | add-member -membertype noteproperty -name StringUse -value Display -passthru

C:\PS> $a.StringUse

Description
-----------
These commands add the StringUse a property to a string. Because the string is not a PSObject object, you must include the PassThru parameter in the command to save the extended string in the variable. The last command in the example displays the new property.

Example 4

C:\PS>$a = "This is a string."

C:\PS> $a = add-member -inputobject $a -membertype ScriptMethod -name PadBoth -value {$p = $this.padleft($this.length + 1); $p.padright($p.length + 1)} -passthru

C:\PS> $a.Padboth()

 This is a string.

Description
-----------
These commands add the PadBoth script method to a string object. 

The first command creates a string and saves it in the $a variable.

The second command adds the Padboth script method to the object in the $a variable. The Value parameter defines the new script method. It uses the PadRight and PadLeft methods of a string to add one space the left and one space to the right of the string. 

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 command includes the Passthru parameter which directs Add-Member to return an instance of the object that includes the new script property. By default, Add-Member does not generate any output.

The third command uses dot notation to call the new Words script method on the object in the $a variable.

Example 5

C:\PS>$event = get-eventlog -logname system -newest 1

C:\PS> $event.TimeWritten | get-member

   TypeName: System.DateTime

Name                 MemberType     Definition
----                 ----------     ----------
Add                  Method         System.DateTime Add(System.TimeSpan value)
AddDays              Method         System.DateTime AddDays(double value)
AddHours             Method         System.DateTime AddHours(double value)
AddMilliseconds      Method         System.DateTime AddMilliseconds(double value)
AddMinutes           Method         System.DateTime AddMinutes(double value)
...

C:\PS> add-member -inputobject $event -membertype aliasproperty -name When -value TimeWritten -secondvalue System.String

C:\PS> $event.When | get-member

   TypeName: System.String

Name             MemberType            Definition
----             ----------            ----------
Clone            Method                System.Object Clone()
CompareTo        Method                int CompareTo(System.Object value), int CompareTo(string strB)
Contains         Method                bool Contains(string value)

Description
-----------
These commands add the "When" alias property to an event in the System event log. The event is an EventLogEntry object that is returned by the Get-EventLog cmdlet. 

The "When" alias property is an alias for the TimeWritten property of the object. The SecondValue parameter is used to specify that the property value should be converted to type System.String when accessed by using the AliasProperty. The TimeWritten property is a DateTime object.

The first command uses the Get-EventLog cmdlet to get the newest event in the System event log. It stores the event in the $event variable. 

The second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet to demonstrate that the property is a DateTime type. 

The third command uses the Add-Member cmdlet to add the When alias property to the object instance in the $event variable. The Name parameter assigns the name, "When," and the Value parameter specifies that When is an alias for the TimeWritten property. The SecondValue parameter indicates that the value that the When method returns should be cast to a System.String type. 

The fourth command uses dot notation to call the new When method. The command pipes the method value to the Get-Member cmdlet to confirm that it has returned a string.

Example 6

C:\PS>function Copy-Property ($From, $To)

{
  foreach ($p in Get-Member -InputObject $From -MemberType Property)
  {
     Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name 
     -Value $From.$($p.Name) -Force

     $To.$($p.Name) = $From.$($p.Name)
   }
}

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

The first command in the function declares the function name and lists its parameters. 

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. It uses the Force parameter to let the command add members with the same member name.

The last command in the function gives the new property the same name as the original property.

See Also

Concepts

about_Automatic_Variables
Get-Member
Export-Clixml
Import-Clixml