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

Description

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 note 屬性新增至代表 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 alias 屬性新增至代表 Test.txt 檔案的物件。新屬性是 Length 屬性的別名。

第一個命令會使用 Get-ChildItem Cmdlet 來取得 Test.txtFileInfo 物件。

第二個命令會新增 Size alias 屬性。第三個命令會使用點表示法來取得新 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，使用 [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 變數中的已排序字典。管線 $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 屬性是字串。

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 參數來取代類型的標準成員。

類型:	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

指定 note 屬性值。

使用此參數搭配 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

語法

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

語法

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

輸入

輸出

備註

相關連結

其他資源