Add-Member

参考

模块:: Microsoft.PowerShell.Utility

将自定义属性和方法添加到 PowerShell 对象的实例中。

语法

Add-Member
   -InputObject <PSObject>
   -TypeName <String>
   [-PassThru]
   [<CommonParameters>]

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

Add-Member
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [-NotePropertyName] <String>
   [-NotePropertyValue] <Object>
   [<CommonParameters>]

Add-Member
   -InputObject <PSObject>
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]

说明

Add-Member cmdlet 允许你将成员（属性和方法）添加到 PowerShell 对象的实例中。例如，你可以添加包含对象说明的 NoteProperty 成员或添加运行用于更改对象的脚本的 ScriptMethod 成员。

若要使用 Add-Member，请通过管道将对象传递给 Add-Member，或使用 InputObject 参数来指定对象。

MemberType 参数指示要添加的成员的类型。 Name 参数会将名称分配给新成员，Value 参数则设置成员的值。

你添加的属性和方法只会添加到你指定的对象的特定实例中。 Add-Member 不会更改对象类型。若要创建新的对象类型，请使用 Add-Type cmdlet。

也可以使用 Export-Clixml cmdlet 将对象的实例（包括其他成员）保存在文件中。然后，可以使用 Import-Clixml cmdlet 通过导出的文件中存储的信息重新创建对象的实例。

从 Windows PowerShell 3.0 开始，Add-Member 具有很多新功能，可以更加轻松地将附注属性添加到对象中。可以使用 NotePropertyName 和 NotePropertyValue 参数定义附注属性，或使用 NotePropertyMembers 参数，该参数采用包含附注属性名称和值的哈希表。

此外，从 Windows PowerShell 3.0 开始，将很少需要使用用于生成输出对象的 PassThru 参数。现在，Add-Member 可将新成员直接添加到更多类型的输入对象中。有关详细信息，请参阅 PassThru 参数说明。

示例

示例 1：向 PSObject 添加注释属性

以下示例将值为“Done”的 Status 注释属性添加到表示 Test.txt 文件的 FileInfo 对象。

第一个命令使用 Get-ChildItem cmdlet 获取表示 Test.txt 文件的 FileInfo 对象。它将其保存在 $a 变量中。

第二个命令将注释属性添加到 $a 中的对象。

第三个命令使用点表示法获取 $a 中对象的 Status 属性值。如输出所示，值为 Done。

$A = Get-ChildItem c:\ps-test\test.txt
$A | Add-Member -NotePropertyName Status -NotePropertyValue Done
$A.Status

Done

示例 2：向 PSObject 添加别名属性

以下示例将 Size 别名属性添加到表示 Test.txt 文件的对象。新属性是 Length 属性的别名。

第一个命令使用 Get-ChildItem cmdlet 获取 Test.txt FileInfo 对象。

第二个命令将添加 Size 别名属性。第三个命令使用点表示法来获取新的 Size 属性的值。

$A = Get-ChildItem C:\Temp\test.txt
$A | Add-Member -MemberType AliasProperty -Name Size -Value Length
$A.Size

2394

示例 3：向字符串添加 StringUse 注释属性

此示例将 StringUse 注释属性添加到字符串中。由于 Add-Member 无法向 String 输入对象添加类型，因此可以指定 PassThru 参数来生成输出对象。示例中的最后一个命令将显示新属性。

此示例使用 NotePropertyMembers 参数。 NotePropertyMembers 参数的值是一个哈希表。哈希表中的键为附注属性名称 StringUse，值为附注属性值 Display。

$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse

Display

示例 4：向 FileInfo 对象添加脚本方法

此示例将 SizeInMB 脚本方法添加到 FileInfo 对象，该对象可计算文件大小（精确到兆字节）。第二个命令将创建一个 ScriptBlock，它使用 [math] 类型的 Round 静态方法将文件大小四舍五入到小数点后第二位。

Value 参数还使用 $This 自动变量，它表示当前对象。 $This 变量仅在定义新属性和方法的脚本块中有效。

最后一个命令使用点表示法调用 $A 变量中的对象上的新的 SizeInMB 脚本方法。

$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()

0.43

示例 5：创建自定义对象

此示例创建了 Asset 自定义对象。

该 New-Object cmdlet 将创建保存在变量中的 $Asset PSObject。 [ordered]类型加速器创建存储在变量中的$d有序字典。通过管道将 $Asset 传输到 Add-Member 将字典中的键值对作为 NoteProperty 成员添加到对象中。 TypeName 参数将类型 Asset 分配给 PSObject。 Get-Member cmdlet 显示对象的类型和属性。但是，属性将按字母顺序而不是添加顺序列出。

