Add-Member

Moduł:

Microsoft.PowerShell.Utility Module

Dodaje właściwości niestandardowe i metody do wystąpienia obiektu programu PowerShell.

Składnia

TypeNameSet (Domyślna)

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

NotePropertyMultiMemberSet

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

NotePropertySingleMemberSet

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

MemberSet

Add-Member
    [-MemberType] <PSMemberTypes>
    [-Name] <String>
    [[-Value] <Object>]
    [[-SecondValue] <Object>]
    -InputObject <PSObject>
    [-TypeName <String>]
    [-Force]
    [-PassThru]
    [<CommonParameters>]

Opis

Polecenie cmdlet Add-Member umożliwia dodawanie elementów członkowskich (właściwości i metod) do wystąpienia obiektu programu PowerShell. Można na przykład dodać element członkowski NoteProperty zawierający opis obiektu lub elementu członkowskiego ScriptMethod , który uruchamia skrypt w celu zmiany obiektu.

Aby użyć , należy przekazać obiekt do lub użyć parametru InputObject w celu określenia obiektu.

Parametr MemberType wskazuje typ elementu członkowskiego, który chcesz dodać. Parametr Name przypisuje nazwę do nowego elementu członkowskiego, a parametr Value ustawia wartość elementu członkowskiego.

Dodane właściwości i metody są dodawane tylko do określonego wystąpienia określonego obiektu. Add-Member nie zmienia typu obiektu. Aby utworzyć nowy typ obiektu, użyj polecenia cmdlet Add-Type.

Możesz również użyć polecenia cmdlet Export-Clixml, aby zapisać wystąpienie obiektu, w tym dodatkowe elementy członkowskie, w pliku. Następnie możesz użyć Import-Clixml polecenia cmdlet , aby ponownie utworzyć wystąpienie obiektu na podstawie informacji przechowywanych w wyeksportowanym pliku.

Począwszy od programu Windows PowerShell 3.0, Add-Member ma nowe funkcje, które ułatwiają dodawanie właściwości notatek do obiektów. Możesz użyć parametrów NotePropertyName i NotePropertyValue, aby zdefiniować właściwość notatki lub użyć parametru NotePropertyMembers, który przyjmuje tabelę skrótów nazw i wartości właściwości notatek.

Ponadto, począwszy od programu Windows PowerShell 3.0, parametr PassThru, który generuje obiekt wyjściowy, jest potrzebny rzadziej. Add-Member teraz dodaje nowe elementy członkowskie bezpośrednio do obiektu wejściowego większej liczby typów. Aby uzyskać więcej informacji, zobacz opis parametru PassThru.

Przykłady

Przykład 1. Dodawanie właściwości notatki do obiektu PSObject

W poniższym przykładzie do obiektu FileInfo dodano właściwość note Status o wartości "Done" (Gotowe).

Pierwsze polecenie używa polecenia cmdlet w celu pobrania obiektu FileInfo reprezentującego plik . Zapisuje go w zmiennej $a.

Drugie polecenie dodaje właściwość notatki do obiektu w $a.

Trzecie polecenie używa notacji kropkowej, aby uzyskać wartość właściwości Status obiektu w $a. Jak pokazują dane wyjściowe, wartość to Done.

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

Done

Przykład 2. Dodawanie właściwości aliasu do obiektu PSObject

Poniższy przykład dodaje właściwość aliasu Size do obiektu reprezentującego plik Test.txt. Nowa właściwość jest aliasem właściwości Length.

Pierwsze polecenie używa polecenia cmdlet w celu pobrania obiektu FileInfo.

Drugie polecenie dodaje właściwość Size aliasu. Trzecie polecenie używa notacji kropkowej, aby uzyskać wartość nowej właściwości Size.

$A = Get-ChildItem C:\Temp\test.txt
$A | Add-Member -MemberType AliasProperty -Name Size -Value Length
$A.Size

2394

