Add-Member

為 Windows PowerShell 物件的執行個體加入使用者定義的自訂成員。

語法

Add-Member [-MemberType] {<AliasProperty> | <CodeProperty> | <Property> | <NoteProperty> | <ScriptProperty> | <Properties> | <PropertySet> | <Method> | <CodeMethod> | <ScriptMethod> | <Methods> | <ParameterizedProperty> | <MemberSet> | <Event> | <All>} [-Name] <string> -InputObject <psobject> [[-Value] <Object>] [[-SecondValue] <Object>] [-Force] [-PassThru] [<CommonParameters>]

描述

Add-Member Cmdlet 會為 Windows PowerShell 物件的執行個體新增使用者定義的自訂成員。它可讓您加入下列成員類型：AliasProperty、CodeProperty、NoteProperty、ScriptProperty、PropertySet、CodeMethod、MemberSet 和 ScriptMethod。您可以使用 Value 參數來設定成員的初始值。如果是 AliasProperty、ScriptProperty、CodeProperty 和 CodeMethod，則可以使用 SecondValue 參數來提供其他資訊。

其他的成員會加入至您經由管道輸出至 Add-Member 或是使用 InputObject 參數所指定的特定物件執行個體中。其他的成員只有在該執行個體存在時才能使用。您可以使用 Export-Clixml Cmdlet，將執行個體 (包括其他成員) 儲存至檔案。Import-Clixml Cmdlet 則可以使用該檔案中儲存的資訊來重新建立物件執行個體。

參數

-Force

即使已有名稱相同的成員，亦強制加入新成員。不適用於類型的核心成員。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-InputObject <psobject>

指定要加入新成員的物件。請輸入包含物件的變數，或輸入可取得物件的命令或運算式。

必要?	true
位置?	named
預設值
接受管線輸入?	true (ByValue)
接受萬用字元?	false

-MemberType <PSMemberTypes>

指定要新增的成員型別。此參數是必要的。

此參數的有效值為：

-- AliasProperty：為現有屬性定義新名稱的屬性。

-- CodeMethod：參考 Microsoft .NET Framework 類別之靜態方法的某個方法。

-- CodeProperty：參考 .NET Framework 類別之靜態屬性的某個屬性。

-- MemberSet：屬性及方法的預先定義的集合，例如 PSBase、PSObject 和 PSTypeNames。

-- Method：基礎 .NET Framework 物件的方法。

-- NoteProperty：有靜態值的屬性。

-- ParameterizedProperty：接受參數和參數值的屬性。

-- Property：基礎 .NET Framework 物件的屬性。

-- PropertySet：物件屬性的預先定義的集合。

-- ScriptMethod：值為指令碼輸出的方法。

-- ScriptProperty：值為指令碼輸出的屬性。

-- All：取得所有成員型別。

-- Methods：取得物件方法的所有型別 (例如 method、codemethod、scriptmethod)

-- Properties：取得物件屬性的所有型別 (例如 property、codeproperty、aliasproperty、scriptproperty)。

並不是所有物件都有全部的成員型別。如果指定物件所沒有的成員型別，Windows PowerShell 就會傳回錯誤。

Event 成員型別不適用於 Add-Member。

必要?	true
位置?	1
預設值
接受管線輸入?	false
接受萬用字元?	true

-Name <string>

指定所加入成員的名稱。

如果省略 "Name" 參數名稱，-Name 參數的值就必須是命令中第二個未具名的參數值。如果包含參數名稱，則可依任意順序列出參數。

必要?	true
位置?	2
預設值
接受管線輸入?	false
接受萬用字元?	false

-PassThru

將新擴充的物件傳遞給管線。根據預設，此 Cmdlet 不會產生任何輸出。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-SecondValue <Object>

指定有關 AliasProperty、ScriptProperty、CodeProperty 或 CodeMethod 成員的其他選擇性資訊。若在加入 AliasProperty 時使用，則此參數必須是資料類型。AliasProperty 的值會經過轉換成為指定的資料類型。例如，若您加入 AliasProperty 以提供字串屬性的替代名稱，便可將 SecondValue 參數指定為 System.Int32，表示每當使用對應的 AliasProperty 存取該字串屬性時，都應該將其值轉換成整數。

加入 ScriptProperty 成員時可以使用 SecondValue 參數額外指定 ScriptBlock。在此情況下，便會使用 Value 參數內指定的第一個 ScriptBlock 來取得變數的值。SecondValue 參數內指定的第二個 ScriptBlock 會用來設定變數的值。

必要?	false
位置?	4
預設值
接受管線輸入?	false
接受萬用字元?	false

-Value <Object>

指定所加入成員的初始值。如果加入的是 AliasProperty、CodeProperty 或 CodeMethod 成員，則可使用 SecondValue 參數提供其他選擇性資訊。

必要?	false
位置?	3
預設值
接受管線輸入?	false
接受萬用字元?	false

<CommonParameters>

這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入	System.Management.Automation.PSObject 您可經由管道將任何物件類型輸出至 Add-Member。
輸出	無或 System.Object 當您使用 PassThru 參數時，Add-Member 會傳回新擴充的物件。否則，這個 Cmdlet 不會產生任何輸出。

附註

您只能將成員加入至 PSObject 物件。若要判斷物件是否為 PSObject 物件，請使用 "is" 運算子。例如，若要測試 $obj 變數中儲存的物件，可以輸入 "$obj -is [PSObject]"。

