Add-Member

将自定义属性和方法添加到 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具有一些新功能,可更轻松地向对象添加笔记属性。 可以使用 NotePropertyNameNotePropertyValue 参数定义附注属性,或使用 NotePropertyMembers 参数,该参数采用包含附注属性名称和值的哈希表。

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

示例

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

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

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

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

第三个命令使用点表示法获取对象在 中的$aStatus 属性的值。 如输出所示,值为“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

2394

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

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

此示例使用 NotePropertyMembers 参数。 NotePropertyMembers 参数的值是一个哈希表。 键是注释属性名称 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 变量仅在定义新属性和方法的脚本块中有效。

最后一个命令使用点表示法对变量中的$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:创建自定义对象

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

New-Object cmdlet 创建 PSObject。 该示例将 PSObject 保存在变量中 $Asset

第二个命令使用 [ordered] 类型加速器创建名称和值的有序字典。 该命令将结果保存在变量中 $D

第三个命令使用 cmdlet 的 Add-MemberNotePropertyMembers 参数将变量中的$D字典添加到 PSObjectTypeName 属性将新名称资产分配给 PSObject

最后一个命令通过管道将新的 Asset 对象传递给 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

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 System.String Name=Server30
PSVersion   NoteProperty System.String PSVersion=4.0
System      NoteProperty System.String System=Server Core

参数

-Force

指示此 cmdlet 会添加新成员,即使对象具有具有相同名称的自定义成员。 不能使用 Force 参数替换类型的标准成员。

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

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

Type:PSObject
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-MemberType

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

  • NoteProperty
  • AliasProperty
  • ScriptProperty
  • CodeProperty
  • ScriptMethod
  • CodeMethod

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

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

Type:PSMemberTypes
Aliases:Type
Accepted values:AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Name

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

Type:String
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyMembers

指定附注属性名称和值的哈希表或有序字典。 键入哈希表或字典,其中的键为附注属性名称,值为附注属性值。

有关 PowerShell 中的哈希表和有序字典的详细信息,请参阅 about_Hash_Tables

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

Type:IDictionary
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyName

指定注释属性名称。

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

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

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NotePropertyValue

指定注释属性值。

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

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

Type:Object
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

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

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

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

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-SecondValue

指定有关 AliasPropertyScriptPropertyCodePropertyCodeMethod 成员的可选附加信息。

如果在添加 AliasProperty 时使用,此参数必须是数据类型。 将转换为指定的数据类型添加到 AliasProperty 的值。

例如,如果添加为字符串属性提供备用名称的 AliasProperty,还可以指定 System.Int32SecondValue 参数,以指示当使用相应的 AliasProperty 访问时,该字符串属性的值应转换为整数。

添加 ScriptProperty 成员时,可以使用 SecondValue 参数指定其他 ScriptBlockValue 参数中指定的第一个 ScriptBlock 用于获取变量的值。 SecondValue 参数中指定的第二个 ScriptBlock 用于设置变量的值。

Type:Object
Position:3
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TypeName

指定类型的名称。

当类型是 System 命名空间中的类或具有类型加速器的类型时,可以输入类型的短名称。 否则,必须输入完整类型名称。 仅当 InputObjectPSObject 时,此参数才有效。

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

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Value

指定已添加成员的初始值。 如果添加 AliasPropertyCodePropertyScriptPropertyCodeMethod 成员,则可以使用 SecondValue 参数提供可选的其他信息。

Type:Object
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

输入

PSObject

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

输出

None or System.Object

使用 PassThru 参数时,此 cmdlet 返回新扩展的对象。 否则,此 cmdlet 将不生成任何输出。

备注

只能将成员添加到 PSObject 对象。 若要确定对象是否为 PSObject 对象,请使用 -is 运算符。

例如,若要测试存储在变量中的 $obj 对象,请键入 $obj -is [PSObject]

MemberTypeNameValueSecondValue 参数的名称是可选的。 如果省略参数名称,则未命名的参数值必须按以下顺序显示: MemberTypeNameValueSecondValue

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

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