$Asset = New-Object -TypeName PSObject
$Asset | Add-Member -NotePropertyMembers @{Name="Server30"} -TypeName Asset
$Asset | Add-Member -NotePropertyMembers @{System="Server Core"}
$Asset | Add-Member -NotePropertyMembers @{PSVersion="4.0"}
$Asset | Get-Member -MemberType Properties

TypeName: Asset

Name        MemberType   Definition
----        ----------   ----------
Name        NoteProperty string Name=Server30
PSVersion   NoteProperty string PSVersion=4.0
System      NoteProperty string System=Server Core

$Asset.PSObject.Properties | Format-Table Name, MemberType, TypeNameOfValue, Value

Name        MemberType TypeNameOfValue Value
----        ---------- --------------- -----
Name      NoteProperty System.String   Server30
System    NoteProperty System.String   Server Core
PSVersion NoteProperty System.String   4.0

检查属性的原始列表会显示属性的顺序，这些属性已添加到对象中。此示例中使用 Format-Table 创建与 Get-Member 类似的输出。

示例 6：向对象添加 AliasProperty

在此示例中，我们创建一个包含两个 NoteProperty 成员的自定义对象。 NoteProperty 的类型反映了属性中存储的值的类型。在本例中，Age 属性是一个字符串。

PS> $obj = [pscustomobject]@{
      Name = 'Doris'
      Age = '20'
}
PS> $obj | Add-Member -MemberType AliasProperty -Name 'intAge' -Value age -SecondValue uint32
PS> $obj | Get-Member

   TypeName: System.Management.Automation.PSCustomObject

Name        MemberType    Definition
----        ----------    ----------
intAge      AliasProperty intAge = (System.UInt32)age
Equals      Method        bool Equals(System.Object obj)
GetHashCode Method        int GetHashCode()
GetType     Method        type GetType()
ToString    Method        string ToString()
Age         NoteProperty  string Age=20
Name        NoteProperty  string Name=Doris

PS> $obj

Name   : Doris
Age    : 20
intAge : 20

PS> $obj.Age + 1

201

PS> $obj.intAge + 1

21

intAge 属性是 Age 属性的 AliasProperty，但类型保证为 uint32。

示例 7：向自定义对象添加 get 和 set 方法

此示例说明如何定义访问深层嵌套属性的 Get 和 Set 方法。

$user = [pscustomobject]@{
    Name      = 'User1'
    Age       = 29
    StartDate = [datetime]'2019-05-05'
    Position  = [pscustomobject]@{
        DepartmentName = 'IT'
        Role = 'Manager'
    }
}
$addMemberSplat = @{
    MemberType = 'ScriptProperty'
    Name = 'Title'
    Value = { $this.Position.Role }                  # getter
    SecondValue = { $this.Position.Role = $args[0] } # setter
}
$user | Add-Member @addMemberSplat
$user | Get-Member

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType     Definition
----        ----------     ----------
Equals      Method         bool Equals(System.Object obj)
GetHashCode Method         int GetHashCode()
GetType     Method         type GetType()
ToString    Method         string ToString()
Age         NoteProperty   int Age=29
Name        NoteProperty   string Name=User1
Position    NoteProperty   System.Management.Automation.PSCustomObject Position=@{DepartmentName=IT; Role=Manager}
StartDate   NoteProperty   datetime StartDate=5/5/2019 12:00:00 AM
Title       ScriptProperty System.Object Title {get= $this.Position.Role ;set= $this.Position.Role = $args[0] ;}

$user.Title = 'Dev Manager'

Name      : User1
Age       : 29
StartDate : 5/5/2019 12:00:00 AM
Position  : @{DepartmentName=IT; Role=Dev Manager}
Title     : Dev Manager

请注意，Title 属性是一个具有 Get 和 Set 方法的 ScriptProperty。当我们为 Title 属性分配新值时，系统会调用 Set 方法并更改 Position 属性中 Role 属性的值。

参数

-Force

默认情况下，如果对象已有具有相同的成员， Add-Member 则无法添加新成员。使用 Force 参数时， Add-Member 将现有成员替换为新成员。不能使用 Force 参数替换某个类型的标准成员。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-InputObject

指定要向其添加新成员的对象。输入一个包含对象的变量，或键入可获取对象的命令或表达式。

类型:	PSObject
Position:	Named
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-MemberType

指定要添加的成员类型。此参数是必需的。此参数的可接受值为：

AliasProperty
CodeMethod
CodeProperty
NoteProperty
ScriptMethod
ScriptProperty

有关这些值的信息，请参阅 PowerShell SDK 中的 PSMemberTypes 枚举。

并非所有对象都具有每种类型的成员。如果指定对象所不具有的成员类型，则 PowerShell 将返回错误。

类型:	PSMemberTypes
别名:	Type
接受的值:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-Name

指定此 cmdlet 添加的成员的名称。

类型:	String
Position:	1
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-NotePropertyMembers