Przykład 3. Dodawanie właściwości StringUse note do ciągu

W tym przykładzie do ciągu dodano właściwość StringUse note. Ponieważ Add-Member nie można dodać typów do obiektów wejściowych string , można określić parametr PassThru w celu wygenerowania obiektu wyjściowego. Ostatnie polecenie w przykładzie wyświetla nową właściwość.

W tym przykładzie użyto parametru NotePropertyMembers. Wartość parametru NotePropertyMembers jest tabelą skrótów. Klucz jest nazwą właściwości notatki, StringUse, a wartość jest wartością właściwości notatki, Display.

$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse

Display

Przykład 4. Dodawanie metody skryptu do obiektu FileInfo

W tym przykładzie dodano metodę skryptu SizeInMB do obiektu FileInfo , który oblicza rozmiar pliku do najbliższego megabajta. Drugie polecenie tworzy ScriptBlock, który używa metody Round statycznej z typu [Math] w celu zaokrąglenia rozmiaru pliku do drugiego miejsca dziesiętnego.

Parametr Value używa również zmiennej automatycznej $this, która reprezentuje bieżący obiekt. Zmienna $this jest prawidłowa tylko w blokach skryptów, które definiują nowe właściwości i metody.

Ostatnie polecenie używa notacji kropkowej, aby wywołać nową metodę skryptu SizeInMB w obiekcie w zmiennej $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

Przykład 5. Tworzenie obiektu niestandardowego

W tym przykładzie tworzony jest obiekt niestandardowy asset.

Polecenie New-Object cmdlet tworzy obiekt PSObject zapisany w zmiennej $Asset . Akcelerator [ordered] typów tworzy uporządkowany słownik przechowywany w zmiennej $d . Potokowanie $Asset w celu Add-Member dodawania par klucz-wartość w słowniku do obiektu jako elementów członkowskich NoteProperty . Parametr TypeName przypisuje typ Asset do obiektu PSObject. Polecenie Get-Member cmdlet pokazuje typ i właściwości obiektu. Jednak właściwości są wymienione w kolejności alfabetycznej, a nie w kolejności, w której zostały dodane.

$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

Inspekcja nieprzetworzonej listy właściwości pokazuje właściwości w kolejności, w której zostały dodane do obiektu. Format-Table jest używany w tym przykładzie do tworzenia danych wyjściowych podobnych do Get-Member.

Przykład 6. Dodawanie aliasuWłaściwości do obiektu

W tym przykładzie utworzymy obiekt niestandardowy zawierający dwa elementy członkowskie NoteProperty . Typ właściwości NoteProperty odzwierciedla typ wartości przechowywanej we właściwości. W tym przypadku właściwość Age jest ciągiem.

$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

Właściwość IntAge jest właściwością AliasProperty dla właściwości Age , ale typ ma gwarancję uint32.

Przykład 7. Dodawanie metod get i set do obiektu niestandardowego

W tych przykładach pokazano, jak zdefiniować metody Get i Set , które uzyskują dostęp do głęboko zagnieżdżonej właściwości.

$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

Zwróć uwagę, że właściwość Title jest właściwością ScriptProperty , która ma metodę Get i Set . Po przypisaniu nowej wartości do właściwości Title wywoływana jest metoda Set i zmienia wartość właściwości Rola we właściwości Position .

Parametry

-Force

Domyślnie nie można dodać nowego elementu członkowskiego, Add-Member jeśli obiekt ma już element członkowski o tym samym elemencie. W przypadku użycia parametru Add-MemberForce zastępuje istniejący element członkowski nowym elementem członkowskim. Nie można użyć parametru Force , aby zastąpić standardowy element członkowski typu.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

MemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

NotePropertySingleMemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

NotePropertyMultiMemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-InputObject

Określa obiekt, do którego jest dodawany nowy element członkowski. Wprowadź zmienną zawierającą obiekty lub wpisz polecenie lub wyrażenie, które pobiera obiekty.

