Add-Member

模組:

Microsoft.PowerShell.Utility

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

語法

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

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

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

Add-Member
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   -InputObject <PSObject>
   [-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 屬性新增至字串。 因為 無法將類型新增至 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：將物件的所有屬性複製到另一個屬性

此函式會將一個物件的所有屬性複製到另一個物件。

迴圈會使用 Cmdlet 來取得from 物件 的每個屬性。 foreach 迴圈內的命令會在每個屬性上以數列方式執行。

命令會將From 物件的 屬性新增至 To 物件，做為 NoteProperty。 值是使用 Value 參數複製。 它會使用 Force 參數來新增具有相同成員名稱的成員。

function Copy-Property ($From, $To)
{
    $properties = Get-Member -InputObject $From -MemberType Property
    foreach ($p in $properties)
    {
        $To | Add-Member -MemberType NoteProperty -Name $p.Name -Value $From.$($p.Name) -Force
    }
}

範例 6：建立自定義物件

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

New-Object Cmdlet 會建立 PSObject。 此範例會將 PSObject 儲存在 $Asset 變數中。

第二個命令會使用 [ordered] 類型加速器來建立名稱和值的已排序字典。 命令會將結果儲存在 $D 變數中。

第三個命令會使用 NotePropertyMembers 參數的 Cmdlet，將 變數中的字典新增至 psObject。 TypeName 屬性會將新的名稱 Asset指派給 psObject 。

最後一個命令會將新的 Asset 物件傳送至 Get-Member Cmdlet。 輸出顯示物件的類型名稱為 Asset，以及我們在已排序字典中定義的附註屬性。

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InputObject

指定加入新成員的物件。 輸入包含 物件的變數，或輸入取得物件的命令或表達式。

類型:	PSObject
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-MemberType

指定要加入的成員類型。 這是必要參數。 此參數可接受的值為：

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

如需這些值的相關信息，請參閱 MSDN 連結庫中 PSMemberTypes 列舉。

並非所有物件都有每種成員類型。 如果您指定對象沒有的成員類型，PowerShell 會傳回錯誤。

類型:	PSMemberTypes
別名:	Type
接受的值:	AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:	0
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-Name

指定這個 Cmdlet 新增的成員名稱。

類型:	String
Position:	1
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-NotePropertyMembers

指定附註屬性名稱和值的哈希表或已排序字典。 輸入哈希表或字典，其中索引鍵是 note 屬性名稱，而值是 note 屬性值。

如需 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或 CodeMethod 成員的選擇性其他資訊。

如果在新增 AliasProperty時使用 ，此參數必須是數據類型。 轉換成指定的數據類型會新增至 AliasProperty的值。

例如，如果您新增提供字串屬性替代名稱的 AliasProperty，您也可以指定 System.Int32 的 SecondValue 參數，指出當使用對應的 AliasProperty存取時，該字元串屬性的值應該轉換成整數。

您可以在新增 ScriptProperty 成員時，使用 SecondValue 參數來指定額外的 ScriptBlock。 在 Value 參數中指定的第一個 ScriptBlock，是用來取得變數的值。 第二個 ScriptBlock，在 SecondValue 參數中指定，用來設定變數的值。

類型:	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 或 CodeMethod 成員，您可以使用 SecondValue 參數來提供選擇性的其他資訊。

類型:	Object
Position:	2
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

PSObject

您可以使用管線將任何物件類型傳送至此 Cmdlet。

輸出

None or System.Object

當您使用 PassThru 參數時，這個 Cmdlet 會傳回新擴充的物件。 否則，此 Cmdlet 不會產生任何輸出。

備註

您只能將成員新增至 PSObject 物件。 若要判斷物件是否為 PSObject 物件，請使用 -is 運算符。

例如，若要測試儲存在 $obj 變數中的物件，請輸入 $obj -is [PSObject]。

MemberType、Name、Value和 SecondValue 參數的名稱是選擇性的。 如果您省略參數名稱，則未命名的參數值必須依下列順序顯示：MemberType、Name、Value和 SecondValue。

如果您包含參數名稱，參數可以依任何順序顯示。

您可以在訂新屬性和方法值的腳本區塊中使用 $this 自動變數。 $this 變數是指要加入屬性和方法的物件實例。 如需 $this 變數的詳細資訊，請參閱 about_Automatic_Variables。

相關連結

• Export-Clixml
• Get-Member
• Import-Clixml
• New-Object
• about_Automatic_Variables