Add-Member

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

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 參數描述。

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

第一個命令會使用 Get-ChildItem Cmdlet 來取得代表 檔案的 Test.txt 物件。 它會將它儲存在 $a 變數中。

第二個命令會將 note 屬性新增至 $a中的物件。

第三個命令會使用點表示法來取得 中 物件的 $a 屬性值。 如輸出所示，值會 Done。

$A = Get-ChildItem C:\ps-test\test.txt
$A | Add-Member -NotePropertyName Status -NotePropertyValue Done
$A.Status

Done

下列範例會將 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

本範例會將 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

本範例會將 SizeInMB 腳本方法新增至 FileInfo 物件，此物件會將檔案大小計算為最接近的 MegaByte。 第二個命令會建立 ScriptBlock，使用 類型的 [Math] 靜態方法，將檔案大小四捨五入到第二個小數位數。

Value 參數也會使用代表目前物件的 $this 自動變數。 該 $this 變數僅適用於定義新屬性與方法的腳本區塊。

最後一個命令會使用點表示法，在 變數中的物件上呼叫新的 $A 腳本方法。

$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

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

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

在此範例中，我們會建立自定義物件，其中包含兩個 NoteProperty 成員。 NoteProperty 的型別 會反映儲存在 屬性中的值類型。 在此情況下，Age 屬性是字串。

$user = [pscustomobject]@{
    Name = 'Doris'
    Age = '20'
}
$addMemberSplat = @{
    MemberType = 'AliasProperty'
    Name = 'IntAge'
    Value = 'Age'
    SecondValue = 'UInt32'
}
$user | Add-Member @addMemberSplat
$user | 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。

此範例示範如何定義存取深層巢狀屬性的 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 屬性的值。

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

您可以將任何物件通過管道傳遞至此命令工具。

根據預設，此 Cmdlet 不會傳回任何輸出。

當您使用 PassThru 參數時，這個 Cmdlet 會傳回新擴充的物件。

您只能將成員新增至 psObject 類型物件。 若要判斷物件是否為 PSObject 物件，請使用 -is 運算符。 例如，若要測試儲存在 $obj 變數中的物件，請輸入 $obj -is [psobject]。

PSObject 類型物件會依成員新增至對象的順序維護其成員清單。

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

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

你可以在 scriptblocks 中使用 $this 自動變數來定義新屬性和方法的值。 $this 變數是指要加入屬性和方法的物件實例。 如需 $this 變數的詳細資訊，請參閱 about_Automatic_Variables。