Właściwości parametru

Typ:	PSObject
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	True
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-MemberType

Określa typ elementu członkowskiego do dodania. Ten parametr jest wymagany. Dopuszczalne wartości tego parametru to:

• AliasProperty
• CodeMethod
• CodeProperty
• UwagaWłaściwość
• ScriptMethod
• ScriptProperty

Aby uzyskać informacje o tych wartościach, zobacz PSMemberTypes, wyliczenie w zestawie POWERShell SDK.

Nie wszystkie obiekty mają każdy typ elementu członkowskiego. Jeśli określisz typ elementu członkowskiego, którego obiekt nie ma, program PowerShell zwróci błąd.

Właściwości parametru

Typ:	PSMemberTypes
Domyślna wartość:	None
Dopuszczalne wartości:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Obsługuje symbole wieloznaczne:	False
DontShow:	False
Aliasy:	Typ

Zestawy parametrów

MemberSet

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Name

Określa nazwę elementu członkowskiego, który dodaje to polecenie cmdlet.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

MemberSet

Position:	1
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-NotePropertyMembers

Określa tabelę skrótu lub uporządkowany słownik, który zawiera parę klucz-wartość reprezentującą nazwy właściwości Note i ich wartości. Aby uzyskać więcej informacji na temat tabel skrótów i uporządkowanych słowników w programie PowerShell, zobacz about_Hash_Tables.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	IDictionary
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

NotePropertyMultiMemberSet

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-NotePropertyName

Określa nazwę właściwości notatki.

Użyj tego parametru z parametrem NotePropertyValue. Ten parametr jest opcjonalny.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

NotePropertySingleMemberSet

Position:	0
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-NotePropertyValue

Określa wartość właściwości notatki.

Użyj tego parametru z parametrem NotePropertyName. Ten parametr jest opcjonalny.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	Object
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

NotePropertySingleMemberSet

Position:	1
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-PassThru

Zwraca obiekt reprezentujący element, z którym pracujesz. Domyślnie to polecenie cmdlet nie generuje żadnych danych wyjściowych.

W przypadku większości obiektów Add-Member dodaje nowe elementy członkowskie do obiektu wejściowego. Jeśli jednak obiekt wejściowy jest ciągiem, Add-Member nie można dodać elementu członkowskiego do obiektu wejściowego. W przypadku tych obiektów użyj parametru PassThru, aby utworzyć obiekt wyjściowy.

W programie Windows PowerShell 2.0 Add-Member dodano elementy członkowskie tylko do otoki obiektów, a nie do obiektu. Użyj parametru PassThru, aby utworzyć obiekt wyjściowy dla dowolnego obiektu, który ma otokę PSObject.

Właściwości parametru

Typ:	SwitchParameter
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

(All)

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-SecondValue

Określa opcjonalne dodatkowe informacje o elementach członkowskich AliasProperty, ScriptProperty lub CodeProperty .

Jeśli jest używany podczas dodawania AliasProperty, ten parametr musi być typem danych. Konwersja na określony typ danych jest dodawana do wartości AliasProperty. Jeśli na przykład dodasz aliasProperty , który udostępnia alternatywną nazwę właściwości ciągu, możesz również określić parametr SecondValueelementu System.Int32 , aby wskazać, że wartość tej właściwości ciągu powinna zostać przekonwertowana na liczbę całkowitą podczas uzyskiwania dostępu przy użyciu odpowiedniego aliasuWłaściwości.

W przypadku właściwości CodeProperty wartość musi być odwołaniem do metody, która implementuje metodę Ustawia metodę dostępu. GetMethod() Użyj metody odwołania typu, aby uzyskać odwołanie do metody. Metoda musi przyjmować jeden parametr, który jest obiektem PSObject. Metodę uzyskiwania dostępu przypisano przy użyciu parametru Value.

