Add-Member

模块:: Microsoft.PowerShell.Utility Module

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

语法

TypeNameSet (默认值)

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

NotePropertyMultiMemberSet

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

NotePropertySingleMemberSet

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

MemberSet

Add-Member
    [-MemberType] <PSMemberTypes>
    [-Name] <String>
    [[-Value] <Object>]
    [[-SecondValue] <Object>]
    -InputObject <PSObject>
    [-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 添加备注属性

以下示例向表示文件的 FileInfo 对象添加值为“Done”的 Test.txt note 属性。

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

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

第三个命令使用点表示法获取中对象的 $a 属性的值。如输出所示，该值 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.txtFileInfo 对象。

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

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

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

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

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

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

Display

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

此示例将 SizeInMB 脚本方法添加到 FileInfo 对象，该对象将文件大小计算为最近的 MegaByte。第二个命令创建一个 ScriptBlock，该脚本块使用 Round 静态方法从 [Math] 类型将文件大小舍入到第二个小数位。

Value 参数还使用表示当前对象的 $this 自动变量。该 $this 变量仅在定义新属性和方法的 scriptblock 中有效。

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

$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：创建自定义对象

此示例创建资产自定义对象。

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

$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 -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 属性是字符串。

$user = [pscustomobject]@{
    Name = 'Doris'
    Age = '20'
}
$addMemberSplat = @{
    MemberType = 'AliasProperty'
    Name = 'IntAge'
    Value = 'Age'
    SecondValue = 'UInt32'
}
$user | Add-Member @addMemberSplat
$user | 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  Age IntAge
----  --- ------
Doris 20      20

PS> $obj.Age + 1

201

PS> $obj.IntAge + 1

21

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

示例 7：向自定义对象添加 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
默认值:	None
支持通配符:	False
不显示:	False

参数集

MemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

NotePropertySingleMemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

NotePropertyMultiMemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-InputObject

指定将新成员添加到的对象。输入包含对象的变量，或键入获取对象的命令或表达式。

参数属性

类型:	PSObject
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	True
来自管道的值:	True
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-MemberType

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

AliasProperty
CodeMethod
CodeProperty
NoteProperty
ScriptMethod
ScriptProperty

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

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

参数属性

类型:	PSMemberTypes
默认值:	None
接受的值:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
支持通配符:	False
不显示:	False
别名:	类型

参数集

MemberSet

Position:	0
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Name

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

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

MemberSet

Position:	1
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-NotePropertyMembers

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

此参数是在 Windows PowerShell 3.0 中引入的。

参数属性

类型:	IDictionary
默认值:	None
支持通配符:	False
不显示:	False

参数集

NotePropertyMultiMemberSet

Position:	0
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-NotePropertyName

指定 note 属性名称。

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

此参数是在 Windows PowerShell 3.0 中引入的。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

NotePropertySingleMemberSet

Position:	0
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-NotePropertyValue

指定注释属性值。

将此参数与 NotePropertyName 参数一起使用。此参数是可选的。

此参数是在 Windows PowerShell 3.0 中引入的。

参数属性

类型:	Object
默认值:	None
支持通配符:	False
不显示:	False

参数集

NotePropertySingleMemberSet

Position:	1
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-PassThru

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

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

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

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	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
默认值:	None
支持通配符:	False
不显示:	False

参数集

MemberSet

Position:	3
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-TypeName

指定类型的名称。

当类型是系统命名空间中的类或具有类型加速器的类型时，可以输入类型的短名称。否则，需要完整类型名称。此参数仅在 InputObject 是 PSObject时才有效。

此参数是在 Windows PowerShell 3.0 中引入的。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

TypeNameSet

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

NotePropertyMultiMemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

NotePropertySingleMemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

MemberSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Value

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

对于 AliasProperty，该值必须是要别名的属性的名称。
对于 CodeMethod，该值必须是对方法的引用。使用类型引用的 GetMethod() 方法获取对方法的引用。
对于 CodeProperty，该值必须是对实现 Get 访问器的方法的引用。使用类型引用的 GetMethod() 方法获取对方法的引用。参考。该方法必须采用 PSObject的单个参数。 Set 访问器是使用 SecondValue 参数分配的。
对于 ScriptMethod，该值必须是 scriptblock。
对于 ScriptProperty，该值必须是实现 Get 访问器的 scriptblock。 Set 访问器是使用 SecondValue 参数分配的。

参数属性

类型:	Object
默认值:	None
支持通配符:	False
不显示:	False

参数集

MemberSet

Position:	2
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

CommonParameters

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。有关详细信息，请参阅 about_CommonParameters。

输入

PSObject

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

输出

None

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

Object

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

备注

只能将成员添加到 PSObject 类型对象。若要确定对象是否为 PSObject 对象，请使用 -is 运算符。例如，若要测试存储在 $obj 变量中的对象，请键入 $obj -is [psobject]。

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

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

如果包括参数名称，参数可以按任意顺序显示。

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

反馈

此页面是否有帮助？

Add-Member

语法

TypeNameSet (默认值)

NotePropertyMultiMemberSet

NotePropertySingleMemberSet

MemberSet

说明

示例

示例 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

参数属性

参数集

CommonParameters

输入

PSObject

输出

None

Object

备注

相关链接

反馈