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>]

说明

cmdlet Add-Member 允许将成员 (属性和方法) 添加到 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：将 note 属性添加到 PSObject

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

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

第二个命令将 note 属性添加到中的 $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.txtFileInfo 对象。

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

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

2394

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

此示例将 StringUse note 属性添加到字符串。由于 Add-Member 无法向 String 输入对象添加类型，因此可以指定 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 对象， 该对象将文件大小计算为最接近的兆字节。第二个命令创建 一个 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：Create自定义对象

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

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

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

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  Age intAge
----  --- ------
Doris 20      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 参数替换类型的标准成员。

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

-InputObject

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

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

-MemberType

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

AliasProperty
CodeMethod
CodeProperty
NoteProperty
ScriptMethod
ScriptProperty

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

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

Type:	PSMemberTypes
Aliases:	Type
Accepted values:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

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

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

-NotePropertyMembers

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

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

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

-NotePropertyName

指定注释属性名称。

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

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

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

-NotePropertyValue

指定注释属性值。

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

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

Type:	Object
Position:	1
Default value:	None
Required:	True
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
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SecondValue

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

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

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

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

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

-TypeName

指定类型的名称。

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

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

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

-Value

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

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

Type:	Object
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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：将 note 属性添加到 PSObject

示例 2：将别名属性添加到 PSObject

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

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

示例 5：Create自定义对象

示例 6：向对象添加 AliasProperty

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

参数

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

输入

输出

备注

相关链接

其他资源