W przypadku właściwości ScriptProperty wartość musi być blokiem skryptu, który implementuje metodę dostępu zestawu . Metodę uzyskiwania dostępu przypisano przy użyciu parametru Value.

Właściwości parametru

Typ:	Object
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

MemberSet

Position:	3
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-TypeName

Określa nazwę typu.

Gdy typ jest klasą w System przestrzeni nazw lub typu z akceleratorem typu, możesz wprowadzić krótką nazwę typu. W przeciwnym razie wymagana jest pełna nazwa typu. Ten parametr jest skuteczny tylko wtedy, gdy InputObject jest psObject.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Właściwości parametru

Typ:	String
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

TypeNameSet

Position:	Named
Obowiązkowy:	True
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

NotePropertyMultiMemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

NotePropertySingleMemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

MemberSet

Position:	Named
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

-Value

Określa początkową wartość dodanego elementu członkowskiego. Jeśli dodasz element członkowski AliasProperty, CodeProperty lub ScriptProperty , możesz podać dodatkowe informacje przy użyciu parametru SecondValue .

• W przypadku aliasuWłaściwości wartość musi być nazwą właściwości, która jest aliasowana.
• W przypadku metody CodeMethod wartość musi być odwołaniem do metody. GetMethod() Użyj metody odwołania typu, aby uzyskać odwołanie do metody.
• W przypadku właściwości CodeProperty wartość musi być odwołaniem do metody, która implementuje metodę Get accessor. GetMethod() Użyj metody odwołania typu, aby uzyskać odwołanie do metody. odniesienie. Metoda musi przyjmować jeden parametr, który jest obiektem PSObject. Zestaw metod dostępu jest przypisywany przy użyciu parametru SecondValue.
• W przypadku elementu ScriptMethod wartość musi być blokiem skryptu.
• W przypadku właściwości ScriptProperty wartość musi być blokiem skryptu, który implementuje metodę Uzyskiwanie dostępu. Zestaw metod dostępu jest przypisywany przy użyciu parametru SecondValue.

Właściwości parametru

Typ:	Object
Domyślna wartość:	None
Obsługuje symbole wieloznaczne:	False
DontShow:	False

Zestawy parametrów

MemberSet

Position:	2
Obowiązkowy:	False
Wartość z potoku:	False
Wartość z potoku według nazwy właściwości:	False
Wartość z pozostałych argumentów:	False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Dane wejściowe

PSObject

Do tego polecenia cmdlet można przekierować dowolny obiekt.

Dane wyjściowe

None

Domyślnie to polecenie cmdlet nie zwraca żadnych danych wyjściowych.

Object

Jeśli używasz parametru PassThru , to polecenie cmdlet zwraca nowo rozszerzony obiekt.

Uwagi

Można dodawać elementy członkowskie tylko do obiektów typu PSObject . Aby określić, czy obiekt jest obiektem psObject, użyj operatora -is. Na przykład aby przetestować obiekt przechowywany w zmiennej $obj, wpisz $obj -is [psobject].

Obiekty typu PSObject utrzymują listę elementów członkowskich w kolejności, w których składowe zostały dodane do obiektu.

Nazwy MemberType, Name, Valuei parametry SecondValue są opcjonalne. Jeśli pominięto nazwy parametrów, nienazwane wartości parametrów muszą pojawić się w następującej kolejności: MemberType, Name, Valuei SecondValue.

Jeśli uwzględnisz nazwy parametrów, parametry mogą być wyświetlane w dowolnej kolejności.

Można użyć $this automatycznej zmiennej w blokach skryptów, które definiują wartości nowych właściwości i metod. Zmienna $this odnosi się do wystąpienia obiektu, do którego dodawane są właściwości i metody. Aby uzyskać więcej informacji na temat zmiennej $this, zobacz about_Automatic_Variables.

Linki powiązane

• Export-Clixml
• Get-Member
• Import-Clixml
• New-Object
• o_Zmiennych_Automatycznych
• System.Type.GetMethod()