Add-Member

語法

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.txt FileInfo 物件。

第二個命令會新增 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

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

輸入

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。

相關連結

• Export-Clixml
• Get-Member
• Import-Clixml
• New-Object
• about_Automatic_Variables
• System.Type.GetMethod（）