From 7ff096b09ccf2411d880110e248f84444f0010fc Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Fri, 26 Apr 2019 11:23:12 -0400 Subject: [PATCH 1/2] Fixes #4220 - Fix Example 6 (Copy Property) --- .../Add-Member.md | 379 +++++++++--------- .../Add-Member.md | 363 ++++++++--------- .../Add-Member.md | 355 ++++++++-------- .../Add-Member.md | 379 +++++++++--------- .../Add-Member.md | 350 ++++++++-------- 5 files changed, 891 insertions(+), 935 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md index 1fd18a784121..eae7f14df6b0 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -1,5 +1,5 @@ ---- -ms.date: 06/09/2017 +--- +md.date: 4/26/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,7 +10,6 @@ title: Add-Member # Add-Member ## SYNOPSIS - Adds custom properties and methods to an instance of a Windows PowerShell object. ## SYNTAX @@ -49,189 +48,173 @@ Add-Member [-NotePropertyMembers] ## 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. +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. -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. +To use `Add-Member`, pipe the object to `Add-Member`, or use the **InputObject** parameter to +specify the object. -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. +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. -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. +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. -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. +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. -## EXAMPLES +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. -### Example 1 +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. -``` -PS> $a = dir c:\ps-test\test.txt -PS> $a | Add-Member -NotePropertyName Status -NotePropertyValue Done -PS> $a | Add-Member Status Done -PS> $a.Status -Done -``` +## EXAMPLES -These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file. +### Example 1: Add a note property to a PSObject -The first command uses the Get-ChildItem cmdlet (alias = "dir) to get the Test.txt file. -It saves it in the $a variable. +The following example adds a **Status** note property with a value of "Done" to the **FileInfo** +object that represents the `Test.txt` file. -The second and third commands add the note property to the object in $a. -The third command omits the optional parameter names, so the parameter values must be in the correct Name-Value order. -These commands are equivalent and can be used interchangeably. +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 fourth 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". +The second command adds the note property to the object in `$a`. -### Example 2 +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". -``` -PS> $a = dir c:\ps-test\test.txt -PS> $a | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS> $a.FileLength -2394 +```powershell +$A = Get-ChildItem c:\ps-test\test.txt +$A | Add-Member -NotePropertyName Status -NotePropertyValue Done +$A.Status ``` -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. +```Output +Done +``` -The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file. +### Example 2: Add an alias property to a PSObject -The second command adds the FileLength alias property. +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 third command uses dot notation to get the value of the new FileLength property. +The first command uses the `Get-ChildItem` cmdlet to get the `Test.txt` **FileInfo** object. -### Example 3 +The second command adds the **Size** alias property. +The third command uses dot notation to get the value of the new **Size** property. +```powershell +$A = Get-ChildItem C:\Temp\test.txt +$A | Add-Member -MemberType AliasProperty -Name Size -Value Length +$A.Size ``` -PS> $a = "A string" -PS> $a = $a | Add-Member @{StringUse="Display"} -PassThru -PS> $a.StringUse -Display + +```Output +2394 ``` -These commands add the **StringUse** note property to a string. -Because Add-Member cannot add types to String input objects, the command uses the **PassThru** parameter to generate an output object. -The last command in the example displays the new property. +### Example 3: Add a StringUse note property to a string -The command uses the **NotePropertyMembers** parameter, but omits the parameter name, which is optional. -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. +This example adds the **StringUse** note property to a string. +Because `Add-Member` cannot add types to **String** input objects, you can speciy the **PassThru** +parameter to generate an output object. The last command in the example displays the new property. -### Example 4 +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**. -``` -PS> $a = "This is a string." -PS> $a = Add-Member -InputObject $a -MemberType ScriptMethod -Name PadBoth -Value {$p = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -PS> $a.Padboth() -This is a string. +```powershell +$A = "A string" +$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru +$A.StringUse ``` -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. +```Output +Display +``` -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. +### Example 4: Add a script method to a FileInfo object -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** adds members to PSObjects and does not generate any output. +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 third command uses dot notation to call the new PadBoth script method on the object in the $a variable. +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. -### Example 5 +The last command uses dot notation to call the new **SizeInMB** script method on the object in the +`$A` variable. -``` -PS> $event = Get-EventLog -LogName System -Newest 1 -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)... - - -PS> Add-Member -InputObject $event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -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) +```powershell +$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() ``` -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. +```Output +0.43 +``` -To demonstrate that the TimeWritten property is a DateTime type, the second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet. +### Example 5: Copy all properties of an object to another -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. +This function copies all of the properties of one object to another object. -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. +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. -### Example 6 +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. -``` -PS> function Copy-Property ($From, $To) +```powershell +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) - } + $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 function copies all of the properties of one object to another object. +### Example 6: Create a custom object -The first command in the function declares the function name and lists its parameters. +This example creates an **Asset** custom 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 `New-Object` cmdlet creates a **PSObject**. The example saves the **PSObject** in the `$Asset` +variable. -The **Add-Member** command adds the property of the From object to the To object as a NoteProperty. -It uses the **Force** parameter add members with the same member name. +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 last command in the function gives the new property the same name as the original property. +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**. -### Example 7 +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. +```powershell +$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 ``` -PS> $Asset = New-Object -TypeName PSObject -PS> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="3.0"} -PS> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset -PS> $Asset | Get-Member - TypeName: Asset +```Output + TypeName: Asset + Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) @@ -239,30 +222,16 @@ GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() Name NoteProperty System.String Name=Server30 -PSVersion NoteProperty System.String PSVersion=3.0 +PSVersion NoteProperty System.String PSVersion=4.0 System NoteProperty System.String System=Server Core ``` -This example creates the Asset custom object. - -The first command uses the New-Object cmdlet to create a PSObject. -The command 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. -It uses the **TypeName** property to assign a new name, Asset, to the PSObject. - -The fourth command sends the new Asset object in the $Asset variable 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. - ## 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. +Indicates that this cmdlet 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. ```yaml Type: SwitchParameter @@ -296,19 +265,27 @@ Accept wildcard characters: False ### -MemberType Specifies the type of the member to add. -This parameter is mandatory. +This parameter is required. +The acceptable values for this parameter are: -The valid values for this parameter are: "NoteProperty,AliasProperty,ScriptProperty,CodeProperty,ScriptMethod,CodeMethod" **AliasProperty**, **CodeMethod**, **CodeProperty**, **Noteproperty**, **ScriptMethod**, and **ScriptProperty**. +- NoteProperty +- AliasProperty +- ScriptProperty +- CodeProperty +- ScriptMethod +- CopyMethod -For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) in the MSDN library. +For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) +in the MSDN library. 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. +If you specify a member type that the object does not have, PowerShell returns an error. ```yaml Type: PSMemberTypes Parameter Sets: MemberSet Aliases: Type +Accepted values: AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All Required: True Position: 0 @@ -319,7 +296,7 @@ Accept wildcard characters: True ### -Name -Specifies the name of the member to be added. +Specifies the name of the member that this cmdlet adds. ```yaml Type: String @@ -335,15 +312,17 @@ Accept wildcard characters: False ### -PassThru -Returns the newly extended object. +Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. -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 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 Windows PowerShell 2.0, **Add-Member** added members only to the PSObject wrapper of objects, not to the object. -Use the **PassThru** parameter to create an output object for any object that has a PSObject wrapper. +In Windows PowerShell 2.0, `Add-Member` added members only to the **PSObject** wrapper of objects, +not to the object. +Use the **PassThru** parameter to create an output object for any object that has a **PSObject** +wrapper. ```yaml Type: SwitchParameter @@ -359,14 +338,21 @@ Accept wildcard characters: False ### -SecondValue -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. +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 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. +You can use the **SecondValue** parameter to specify an additional **ScriptBlock** when adding a +**ScriptProperty** member. 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. ```yaml Type: Object @@ -383,7 +369,8 @@ Accept wildcard characters: False ### -Value Specifies the initial value of the added member. -If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the SecondValue parameter. +If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you +can supply optional, additional information by using the **SecondValue** parameter. ```yaml Type: Object @@ -400,11 +387,13 @@ Accept wildcard characters: False ### -NotePropertyMembers Specifies a hash table or ordered dictionary of note property names and values. -Type a hash table or dictionary in which the keys are note property names and the values are note property values. +Type a hash table or dictionary in which the keys are note property names and the values are note +property values. -For more information about hash tables and ordered dictionaries in Windows PowerShell, see about_Hash_Tables (http://go.microsoft.com/fwlink/?LinkID=135175). +For more information about hash tables and ordered dictionaries in PowerShell, see +[about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: IDictionary @@ -420,12 +409,12 @@ Accept wildcard characters: False ### -NotePropertyName -Adds a note property with the specified name. +Specifies the note property name. Use this parameter with the **NotePropertyValue** parameter. -The parameter name (-NotePropertyName) is optional. +This parameter is optional. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String @@ -441,12 +430,12 @@ Accept wildcard characters: False ### -NotePropertyValue -Adds a note property with the specified value. +Specifies the note property value. Use this parameter with the **NotePropertyName** parameter. -The parameter name (-NotePropertyValue) is optional. +This parameter is optional. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: Object @@ -464,11 +453,11 @@ Accept wildcard characters: False Specifies 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. -This parameter is effective only when the input object is a PSObject. +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. +This parameter is effective only when the **InputObject** is a **PSObject**. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String @@ -494,34 +483,36 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - ## INPUTS ### System.Management.Automation.PSObject -You can pipe any object type to Add-Member. +You can pipe any object type to this cmdlet. ## OUTPUTS ### None or System.Object -When you use the PassThru parameter, Add-Member returns the newly-extended object. +When you use the **PassThru** parameter, this cmdlet 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\]". +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**. - 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 (http://go.microsoft.com/fwlink/?LinkID=113212). +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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md index 58b746ba91aa..a64dc00407fc 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +md.date: 4/26/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,7 +10,7 @@ title: Add-Member # Add-Member ## SYNOPSIS -Adds custom properties and methods to an instance of a Windows PowerShell object. +Adds custom properties and methods to an instance of a PowerShell object. ## SYNTAX @@ -48,211 +48,162 @@ Add-Member [-NotePropertyMembers] ## 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. +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. -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 **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 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. +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. +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. ## EXAMPLES ### Example 1: Add a note property to a PSObject -```powershell -$a = dir c:\ps-test\test.txt -$a | Add-Member -NotePropertyName Status -NotePropertyValue Done -$a | Add-Member Status Done -$a.Status -``` - -```Output -Done -``` - -These commands add the 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 (alias = "dir) to get the Test.txt file. -It saves it in the $a variable. +The following example adds a **Status** note property with a value of "Done" to the **FileInfo** +object that represents the `Test.txt` file. -The second and third commands add the note property to the object in $a. -The third command omits the optional parameter names, so the parameter values must be in the correct -Name-Value order. These commands are equivalent and can be used interchangeably. +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 fourth 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". +The second command adds the note property to the object in `$a`. -### Example 2: Add an alias property to a PSObject +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". ```powershell -$a = dir c:\ps-test\test.txt -$a | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -$a.FileLength +$A = Get-ChildItem c:\ps-test\test.txt +$A | Add-Member -NotePropertyName Status -NotePropertyValue Done +$A.Status ``` ```Output -2394 +Done ``` -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. +### Example 2: Add an alias property to a PSObject -The second command adds the FileLength alias property. +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 third command uses dot notation to get the value of the new **FileLength** property. +The first command uses the `Get-ChildItem` cmdlet to get the `Test.txt` **FileInfo** object. -### Example 3: Add a StringUse note property to a string +The second command adds the **Size** alias property. +The third command uses dot notation to get the value of the new **Size** property. ```powershell -$a = "A string" -$a = $a | Add-Member @{StringUse="Display"} -PassThru -$a.StringUse +$A = Get-ChildItem C:\Temp\test.txt +$A | Add-Member -MemberType AliasProperty -Name Size -Value Length +$A.Size ``` ```Output -Display +2394 ``` -These commands add the **StringUse** note property to a string. -Because `Add-Member` cannot add types to String input objects, the command uses the **PassThru** -parameter to generate an output object. The last command in the example displays the new property. +### Example 3: Add a StringUse note property to a string -The command uses the **NotePropertyMembers** parameter, but omits the parameter name, which is -optional. 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. +This example adds the **StringUse** note property to a string. +Because `Add-Member` cannot add types to **String** input objects, you can speciy the **PassThru** +parameter to generate an output object. The last command in the example displays the new property. -### Example 4: Add a script method to a string object +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**. ```powershell -$a = "This is a string." -$a = Add-Member -InputObject $a -MemberType ScriptMethod -Name PadBoth -Value {$p = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -$a.Padboth() +$A = "A string" +$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru +$A.StringUse ``` ```Output -This is a string. +Display ``` -These commands add the PadBoth script method to a string object. - -The first command creates a string and saves it in the $a variable. +### Example 4: Add a script method to a FileInfo object -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. +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 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` adds members to PSObjects and does not generate any output. - -The third command uses dot notation to call the new PadBoth script method on the object in the $a -variable. +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. -### Example 5: Add an alias property to an event +The last command uses dot notation to call the new **SizeInMB** script method on the object in the +`$A` variable. ```powershell -$event = Get-EventLog -LogName System -Newest 1 -$event.TimeWritten | Get-Member +$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() ``` ```Output -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)... +0.43 ``` -```powershell -Add-Member -InputObject $event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -$event.When | Get-Member -``` +### Example 5: Copy all properties of an object to another -```Output -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) -``` - -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. - -To demonstrate that the **TimeWritten** property is a DateTime type, the second command uses dot -notation to get the **TimeWritten** property of that event and pipes it to the `Get-Member` cmdlet. +This function copies all of the properties of one object to another object. -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. +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. -### Example 6: Copy all properties of an object to another +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. ```powershell 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) - } +{ + $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 function copies all of the properties of one object to another object. +### Example 6: Create a custom object -The first command in the function declares the function name and lists its parameters. +This example creates an **Asset** custom 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 `New-Object` cmdlet creates a **PSObject**. The example saves the **PSObject** in the `$Asset` +variable. -The `Add-Member` command adds the property of the From object to the To object as a NoteProperty. -It uses the **Force** parameter add members with the same member name. +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 last command in the function gives the new property the same name as the original property. +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**. -### Example 7: Create a custom object +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. ```powershell $Asset = New-Object -TypeName PSObject @@ -263,7 +214,7 @@ $Asset | Get-Member ```Output TypeName: Asset - + Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) @@ -275,28 +226,12 @@ PSVersion NoteProperty System.String PSVersion=4.0 System NoteProperty System.String System=Server Core ``` -This example creates the Asset custom object. - -The first command uses the `New-Object` cmdlet to create a PSObject. -The command 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. -It uses the **TypeName** property to assign a new name, Asset, to the PSObject. - -The fourth command sends the new Asset object in the $Asset variable 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. - ## 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. +Indicates that this cmdlet 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. ```yaml Type: SwitchParameter @@ -330,20 +265,27 @@ Accept wildcard characters: False ### -MemberType Specifies the type of the member to add. -This parameter is mandatory. +This parameter is required. +The acceptable values for this parameter are: + +- NoteProperty +- AliasProperty +- ScriptProperty +- CodeProperty +- ScriptMethod +- CopyMethod -The valid values for this parameter are: -"NoteProperty,AliasProperty,ScriptProperty,CodeProperty,ScriptMethod,CodeMethod" **AliasProperty**, -**CodeMethod**, **CodeProperty**, **Noteproperty**, **ScriptMethod**, and **ScriptProperty**. For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) in the MSDN library. + 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. +If you specify a member type that the object does not have, PowerShell returns an error. ```yaml Type: PSMemberTypes Parameter Sets: MemberSet Aliases: Type +Accepted values: AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All Required: True Position: 0 @@ -354,7 +296,7 @@ Accept wildcard characters: False ### -Name -Specifies the name of the member to be added. +Specifies the name of the member that this cmdlet adds. ```yaml Type: String @@ -370,17 +312,18 @@ Accept wildcard characters: False ### -PassThru -Returns the newly extended object. +Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. 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 Windows PowerShell 2.0, `Add-Member` added members only to the PSObject wrapper of objects, not -to the object. -Use the **PassThru** parameter to create an output object for any object that has a PSObject +In Windows PowerShell 2.0, `Add-Member` added members only to the **PSObject** wrapper of objects, +not to the object. +Use the **PassThru** parameter to create an output object for any object that has a **PSObject** wrapper. + ```yaml Type: SwitchParameter Parameter Sets: (All) @@ -397,18 +340,20 @@ Accept wildcard characters: False 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. + +If used when adding an **AliasProperty**, this parameter must be a data type. +A conversion 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. 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. + ```yaml Type: Object Parameter Sets: MemberSet @@ -426,6 +371,7 @@ Accept wildcard characters: False Specifies the initial value of the added member. If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the **SecondValue** parameter. + ```yaml Type: Object Parameter Sets: MemberSet @@ -443,9 +389,11 @@ Accept wildcard characters: False Specifies a hash table or ordered dictionary of note property names and values. Type a hash table or dictionary in which the keys are note property names and the values are note property values. -For more information about hash tables and ordered dictionaries in Windows PowerShell, [see -about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). -This parameter is introduced in Windows PowerShell 3.0. + +For more information about hash tables and ordered dictionaries in PowerShell, see +[about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). + +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: IDictionary @@ -461,12 +409,12 @@ Accept wildcard characters: False ### -NotePropertyName -Adds a note property with the specified name. +Specifies the note property name. Use this parameter with the **NotePropertyValue** parameter. -The parameter name (-NotePropertyName) is optional. +This parameter is optional. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String @@ -482,12 +430,12 @@ Accept wildcard characters: False ### -NotePropertyValue -Adds a note property with the specified value. +Specifies the note property value. Use this parameter with the **NotePropertyName** parameter. -The parameter name (-NotePropertyValue) is optional. +This parameter is optional. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: Object @@ -505,11 +453,11 @@ Accept wildcard characters: False Specifies 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 +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. -This parameter is effective only when the input object is a PSObject. +This parameter is effective only when the **InputObject** is a **PSObject**. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String @@ -539,29 +487,32 @@ Accept wildcard characters: False ### System.Management.Automation.PSObject -You can pipe any object type to `Add-Member`. +You can pipe any object type to this cmdlet. ## OUTPUTS ### None or System.Object -When you use the **PassThru** parameter, `Add-Member` returns the newly-extended object. +When you use the **PassThru** parameter, this cmdlet 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 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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ## RELATED LINKS @@ -573,4 +524,4 @@ Otherwise, this cmdlet does not generate any output. [New-Object](New-Object.md) -[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md index 8a1ab2cacc09..5bddf6bf3a41 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +md.date: 4/26/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,20 +10,20 @@ title: Add-Member # Add-Member ## SYNOPSIS -Adds custom properties and methods to an instance of a Windows PowerShell object. +Adds custom properties and methods to an instance of a PowerShell object. ## SYNTAX ### TypeNameSet (Default) -```powershell +``` Add-Member -InputObject -TypeName [-PassThru] [] ``` ### MemberSet -```powershell +``` Add-Member [-MemberType] [-Name] [[-Value] ] [[-SecondValue] ] -InputObject [-TypeName ] [-Force] [-PassThru] @@ -32,7 +32,7 @@ Add-Member [-MemberType] [-Name] ### NotePropertySingleMemberSet -```powershell +``` Add-Member [-NotePropertyName] [-NotePropertyValue] -InputObject [-TypeName ] [-Force] [-PassThru] [] @@ -40,7 +40,7 @@ Add-Member [-NotePropertyName] [-NotePropertyValue] ### NotePropertyMultiMemberSet -```powershell +``` Add-Member [-NotePropertyMembers] -InputObject [-TypeName ] [-Force] [-PassThru] [] @@ -48,185 +48,173 @@ Add-Member [-NotePropertyMembers] ## DESCRIPTION -The **Add-Member** cmdlet lets you add properties and methods to an instance of a Windows 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. +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. -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. +To use `Add-Member`, pipe the object to `Add-Member`, or use the **InputObject** parameter to +specify the object. -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. +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. -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. +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. -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. +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. -## EXAMPLES +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. -### Example 1: Add a note property to a PSObject +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. -``` -PS C:\> $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -NotePropertyName Status -NotePropertyValue Done -PS C:\> $A | Add-Member Status Done -PS C:\> $A.Status -Done -``` +## EXAMPLES -These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file. +### Example 1: Add a note property to a PSObject -The first command uses the Get-ChildItem cmdlet (alias = "dir) to get the Test.txt file. -It saves it in the $a variable. +The following example adds a **Status** note property with a value of "Done" to the **FileInfo** +object that represents the `Test.txt` file. -The second and third commands add the note property to the object in $a. -The third command omits the optional parameter names, so the parameter values must be in the correct Name-Value order. -These commands are equivalent and can be used interchangeably. +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 fourth 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". +The second command adds the note property to the object in `$a`. -### Example 2: Add an alias property to a PSObject +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". -``` -PS C:\> $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS C:\> $A.FileLength -2394 +```powershell +$A = Get-ChildItem c:\ps-test\test.txt +$A | Add-Member -NotePropertyName Status -NotePropertyValue Done +$A.Status ``` -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. +```Output +Done +``` -The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file. +### Example 2: Add an alias property to a PSObject -The second command adds the FileLength alias property. +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 third command uses dot notation to get the value of the new FileLength property. +The first command uses the `Get-ChildItem` cmdlet to get the `Test.txt` **FileInfo** object. -### Example 3: Add a StringUse note property to a string +The second command adds the **Size** alias property. +The third command uses dot notation to get the value of the new **Size** property. +```powershell +$A = Get-ChildItem C:\Temp\test.txt +$A | Add-Member -MemberType AliasProperty -Name Size -Value Length +$A.Size ``` -PS C:\> $A = "A string" -PS C:\> $A = $A | Add-Member @{StringUse="Display"} -PassThru -PS C:\> $A.StringUse -Display + +```Output +2394 ``` -These commands add the **StringUse** note property to a string. -Because Add-Member cannot add types to String input objects, the command uses the *PassThru* parameter to generate an output object. -The last command in the example displays the new property. +### Example 3: Add a StringUse note property to a string -The command uses the *NotePropertyMembers* parameter, but omits the parameter name, which is optional. -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. +This example adds the **StringUse** note property to a string. +Because `Add-Member` cannot add types to **String** input objects, you can speciy the **PassThru** +parameter to generate an output object. The last command in the example displays the new property. -### Example 4: Add a script method to a string object +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**. +```powershell +$A = "A string" +$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru +$A.StringUse ``` -PS C:\> $A = "This is a string." -PS C:\> $A = Add-Member -InputObject $A -MemberType ScriptMethod -Name "PadBoth" -Value {$P = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -PS C:\> $A.Padboth() -This is a string. -``` - -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. +```Output +Display +``` -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. +### Example 4: Add a script method to a FileInfo object -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** adds members to **PSObject**s and does not generate any output. +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 third command uses dot notation to call the new PadBoth script method on the object in the $A variable. +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. -### Example 5: Add an alias property to an event +The last command uses dot notation to call the new **SizeInMB** script method on the object in the +`$A` variable. +```powershell +$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() ``` -PS C:\> $Event = Get-EventLog -LogName System -Newest 1 -PS C:\> $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)... - - -PS C:\> Add-Member -InputObject $Event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -PS C:\> $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) -``` - -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. +```Output +0.43 +``` -To demonstrate that the TimeWritten property is a **DateTime** type, the second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet. +### Example 5: Copy all properties of an object to another -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. +This function copies all of the properties of one object to another object. -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. +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. -### Example 6: Copy all properties of an object to another +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. -``` -PS C:\> 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) - } +```powershell +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 function copies all of the properties of one object to another object. +### Example 6: Create a custom object -The first command in the function declares the function name and lists its parameters. +This example creates an **Asset** custom 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 `New-Object` cmdlet creates a **PSObject**. The example saves the **PSObject** in the `$Asset` +variable. -The **Add-Member** command adds the property of the **From** object to the **To** object as a NoteProperty. -It uses the *Force* parameter to add members with the same member name. +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 last command in the function gives the new property the same name as the original property. +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**. -### Example 7: Create a custom object +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. +```powershell +$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 ``` -PS C:\> $Asset = New-Object -TypeName PSObject -PS C:\> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="4.0"} -PS C:\> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset -PS C:\> $Asset | Get-Member - TypeName: Asset +```Output + TypeName: Asset + Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) @@ -238,26 +226,12 @@ PSVersion NoteProperty System.String PSVersion=4.0 System NoteProperty System.String System=Server Core ``` -This example creates the **Asset** custom object. - -The first command uses the New-Object cmdlet to create a **PSObject**. -The command 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**. -It uses the TypeName property to assign a new name, Asset, to the **PSObject**. - -The fourth command sends the new **Asset** object in the $Asset variable 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. - ## PARAMETERS ### -Force Indicates that this cmdlet 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. +You cannot use the **Force** parameter to replace a standard member of a type. ```yaml Type: SwitchParameter @@ -301,10 +275,11 @@ The acceptable values for this parameter are: - ScriptMethod - CopyMethod -For information about these values, see [PSMemberTypes Enumeration](https://msdn.microsoft.com/library/system.management.automation.psmembertypes) in the MSDN library. +For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) +in the MSDN library. 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. +If you specify a member type that the object does not have, PowerShell returns an error. ```yaml Type: PSMemberTypes @@ -338,9 +313,11 @@ Accept wildcard characters: False ### -NotePropertyMembers Specifies a hash table or ordered dictionary of note property names and values. -Type a hash table or dictionary in which the keys are note property names and the values are note property values. +Type a hash table or dictionary in which the keys are note property names and the values are note +property values. -For more information about hash tables and ordered dictionaries in Windows PowerShell, see about_Hash_Tables. +For more information about hash tables and ordered dictionaries in PowerShell, see +[about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). This parameter was introduced in Windows PowerShell 3.0. @@ -360,7 +337,7 @@ Accept wildcard characters: False Specifies the note property name. -Use this parameter with the *NotePropertyValue* parameter. +Use this parameter with the **NotePropertyValue** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -381,7 +358,7 @@ Accept wildcard characters: False Specifies the note property value. -Use this parameter with the *NotePropertyName* parameter. +Use this parameter with the **NotePropertyName** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -403,12 +380,14 @@ Accept wildcard characters: False Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. -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. +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 Windows PowerShell 2.0, **Add-Member** added members only to the PSObject wrapper of objects, not to the object. -Use the *PassThru* parameter to create an output object for any object that has a PSObject wrapper. +In Windows PowerShell 2.0, `Add-Member` added members only to the **PSObject** wrapper of objects, +not to the object. +Use the **PassThru** parameter to create an output object for any object that has a **PSObject** +wrapper. ```yaml Type: SwitchParameter @@ -424,14 +403,21 @@ Accept wildcard characters: False ### -SecondValue -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 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. +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 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. +You can use the **SecondValue** parameter to specify an additional **ScriptBlock** when adding a +**ScriptProperty** member. 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. ```yaml Type: Object @@ -449,9 +435,9 @@ Accept wildcard characters: False Specifies 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. -This parameter is effective only when the input object is a **PSObject**. +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. +This parameter is effective only when the **InputObject** is a **PSObject**. This parameter was introduced in Windows PowerShell 3.0. @@ -482,7 +468,8 @@ Accept wildcard characters: False ### -Value Specifies the initial value of the added member. -If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the *SecondValue* parameter. +If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you +can supply optional, additional information by using the **SecondValue** parameter. ```yaml Type: Object @@ -498,7 +485,9 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -510,22 +499,26 @@ You can pipe any object type to this cmdlet. ### None or System.Object -When you use the *PassThru* parameter, this cmdlet returns the newly-extended object. +When you use the **PassThru** parameter, this cmdlet 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 instance, to test an object stored in the $obj variable, type `$obj -is \[PSObject\]`. +You can add members only to **PSObject** objects. To determine whether an object is a **PSObject** +object, use the `-is` operator. - 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. +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**. - 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. +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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md index a84a1a45fd2c..7572e5c3ec1e 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md @@ -3,247 +3,231 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Utility -ms.date: 06/09/2017 +md.date: 4/26/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821748 schema: 2.0.0 title: Add-Member --- - # Add-Member ## SYNOPSIS -Adds custom properties and methods to an instance of a Windows PowerShell object. +Adds custom properties and methods to an instance of a PowerShell object. ## SYNTAX ### TypeNameSet (Default) + ``` Add-Member -InputObject -TypeName [-PassThru] [] ``` ### MemberSet + ``` Add-Member -InputObject [-MemberType] [-Name] [[-Value] ] [[-SecondValue] ] [-TypeName ] [-Force] [-PassThru] [] ``` ### NotePropertySingleMemberSet + ``` Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyName] [-NotePropertyValue] [] ``` ### NotePropertyMultiMemberSet + ``` Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyMembers] [] ``` ## DESCRIPTION -The **Add-Member** cmdlet lets you add members (properties and methods) to an instance of a Windows 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. -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 `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. -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. +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. +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. +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. ## EXAMPLES ### Example 1: Add a note property to a PSObject -``` -PS C:\> $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -NotePropertyName Status -NotePropertyValue Done -PS C:\> $A | Add-Member Status Done -PS C:\> $A.Status -Done -``` -These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file. +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 (alias = "dir) to get the Test.txt file. -It saves it in the $a variable. +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 and third commands add the note property to the object in $a. -The third command omits the optional parameter names, so the parameter values must be in the correct Name-Value order. -These commands are equivalent and can be used interchangeably. +The second command adds the note property to the object in `$a`. -The fourth 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". +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: Add an alias property to a PSObject +```powershell +$A = Get-ChildItem c:\ps-test\test.txt +$A | Add-Member -NotePropertyName Status -NotePropertyValue Done +$A.Status ``` -PS C:\> $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS C:\> $A.FileLength -2394 + +```Output +Done ``` -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. +### Example 2: Add an alias property to a PSObject -The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file. +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 second command adds the FileLength alias property. +The first command uses the `Get-ChildItem` cmdlet to get the `Test.txt` **FileInfo** object. -The third command uses dot notation to get the value of the new FileLength property. +The second command adds the **Size** alias property. +The third command uses dot notation to get the value of the new **Size** property. -### Example 3: Add a StringUse note property to a string -``` -PS C:\> $A = "A string" -PS C:\> $A = $A | Add-Member @{StringUse="Display"} -PassThru -PS C:\> $A.StringUse -Display +```powershell +$A = Get-ChildItem C:\Temp\test.txt +$A | Add-Member -MemberType AliasProperty -Name Size -Value Length +$A.Size ``` -These commands add the **StringUse** note property to a string. -Because Add-Member cannot add types to String input objects, the command uses the *PassThru* parameter to generate an output object. -The last command in the example displays the new property. - -The command uses the *NotePropertyMembers* parameter, but omits the parameter name, which is optional. -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. - -### Example 4: Add a script method to a string object -``` -PS C:\> $A = "This is a string." -PS C:\> $A = Add-Member -InputObject $A -MemberType ScriptMethod -Name "PadBoth" -Value {$P = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -PS C:\> $A.Padboth() -This is a string. +```Output +2394 ``` -These commands add the PadBoth script method to a string object. +### Example 3: Add a StringUse note property to a string -The first command creates a string and saves it in the $A variable. +This example adds the **StringUse** note property to a string. +Because `Add-Member` cannot add types to **String** input objects, you can speciy the **PassThru** +parameter to generate an output object. The last command in the example displays the new property. -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. +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**. -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. +```powershell +$A = "A string" +$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru +$A.StringUse +``` -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** adds members to **PSObject**s and does not generate any output. +```Output +Display +``` -The third command uses dot notation to call the new PadBoth script method on the object in the $A variable. +### Example 4: Add a script method to a FileInfo object -### Example 5: Add an alias property to an event -``` -PS C:\>$Event = Get-EventLog -LogName System -Newest 1 -PS C:\>$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)... - - -PS C:\>Add-Member -InputObject $Event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -PS C:\>$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) -``` +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. -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 **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 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 last command uses dot notation to call the new **SizeInMB** script method on the object in the +`$A` variable. -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. +```powershell +$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() +``` -To demonstrate that the TimeWritten property is a **DateTime** type, the second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet. +```Output +0.43 +``` -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. +### Example 5: Copy all properties of an object to another -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. +This function copies all of the properties of one object to another object. -### Example 6: Copy all properties of an object to another -``` -PS C:\> 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) - } +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. + +```powershell +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 function copies all of the properties of one object to another object. +### Example 6: Create a custom object -The first command in the function declares the function name and lists its parameters. +This example creates an **Asset** custom 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 `New-Object` cmdlet creates a **PSObject**. The example saves the **PSObject** in the `$Asset` +variable. -The **Add-Member** command adds the property of the **From** object to the **To** object as a NoteProperty. -It uses the *Force* parameter to add members with the same member name. +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 last command in the function gives the new property the same name as the original property. +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**. -### Example 7: Create a custom object -``` -PS C:\> $Asset = New-Object -TypeName PSObject -PS C:\> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="4.0"} -PS C:\> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset -PS C:\> $Asset | Get-Member +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. +```powershell +$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 +``` +```Output 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 string Name=Server30 -PSVersion NoteProperty string PSVersion=4.0 -System NoteProperty string System=Server Core +Name NoteProperty System.String Name=Server30 +PSVersion NoteProperty System.String PSVersion=4.0 +System NoteProperty System.String System=Server Core ``` -This example creates the **Asset** custom object. - -The first command uses the New-Object cmdlet to create a **PSObject**. -The command 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**. -It uses the TypeName property to assign a new name, Asset, to the **PSObject**. - -The fourth command sends the new **Asset** object in the $Asset variable 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. - ## PARAMETERS ### -Force + Indicates that this cmdlet 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. +You cannot use the **Force** parameter to replace a standard member of a type. ```yaml Type: SwitchParameter @@ -258,6 +242,7 @@ Accept wildcard characters: False ``` ### -InputObject + 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. @@ -274,6 +259,7 @@ Accept wildcard characters: False ``` ### -MemberType + Specifies the type of the member to add. This parameter is required. The acceptable values for this parameter are: @@ -285,10 +271,11 @@ The acceptable values for this parameter are: - ScriptMethod - CopyMethod -For information about these values, see [PSMemberTypes Enumeration](https://msdn.microsoft.com/library/system.management.automation.psmembertypes) in the MSDN library. +For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) +in the MSDN library. 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. +If you specify a member type that the object does not have, PowerShell returns an error. ```yaml Type: PSMemberTypes @@ -304,6 +291,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the member that this cmdlet adds. ```yaml @@ -319,10 +307,13 @@ Accept wildcard characters: False ``` ### -NotePropertyMembers + Specifies a hash table or ordered dictionary of note property names and values. -Type a hash table or dictionary in which the keys are note property names and the values are note property values. +Type a hash table or dictionary in which the keys are note property names and the values are note +property values. -For more information about hash tables and ordered dictionaries in Windows PowerShell, see about_Hash_Tables. +For more information about hash tables and ordered dictionaries in PowerShell, see +[about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). This parameter was introduced in Windows PowerShell 3.0. @@ -339,9 +330,10 @@ Accept wildcard characters: False ``` ### -NotePropertyName + Specifies the note property name. -Use this parameter with the *NotePropertyValue* parameter. +Use this parameter with the **NotePropertyValue** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -359,9 +351,10 @@ Accept wildcard characters: False ``` ### -NotePropertyValue + Specifies the note property value. -Use this parameter with the *NotePropertyName* parameter. +Use this parameter with the **NotePropertyName** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -379,15 +372,18 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. -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. +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 Windows PowerShell 2.0, **Add-Member** added members only to the PSObject wrapper of objects, not to the object. -Use the *PassThru* parameter to create an output object for any object that has a PSObject wrapper. +In Windows PowerShell 2.0, `Add-Member` added members only to the **PSObject** wrapper of objects, +not to the object. +Use the **PassThru** parameter to create an output object for any object that has a **PSObject** +wrapper. ```yaml Type: SwitchParameter @@ -402,14 +398,22 @@ Accept wildcard characters: False ``` ### -SecondValue -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 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. +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 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. 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. ```yaml Type: Object @@ -424,11 +428,12 @@ Accept wildcard characters: False ``` ### -TypeName + Specifies 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. -This parameter is effective only when the input object is a **PSObject**. +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. +This parameter is effective only when the **InputObject** is a **PSObject**. This parameter was introduced in Windows PowerShell 3.0. @@ -457,8 +462,10 @@ Accept wildcard characters: False ``` ### -Value + Specifies the initial value of the added member. -If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the SecondValue parameter. +If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you +can supply optional, additional information by using the **SecondValue** parameter. ```yaml Type: Object @@ -473,31 +480,41 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object type to this cmdlet. ## OUTPUTS ### None or System.Object -When you use the *PassThru* parameter, this cmdlet returns the newly-extended object. + +When you use the **PassThru** parameter, this cmdlet 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 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 add members only to **PSObject** objects. To determine whether an object is a **PSObject** +object, use the `-is` operator. - 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. +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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ## RELATED LINKS @@ -507,4 +524,6 @@ For more information about the $this variable, see about_Automatic_Variables. [Import-Clixml](Import-Clixml.md) -[New-Object](New-Object.md) \ No newline at end of file +[New-Object](New-Object.md) + +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md index 3de7157a9fbf..40306b9a8766 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md @@ -3,7 +3,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Utility -ms.date: 06/09/2017 +md.date: 4/26/2019 online version: http://go.microsoft.com/fwlink/?LinkId=821748 schema: 2.0.0 title: Add-Member @@ -44,184 +44,177 @@ Add-Member -InputObject [-MemberType] [-Name] $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -NotePropertyName Status -NotePropertyValue Done -PS C:\> $A | Add-Member Status Done -PS C:\> $A.Status -Done -``` +## EXAMPLES -These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file. +### Example 1: Add a note property to a PSObject -The first command uses the Get-ChildItem cmdlet (alias = "dir) to get the Test.txt file. -It saves it in the $a variable. +The following example adds a **Status** note property with a value of "Done" to the **FileInfo** +object that represents the `Test.txt` file. -The second and third commands add the note property to the object in $a. -The third command omits the optional parameter names, so the parameter values must be in the correct Name-Value order. -These commands are equivalent and can be used interchangeably. +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 fourth 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". +The second command adds the note property to the object in `$a`. -### Example 2: Add an alias property to a PSObject +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". -``` -PS C:\> $A = dir c:\ps-test\test.txt -PS C:\> $A | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS C:\> $A.FileLength -2394 +```powershell +$A = Get-ChildItem c:\ps-test\test.txt +$A | Add-Member -NotePropertyName Status -NotePropertyValue Done +$A.Status ``` -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. +```Output +Done +``` -The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file. +### Example 2: Add an alias property to a PSObject -The second command adds the FileLength alias property. +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 third command uses dot notation to get the value of the new FileLength property. +The first command uses the `Get-ChildItem` cmdlet to get the `Test.txt` **FileInfo** object. -### Example 3: Add a StringUse note property to a string +The second command adds the **Size** alias property. +The third command uses dot notation to get the value of the new **Size** property. +```powershell +$A = Get-ChildItem C:\Temp\test.txt +$A | Add-Member -MemberType AliasProperty -Name Size -Value Length +$A.Size ``` -PS C:\> $A = "A string" -PS C:\> $A = $A | Add-Member @{StringUse="Display"} -PassThru -PS C:\> $A.StringUse -Display + +```Output +2394 ``` -These commands add the **StringUse** note property to a string. -Because Add-Member cannot add types to String input objects, the command uses the *PassThru* parameter to generate an output object. -The last command in the example displays the new property. +### Example 3: Add a StringUse note property to a string -The command uses the *NotePropertyMembers* parameter, but omits the parameter name, which is optional. -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. +This example adds the **StringUse** note property to a string. +Because `Add-Member` cannot add types to **String** input objects, you can speciy the **PassThru** +parameter to generate an output object. The last command in the example displays the new property. -### Example 4: Add a script method to a string object +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**. +```powershell +$A = "A string" +$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru +$A.StringUse ``` -PS C:\> $A = "This is a string." -PS C:\> $A = Add-Member -InputObject $A -MemberType ScriptMethod -Name "PadBoth" -Value {$P = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -PS C:\> $A.Padboth() -This is a string. -``` - -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 to the left and one space to the right of the string. +```Output +Display +``` -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. +### Example 4: Add a script method to a FileInfo object -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** adds members to **PSObject**s and does not generate any output. +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 third command uses dot notation to call the new PadBoth script method on the object in the $A variable. +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. -### Example 5: Add an alias property to an event +The last command uses dot notation to call the new **SizeInMB** script method on the object in the +`$A` variable. +```powershell +$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() ``` -PS C:\> $Event = Get-EventLog -LogName System -Newest 1 -PS C:\> $Event.TimeWritten | Get-MemberTypeName: 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)... - -PS C:\> Add-Member -InputObject $Event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -PS C:\> $Event.When | Get-MemberTypeName: 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) -``` - -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. - -To demonstrate that the TimeWritten property is a **DateTime** type, the second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet. -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. +```Output +0.43 +``` -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 5: Copy all properties of an object to another -### Example 6: Copy all properties of an object to another +This function copies all of the properties of one object to another object. -``` -PS C:\> 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) - } +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. + +```powershell +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 function copies all of the properties of one object to another object. +### Example 6: Create a custom object -The first command in the function declares the function name and lists its parameters. +This example creates an **Asset** custom 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 `New-Object` cmdlet creates a **PSObject**. The example saves the **PSObject** in the `$Asset` +variable. -The **Add-Member** command adds the property of the **From** object to the **To** object as a NoteProperty. -It uses the *Force* parameter to add members with the same member name. +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 last command in the function gives the new property the same name as the original property. +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**. -### Example 7: Create a custom object +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. +```powershell +$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 ``` -PS C:\> $Asset = New-Object -TypeName PSObject -PS C:\> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="4.0"} -PS C:\> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset -PS C:\> $Asset | Get-Member TypeName: Asset + +```Output + TypeName: Asset + Name MemberType Definition ---- ---------- ---------- -Equals Method bool Equals(System.Object obj) GetHashCode Method int GetHashCode() +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 @@ -229,26 +222,12 @@ PSVersion NoteProperty System.String PSVersion=4.0 System NoteProperty System.String System=Server Core ``` -This example creates the **Asset** custom object. - -The first command uses the New-Object cmdlet to create a **PSObject**. -The command 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**. -It uses the TypeName property to assign a new name, Asset, to the **PSObject**. - -The fourth command sends the new **Asset** object in the $Asset variable 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. - ## PARAMETERS ### -Force Indicates that this cmdlet 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. +You cannot use the **Force** parameter to replace a standard member of a type. ```yaml Type: SwitchParameter @@ -292,7 +271,8 @@ The acceptable values for this parameter are: - ScriptMethod - CopyMethod -For information about these values, see [PSMemberTypes Enumeration](https://msdn.microsoft.com/library/system.management.automation.psmembertypes) in the MSDN library. +For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) +in the MSDN library. Not all objects have every type of member. If you specify a member type that the object does not have, PowerShell returns an error. @@ -329,9 +309,11 @@ Accept wildcard characters: False ### -NotePropertyMembers Specifies a hash table or ordered dictionary of note property names and values. -Type a hash table or dictionary in which the keys are note property names and the values are note property values. +Type a hash table or dictionary in which the keys are note property names and the values are note +property values. -For more information about hash tables and ordered dictionaries in PowerShell, see about_Hash_Tables. +For more information about hash tables and ordered dictionaries in PowerShell, see +[about_Hash_Tables](../Microsoft.PowerShell.Core/About/about_Hash_Tables.md). This parameter was introduced in Windows PowerShell 3.0. @@ -351,7 +333,7 @@ Accept wildcard characters: False Specifies the note property name. -Use this parameter with the *NotePropertyValue* parameter. +Use this parameter with the **NotePropertyValue** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -372,7 +354,7 @@ Accept wildcard characters: False Specifies the note property value. -Use this parameter with the *NotePropertyName* parameter. +Use this parameter with the **NotePropertyName** parameter. This parameter is optional. This parameter was introduced in Windows PowerShell 3.0. @@ -394,12 +376,14 @@ Accept wildcard characters: False Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. -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. +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 Windows PowerShell 2.0, **Add-Member** added members only to the PSObject wrapper of objects, not to the object. -Use the *PassThru* parameter to create an output object for any object that has a PSObject wrapper. +In Windows PowerShell 2.0, `Add-Member` added members only to the **PSObject** wrapper of objects, +not to the object. +Use the **PassThru** parameter to create an output object for any object that has a **PSObject** +wrapper. ```yaml Type: SwitchParameter @@ -415,14 +399,21 @@ Accept wildcard characters: False ### -SecondValue -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 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. +Specifies optional additional information about **AliasProperty**, **ScriptProperty**, +**CodeProperty**, or **CodeMethod** members. -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. +If used when adding an **AliasProperty**, this parameter must be a data type. +A conversion 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. 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. ```yaml Type: Object @@ -440,9 +431,9 @@ Accept wildcard characters: False Specifies 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. -This parameter is effective only when the input object is a **PSObject**. +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. +This parameter is effective only when the **InputObject** is a **PSObject**. This parameter was introduced in Windows PowerShell 3.0. @@ -473,7 +464,8 @@ Accept wildcard characters: False ### -Value Specifies the initial value of the added member. -If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the SecondValue parameter. +If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you +can supply optional, additional information by using the **SecondValue** parameter. ```yaml Type: Object @@ -489,7 +481,9 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -501,20 +495,26 @@ You can pipe any object type to this cmdlet. ### None or System.Object -When you use the *PassThru* parameter, this cmdlet returns the newly-extended object. +When you use the **PassThru** parameter, this cmdlet 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 instance, to test an object stored in the $obj variable, type `$obj -is \[PSObject\]`. +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**. -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. +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](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). ## RELATED LINKS @@ -524,4 +524,6 @@ For more information about the $this variable, see about_Automatic_Variables. [Import-Clixml](Import-Clixml.md) -[New-Object](New-Object.md) \ No newline at end of file +[New-Object](New-Object.md) + +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) \ No newline at end of file From 835cbe084ffb84303afe0fa0fb2af65db289029e Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Fri, 26 Apr 2019 13:06:50 -0400 Subject: [PATCH 2/2] Editorial review --- .../Add-Member.md | 22 +++----- .../Add-Member.md | 18 +++---- .../Add-Member.md | 16 +----- .../Add-Member.md | 16 +----- .../Add-Member.md | 52 +++++++------------ 5 files changed, 38 insertions(+), 86 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md index eae7f14df6b0..7868c6e48b16 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -214,7 +214,7 @@ $Asset | Get-Member ```Output TypeName: Asset - + Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) @@ -461,27 +461,21 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: TypeNameSet +Parameter Sets: TypeNameSet, NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet Aliases: -Required: True +Required: True (TypeNameSet), False (NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet) Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -```yaml -Type: String -Parameter Sets: NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet -Aliases: +### CommonParameters -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -524,4 +518,4 @@ being added. For more information about the `$this` variable, see [about_Automat [New-Object](New-Object.md) -[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) \ No newline at end of file +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md index a64dc00407fc..2c7cced8b300 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -461,27 +461,21 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: TypeNameSet +Parameter Sets: TypeNameSet, NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet Aliases: -Required: True +Required: True (TypeNameSet), False (NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet) Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -```yaml -Type: String -Parameter Sets: MemberSet, NotePropertySingleMemberSet, NotePropertyMultiMemberSet -Aliases: +### CommonParameters -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md index 5bddf6bf3a41..52671405c41c 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -443,22 +443,10 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: TypeNameSet +Parameter Sets: TypeNameSet, NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet Aliases: -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -```yaml -Type: String -Parameter Sets: MemberSet, NotePropertySingleMemberSet, NotePropertyMultiMemberSet -Aliases: - -Required: False +Required: True (TypeNameSet), False (NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet) Position: Named Default value: None Accept pipeline input: False diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md index 7572e5c3ec1e..f6a0ef632244 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md @@ -439,22 +439,10 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: TypeNameSet +Parameter Sets: TypeNameSet, NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet Aliases: -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -```yaml -Type: String -Parameter Sets: MemberSet, NotePropertySingleMemberSet, NotePropertyMultiMemberSet -Aliases: - -Required: False +Required: True (TypeNameSet), False (NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet) Position: Named Default value: None Accept pipeline input: False diff --git a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md index 40306b9a8766..9cd7d4a049b2 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md @@ -210,7 +210,7 @@ $Asset | Get-Member ```Output TypeName: Asset - + Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) @@ -427,53 +427,41 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -TypeName - -Specifies 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. -This parameter is effective only when the **InputObject** is a **PSObject**. +### -Value -This parameter was introduced in Windows PowerShell 3.0. +Specifies the initial value of the added member. +If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you +can supply optional, additional information by using the **SecondValue** parameter. ```yaml -Type: String -Parameter Sets: TypeNameSet +Type: Object +Parameter Sets: MemberSet Aliases: -Required: True -Position: Named +Required: False +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -```yaml -Type: String -Parameter Sets: NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet -Aliases: +### -TypeName -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +Specifies a name for the type. -### -Value +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. +This parameter is effective only when the **InputObject** is a **PSObject**. -Specifies the initial value of the added member. -If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you -can supply optional, additional information by using the **SecondValue** parameter. +This parameter was introduced in Windows PowerShell 3.0. ```yaml -Type: Object -Parameter Sets: MemberSet +Type: String +Parameter Sets: TypeNameSet, NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet Aliases: -Required: False -Position: 2 +Required: True (TypeNameSet), False (NotePropertyMultiMemberSet, NotePropertySingleMemberSet, MemberSet) +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -526,4 +514,4 @@ being added. For more information about the `$this` variable, see [about_Automat [New-Object](New-Object.md) -[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) \ No newline at end of file +[about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md)