MemberType、Name、Value 及 SecondValue 參數的名稱為選擇性。如果省略參數名稱，就必須依此順序列出未具名的參數值：MemberType、Name、Value、SecondValue。如果包含參數名稱，則可依任意順序列出參數。

範例 1

C:\PS>$a = (get-childitem)[0]

C:\PS> $a | add-member -membertype noteproperty -name Status -value done

C:\PS> $a | get-member -type noteproperty

   TypeName: System.IO.DirectoryInfo

Name          MemberType   Definition
----          ----------   ----------
PSChildName   NoteProperty System.String PSChildName=Co
PSDrive       NoteProperty System.Management.Automation
PSIsContainer NoteProperty System.Boolean PSIsContainer
PSParentPath  NoteProperty System.String PSParentPath=M
PSPath        NoteProperty System.String PSPath=Microso
PSProvider    NoteProperty System.Management.Automation
Status        NoteProperty System.String Status=done

描述
-----------
這些命令會將 Status note 屬性加入至 Get-ChildItem 所傳回的 DirectoryInfo 物件中，並為它指派 "done" 的值。

第一個命令會取得 Get-Childitem 所傳回的第一個物件 (索引 0)。

第二個命令會加入 note 屬性。

第三個命令會使用管線運算子 (|)，將更新的物件傳送到 Get-Member Cmdlet。輸出會顯示已經加入此屬性。

範例 2

C:\PS>$a = (get-childitem)[0]

C:\PS> $a | add-member -membertype aliasproperty -name FileLength -value Length 

C:\PS> $a.filelength

描述
-----------
這些命令會將 FileLength alias 屬性加入至 Get-ChildItem 所傳回的 DirectoryInfo 物件。新的屬性是 Length 屬性的別名。

第一個命令會取得 Get-Childitem 所傳回的第一個物件 (索引 0)。

第二個命令會加入 alias 屬性。

第三個命令會傳回新 FileLength 屬性的值。

範例 3

C:\PS>$a = "a string"

C:\PS> $a = $a | add-member -membertype noteproperty -name StringUse -value Display -passthru

C:\PS> $a.StringUse

描述
-----------
這些命令會將 StringUse 屬性加入至字串。因為此字串並非 PSObject 物件，所以您必須在命令中指定 PassThru 參數，才能將擴充的字串儲存到變數中。範例中的最後一個命令會顯示新的屬性。

範例 4

C:\PS>$a = "this is a string"

C:\PS> $a = add-member -inputobject $a -membertype scriptmethod -name words `
-value {$this.split()} -passthru

C:\PS> $a.words()

描述
-----------
這些命令會將指令碼方法加入至字串物件。這個指令碼方法公開 System.String .NET Framework 類別庫類別的 Split() 方法，可讓您很方便地藉由呼叫字串物件上名為 "Words" 的方法，傳回字串中的個別單字。請注意，指定 PassThru 參數是為了強制 Add-Member 將擴充的字串物件當做輸出傳回，以便儲存至 $a 變數中。

範例 5

C:\PS>$event = get-eventlog -logname system -newest 1

C:\PS> $event.TimeWritten | get-member

C:\PS> add-member -inputobject $event -membertype aliasproperty -name When `
-value TimeWritten -secondvalue System.String

C:\PS> $event.When | get-member

描述
-----------
這些命令會將 AliasProperty 加入至 Get-EventLog Cmdlet 所傳回的 EventLogEntry 物件。AliasProperty 的名稱為 "When"，而且是物件之 TimeWritten 屬性的別名。SecondValue 參數是用來指定：當使用 AliasProperty 存取屬性值時，必須將它轉換為類型 System.String；TimeWritten 屬性為 DateTime 物件。

第一個命令會使用 Get-EventLog Cmdlet，從系統事件記錄檔擷取最新的事件，並將它儲存在 $event 變數中。

第二個命令會存取該事件的 TimeWritten 屬性，並經由管道將它輸入至 Get-Member Cmdlet，表明該屬性為 DateTime 類型。然後使用 Add-Member 將 AliasProperty 成員加入至儲存於 $event 變數的 EventLogEntry 物件執行個體。Name 參數用於將新成員的名稱設定為 "When"，而 Value 參數則用於指定此成員是 TimeWritten 屬性的別名。SecondValue 參數用來表示：使用這個新成員時，應該將它傳回的值從原始的 System.DateTime 類型轉換為 System.String 類型。

第三個命令會存取新成員，並經由管道將它輸入至 Get-Member Cmdlet，以確認它屬於類型 System.String。

範例 6

C:\PS>function Copy-Property ($From, $To)

{
  foreach ($p in Get-Member -InputObject $From -MemberType Property)
  {
     Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name 
     -Value $From.$($p.Name) -Force

     $To.$($p.Name) = $From.$($p.Name)
   }
}

描述
-----------
這個函數會將一個物件的所有屬性複製到另一個物件。

函數的第一個命令會宣告此函數名稱，並列出其參數。

Foreach 迴圈會使用 Get-Member Cmdlet 取得 From 物件的每個屬性。而 Foreach 迴圈內的命令會連續在每個屬性上執行。

Add-Member 命令會將 From 物件的屬性加入至 To 物件當做 NoteProperty。它會使用 Force 參數讓此命令加入同名的成員。

函數的最後一個命令是將新屬性命名為與原始屬性同名。

請參閱

概念

Get-Member
Export-Clixml
Import-Clixml