Add-Member

參考

模組:: Microsoft.PowerShell.Utility

將自定義屬性和方法新增至 PowerShell 物件的實例。

Syntax

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

Description

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：將附注屬性新增至 PSObject

下列範例會將 Status note 屬性，其值為「Done」新增至代表檔案的 Test.txt FileInfo 物件。

第一個命令會Get-ChildItem使用 Cmdlet 來取得代表檔案的 Test.txt FileInfo 物件。它會將它儲存在變數中 $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 物件，此物件會將檔案大小計算為最接近的 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：建立自定義物件

此範例會 建立 Asset 自定義物件。

Cmdlet New-Object 會建立儲存在變數中的 $Asset PSObject。 [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

指定 note 屬性值。

搭配 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

Syntax

Description

範例

範例 1：將附注屬性新增至 PSObject

範例 2：將別名屬性新增至 PSObject

範例 3：將 StringUse note 屬性新增至字串

範例 4：將腳本方法新增至 FileInfo 物件

範例 5：建立自定義物件

範例 6：將 AliasProperty 新增至物件

範例 7：將 get 和 set 方法新增至自定義物件

參數

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

輸入

輸出

備註

意見反應

其他資源

Add-Member

Syntax

Description

範例

範例 1：將附注屬性新增至 PSObject

範例 2：將別名屬性新增至 PSObject

範例 3：將 StringUse note 屬性新增至字串

範例 4：將腳本方法新增至 FileInfo 物件

範例 5：建立自定義物件

範例 6：將 AliasProperty 新增至物件

範例 7：將 get 和 set 方法新增至自定義物件

參數

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

輸入

輸出

備註

相關連結

意見反應

其他資源