Add-Member

 

SYNOPSIS

Adds a user-defined custom member 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> | <All>} [-name] <string> [[-value] <Object>] [[-secondValue] <Object>] -inputObject <psobject> [-force] [-passThru] [<CommonParameters>]

 

DETAILED DESCRIPTION

Adds a user-defined custom member to an instance of a Windows PowerShell object. Lets you add the following types of members: AliasProperty, CodeProperty, NoteProperty, ScriptProperty, PropertySet, CodeMethod, MemberSet and ScriptMethod. You set the initial value of the member by using the Value parameter. In the case of AliasProperty, ScriptProperty, CodeProperty and CodeMethod, you can supply additional information by using the SecondValue parameter.

 

The additional members are added to the particular instance of the object that you pipe to add-member or specify using the InputObject parameter. The additional member is only available while that instance exists. You can use the Export-Clixml cmdlet to save the instance, including the additional members, to a file. The information stored in that file can be used by the Import-Clixml cmdlet to recreate the instance of the object.

 

PARAMETERS

 

-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. The valid values for this parameter are: AliasProperty, CodeProperty, NoteProperty, ScriptProperty, PropertySet, CodeMethod, MemberSet and ScriptMethod.

 

The following lists the acceptable values for this parameter:

 

·          AliasProperty

·          CodeProperty

·          Property

·          NoteProperty

·          ScriptProperty

·          Properties

·          PropertySet

·          Method

·          CodeMethod

·          ScriptMethod

·          Methods

·          ParameterizedProperty

·          MemberSet

·          All

 

Required?

true

Position?

1

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-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

Null

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

null

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 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 and the second ScriptBlock, specified in the SecondValue parameter, is used to set the value of a variable.

 

Required?

false

Position?

4

Default value

null

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-force <SwitchParameter>

Adds a new member even if one with the same name already exists. Does not work for core members of a type.

 

Required?

false

Position?

named

Default value

false

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-passThru <SwitchParameter>

Passes the newly-extended object created by this cmdlet along the pipeline. By default, this cmdlet does not pass any objects along the pipeline.

 

Required?

false

Position?

named

Default value

false

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

System.Object

 

RETURN TYPE

System.Object

 

NOTES

 

You can only add members to PSObjects. To determine if a object is a PSObject, 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.

 

For more information, type "Get-Help Add-Member -detailed". For technical information, type "Get-Help Add-Member -full".

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

EXAMPLE 1

 

$a = (get-childitem)[0]

$a | add-member -membertype noteproperty -name status -value done

$a | get-member

 

This command adds a note property to a DirectoryInfo object returned by Get-ChildItem. It names the new property status and assigns it a value of done. The last line of the command pipes the updated object to Get-Memberto demonstrate that the property has been added.

 

EXAMPLE 2

 

$a = (get-childitem)[0]

$a | add-member -membertype aliasproperty -name filelength -value length

$a.filelength

 

This command adds an alias property to a DirectoryInfo object returned by Get-ChildItem. It names the new property filelength and makes it an alias for the length property. The last line of the command returns the value of the new property.

 

EXAMPLE 3

 

$a = "a string"

$a = $a | add-member noteproperty StringUse Display -passthru

$a.StringUse

 

This command adds a property to a string. Because the string is a non-PSObject, it is necessary to specify the Passthru parameter to store the extended string back into the variable. In the final line of the command, the new property is displayed.

 

EXAMPLE 4

 

$a = "this is a string"

$a = add-member -inputobject $a -membertype scriptmethod -name words `

-value {$this.split()} -passthru

$a.words()

 

This command adds a script method to a string object. The script method exposes the Split() method of the System.String .Net Framework Class Library class to make it convenient to return the individual words in a string by called a method named words on the string object. Note that the Passthru parameter was specified to force Add-Member to return the extended string object as output to be stored in the $a variable.

 

EXAMPLE 5

 

$event = get-eventlog -logname system -newest 1

$event.TimeWritten | get-member

add-member -inputobject $event -membertype aliasproperty -name When `

-value TimeWritten -secondvalue System.String

$event.When | get-member

 

This command adds an AliasProperty to an EventLogEntry object returned by the Get-EventLogcmdlets. The AliasProperty is named 'When' and 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 line of the command uses the Get-EventLog cmdlet to retrieve the most recent event from the System event log and stores it in the $event variable. The second line of the command accesses the TimeWritten property of that event and pipes it to the Get-Member cmdlet to demonstrate that the property is a DateTime type. Add-Member is then used to add an AliasProperty member to the instance of the EventLogEntry object stored in the $event variable. The Name parameter is used to set the name of the new member to 'When' and the Value parameter is used to specify that it is an alias for the 'TimeWritten' property. The SecondValue parameter is used to indicate that, when this new member is used, the value it returns should be cast from its original System.DateTime type to a System.String type. The final line of the command accesses the new member and pipes it to the Get-Member cmdlet to confirm that it is of type System.String.

 

 

RELATED LINKS

Get-Member

Export-CLIXML

Import-CLIXML