指定一个哈希表或有序字典，其中包含表示 NoteProperty 名称及其值的键值对。有关 PowerShell 中哈希表和有序字典的详细信息，请参阅 about_Hash_Tables。

已在 Windows PowerShell 3.0 中引入了此参数。

类型:	IDictionary
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-NotePropertyName

指定注释属性名称。

将此参数与 NotePropertyValue 参数配合使用。此参数是可选的。

已在 Windows PowerShell 3.0 中引入了此参数。

类型:	String
Position:	0
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-NotePropertyValue

指定注释属性值。

将此参数与 NotePropertyName 参数配合使用。此参数是可选的。

已在 Windows PowerShell 3.0 中引入了此参数。

类型:	Object
Position:	1
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-PassThru

返回一个代表你所处理的项目的对象。默认情况下，此 cmdlet 不会生成任何输出。

对于大多数对象，Add-Member 会将新成员添加到输入对象。但是，当输入对象是字符串时，Add-Member 无法将成员添加到输入对象。对于这些对象，请使用 PassThru 参数来创建输出对象。

在 Windows PowerShell 2.0 中，Add-Member 仅将成员添加到对象的 PSObject 包装器，而不是添加到对象。使用 PassThru 参数为任何具有 PSObject 包装器的对象创建输出对象。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-SecondValue

指定有关 AliasProperty、ScriptProperty 或 CodeProperty 成员的可选附加信息。

若在添加 AliasProperty 时使用此参数，则它必须是数据类型。对指定数据类型的转换将添加到 AliasProperty 的值中。例如，如果添加了为字符串属性提供备用名称的 AliasProperty，你还可以指定 System.Int32 的 SecondValue 参数，以指示在使用相应的 AliasProperty 进行访问时，该字符串属性的值应转换为整数。

对于 CodeProperty，该值必须是对实施 Set 访问器的方法的引用。使用类型引用的 GetMethod() 方法来获取对方法的引用。该方法必须采用一个参数，即 PSObject。 Get 访问器是使用 Value 参数分配的。

对于 ScriptProperty，该值必须是实施 Set 访问器的脚本块。 Get 访问器是使用 Value 参数分配的。

类型:	Object
Position:	3
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TypeName

指定类型的名称。

当类型是 System 命名空间中的类或具有类型快捷键时，你可以输入该类型的简称。否则，必须输入完整类型名称。仅当 InputObject 是 PSObject 时，此参数才有效。

已在 Windows PowerShell 3.0 中引入了此参数。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Value

指定已添加成员的初始值。如果添加 AliasProperty、CodeProperty 或 ScriptProperty 成员，则可以使用 SecondValue 参数提供其他信息。

对于 AliasProperty，该值必须是要添加别名的属性的名称。
对于 CodeMethod，该值必须是对方法的引用。使用类型引用的 GetMethod() 方法来获取对方法的引用。
对于 CodeProperty，该值必须是对实施 Get 访问器的方法的引用。使用类型引用的 GetMethod() 方法来获取对方法的引用。引用。该方法必须采用一个参数，即 PSObject。 Set 访问器是使用 SecondValue 参数分配的。
对于 ScriptMethod，该值必须是脚本块。
对于 ScriptProperty，该值必须是实施 Get 访问器的脚本块。 Set 访问器是使用 SecondValue 参数分配的。

类型:	Object
Position:	2
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

PSObject

你可以通过管道将任何对象传递给此 cmdlet。

输出

None

默认情况下，此 cmdlet 不返回任何输出。

Object

使用 PassThru 参数时，此 cmdlet 将返回新扩展的对象。

备注

可以仅向 PSObject 对象添加成员。若要确定对象是否为 PSObject 对象，请使用 -is 运算符。例如，要测试存储在 $obj 变量中的对象，请输入 $obj -is [psobject]。

PSObject 类型对象按照成员添加到对象的顺序维护其成员列表。

MemberType、Name、Value 和 SecondValue 参数的名称为可选项。如果省略参数名称，则未命名参数值必须按以下顺序显示：MemberType、Name、Value 和 SecondValue。

如果包括参数名称，则参数能够以任何顺序出现。

可以在定义新属性和方法的值的脚本块中使用 $this 自动变量。 $this 变量是指要向其中添加属性和方法的对象的实例。有关 $this 变量的详细信息，请参阅 about_Automatic_Variables。

通过

Add-Member

语法

说明

示例

示例 1：向 PSObject 添加注释属性

示例 2：向 PSObject 添加别名属性

示例 3：向字符串添加 StringUse 注释属性

示例 4：向 FileInfo 对象添加脚本方法

示例 5：创建自定义对象

示例 6：向对象添加 AliasProperty

示例 7：向自定义对象添加 get 和 set 方法

参数

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

输入

输出

备注

相关链接

其他资源