Add-Member

Add a user-defined custom member to a PowerShell object instance.

Syntax
      Add-Member -inputObject PSObject [-TypeName <String>]
         [-force] [-passThru] [CommonParameters]

      Add-Member [-NotePropertyName] String [-NotePropertyValue] Object
          -inputObject PSObject [-TypeName String]
             [-force] [-passThru] [CommonParameters]

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

      Add-Member [-memberType PSMemberType] [-name] string 
         [[-value] Object] [[-secondValue] Object]
             -inputObject PSObject [-TypeName String]
                 [-force] [-passThru] [CommonParameters]

Key
   -memberType PSMemberType
       The type of the member to add. Valid values for this are:
       {AliasProperty | CodeProperty| Property | NoteProperty | ScriptProperty
       | Properties | PropertySet | Method | CodeMethod | ScriptMethod | Methods
       | ParameterizedProperty | MemberSet | All}

   -inputObject psobject
       The object to which the new member is added. (Required)
       Enter a variable that contains the objects or type a command or 
       expression that gets the objects.

   -MemberType PSMemberTypes
       The type of the member to add. (mandatory.) 
       Valid values for this parameter are: "NoteProperty,AliasProperty,ScriptProperty,
          CodeProperty,ScriptMethod,CodeMethod" AliasProperty, CodeMethod, CodeProperty,
          Noteproperty, ScriptMethod, and ScriptProperty. 
       Not all objects have every type of member. If you specify a member type that
       the object does not have, PowerShell returns an error.

   -name string
       The name of the member to be added.

   -value Object
       The initial value of the added member. If you add an AliasProperty, CodeProperty
       ScriptProperty or CodeMethod member, you can supply optional, additional information with '-SecondValue'.

   -SecondValue Object
       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 -SecondValue 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 -SecondValue, is used to set the value of a variable.

   -NotePropertyMembers IDictionary
       A hash table or ordered dictionary of note property names and values. (PowerShell 3.0+)
       Type a hash table or dictionary in which the keys are note property names and the values are note property values.

   -NotePropertyName String
       Add a note property with the specified name. (PowerShell 3.0+)
       Use this parameter with -NotePropertyValue.

   -NotePropertyValue Object
       Add a note property with the specified value. (PowerShell 3.0+)
       Use this parameter with -NotePropertyName.

   -TypeName String
       A name for the type.
       When the type is a class in the System namespace or a type that has a type accelerator, you can enter the
       short name of the type. Otherwise, the full type name is required.  (PowerShell 3.0+)
       This parameter is effective only when the input object is a PSObject.

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

   -passThru SwitchParameter
       Pass the newly-extended object created by this cmdlet along the pipeline.
       For most objects, Add-Member adds the new members to the input object. However,
       when the input object is a string, Add-Member cannot add the member to the input object.
       For these objects, use the PassThru parameter to create an output object.
       In PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object.
       Use -PassThru to create an output object for any object that has a PSObject wrapper.

You can only add members to PSObjects. 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.

Beginning in 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 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.

To determine if a object is a PS 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 include the parameter names, the parameters can appear in any order. If you omit the parameter names, the unnamed parameter values must appear in this order: MemberType, Name, Value, SecondValue.

When specifying multiple values for a parameter, use commas to separate the values: "parameter-name value1, value2".

MemberTypes:

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.

Methods: Gets all types of methods of the object
Properties: Gets all types of properties of the object

Examples

Add a note property to a DirectoryInfo object returned by Get -ChildItem.

PS C:> $a = get-childitem c:\ps-test\test.txt     
PS C:> $a | add-member -membertype noteproperty -name MyNote -value SomeSampleText 
PS C:> $a | get-member MyNote
PS C:> $a.MyNote SomeSampleText

The above names a new property MyNote and assigns it the value: SomeSampleText.
Piping the updated object to Get-Member demonstrates that the property has been added.

For more examples run get-help Add-Member -detailed

"What we think, we become" ~ Siddhartha Gautama (Buddha)

Related PowerShell Cmdlets

Get-Member
Export-Clixml - Produce a clixml representation of PowerShell objects.
PSMemberTypes - docs.Microsoft.com


 
Copyright © 1999-2024 SS64.com
Some rights reserved