NAME
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 | Event | All} [-Name] <string> -InputObject <psobject> [[-Value] <Object>] [[-SecondValue] <Object>] [-Force] [-PassThru] [<CommonParameters>]
DESCRIPTION
The Add-Member cmdlet adds a user-defined custom member to an instance of a Windows PowerShell object. It 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 available only 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 re-create the instance of the object.
PARAMETERS
-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
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 [<SwitchParameter>]
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 cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
“Get-Help about_CommonParameters“.
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 if 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
————————– EXAMPLE 1 ————————–
C:\PS>$a = (Get-ChildItem)[0]
C:\PS> $a | Add-Member -MemberType noteproperty -Name Status -Value done
C:\PS> $a | Get-Member -type noteproperty
TypeName: System.IO.DirectoryInfo
Name MemberType Definition
—- ———- ———-
PSChildName NoteProperty System.String PSChildName=Co
PSDrive NoteProperty System.Management.Automation
PSIsContainer NoteProperty System.Boolean PSIsContainer
PSParentPath NoteProperty System.String PSParentPath=M
PSPath NoteProperty System.String PSPath=Microso
PSProvider NoteProperty System.Management.Automation
Status NoteProperty System.String Status=done
Description
———–
These commands add the Status note property to a DirectoryInfo object returned by Get-ChildItem and assigns it a value of “done”.
The first command gets the first object that Get-ChildItem returns (index 0).
The second command adds the note property.
The third command uses a pipeline operator (|) to send the updated object to the Get-Member cmdlet. The output shows that the property has been added.
————————– EXAMPLE 2 ————————–
C:\PS>$a = (Get-ChildItem)[0]
C:\PS> $a | Add-Member -MemberType Aliasproperty -Name FileLength -Value Length
C:\PS> $a.filelength
Description
———–
These commands add the FileLength Alias property to a DirectoryInfo object returned by Get-ChildItem. The new property is an Alias for the Length property.
The first command gets the first object that Get-ChildItem returns (index 0).
The second command adds the Alias property.
The third command returns 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 words `
-Value {$this.split()} -PassThru
C:\PS> $a.words()
Description
———–
These commands add 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 calling a method named “Words” on the string object. Note that the PassThru parameter is specified to force Add-Member to return the extended string object as output to be stored in the $a Variable.
————————– EXAMPLE 5 ————————–
C:\PS>$event = Get-Eventlog -logname system -newest 1
C:\PS> $event.TimeWritten | Get-Member
C:\PS> Add-Member -InputObject $event -MemberType Aliasproperty -Name When `
-Value TimeWritten -SecondValue System.String
C:\PS> $event.When | Get-Member
Description
———–
These commands add an AliasProperty to an EventLogEntry object returned by the Get-EventLog cmdlets. 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 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 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 third command accesses the new member and pipes it to the Get-Member cmdlet to confirm that it is of type System.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.
RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113280
Get-Member
Export-Clixml
Import-Clixml