Add-Member
將自定義屬性和方法新增至 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
下列範例會在代表Test.txt檔案的 FileInfo 物件中新增值為 “Done” 的 Status note 屬性。
第一個命令會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 附注屬性新增至字串
本範例會將 StringUse 附註屬性新增至字串。
因為 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：將物件的所有屬性複製到另一個屬性
此函式會將一個物件的所有屬性複製到另一個物件。
迴圈 foreach 會 Get-Member 使用 Cmdlet 來取得 From 物件的每個屬性。 迴圈內的 foreach 命令會在每個屬性上以數列方式執行。
Add-Member命令會將 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：Create 自定義物件
此範例會建立 Asset 自定義物件。
Cmdlet New-Object 會建立 PSObject。 此範例會將 PSObject 儲存在 變數中 $Asset 。
第二個命令會 [ordered] 使用型別加速器來建立名稱和值的已排序字典。 命令會將結果儲存在變數中 $D 。
第三個命令會使用 Cmdlet 的 Add-MemberNotePropertyMembers 參數，將變數中的$D字典新增至 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 參數來取代類型的標準成員。
| 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
指定要加入的成員類型。 此為必要參數。 此參數可接受的值為：
- 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 |
| 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
指定內容是附註屬性名稱和值的雜湊表或排序的字典。 輸入其中的索引鍵為附註屬性名稱且值為附註屬性值的雜湊表或字典。
如需 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 或 CodeMethod 成員相關的其他選擇性資訊。
如果在新增 AliasProperty 時使用，此參數必須是數據類型。 轉換至指定的數據類型會新增至 AliasProperty 的值。
例如，如果您新增 AliasProperty 來提供字串屬性的替代名稱，您也可以指定 System.Int32 的 SecondValue 參數，以指出使用對應的 AliasProperty 存取時，該字串屬性的值應該轉換成整數。
新增 ScriptProperty 成員時，您可以使用 SecondValue 參數來指定額外的 ScriptBlock。 Value 參數中指定的第一個 ScriptBlock 可用來取得變數的值。 SecondValue 參數中指定的第二個 ScriptBlock 可用來設定變數的值。
| 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 或 CodeMethod 成員，您可以使用 SecondValue 參數來提供選擇性的其他資訊。
| Type: | Object |
| Position: | 2 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
輸入
您可以使用管線將任何物件類型傳送至此 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。