Add-Member

Odwołanie

Moduł:: Microsoft.PowerShell.Utility

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

Składnia

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

Opis

Polecenie Add-Member cmdlet 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ć Add-Membermetody , należy przekazać obiekt do Add-Memberobiektu lub użyć parametru InputObject , aby określić obiekt.

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 Add-Type polecenia cmdlet .

Możesz również użyć Export-Clixml polecenia cmdlet , 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 dodano właściwość Nota stanu z wartością "Done" do obiektu FileInfo reprezentującego Test.txt plik.

Pierwsze polecenie używa Get-ChildItem polecenia cmdlet do pobrania obiektu FileInfo reprezentującego Test.txt plik. Zapisuje go w zmiennej $a .

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

Trzecie polecenie używa notacji kropkowej, aby uzyskać wartość właściwości Status obiektu w pliku $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

W poniższym przykładzie do obiektu, który reprezentuje plik, dodaje właściwość aliasu Test.txt Size. Nowa właściwość jest aliasem właściwości Length .

Pierwsze polecenie używa Get-ChildItem polecenia cmdlet do pobrania Test.txtobiektu FileInfo .

Drugie polecenie dodaje właściwość aliasu Size . 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 dodano właściwość StringUse note do ciągu. 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 note, 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 skryptBlock, który używa metody statycznej Round z [math] typu, aby zaokrąglić rozmiar pliku do drugiego miejsca dziesiętnego.

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

Ostatnie polecenie używa notacji kropkowej do wywołania nowej metody skryptu SizeInMB na 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 elementu zawartości .

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.

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

Właściwość intAge jest właściwością AliasProperty 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-Member Force 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.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	PSObject
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	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.

Type:	PSMemberTypes
Aliases:	Type
Accepted values:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

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

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	IDictionary
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	Object
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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 OBIEKTU PSObject , a nie do obiektu. Użyj parametru PassThru , aby utworzyć obiekt wyjściowy dla dowolnego obiektu, który ma otokę PSObject .

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SecondValue

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

Jeśli jest używany podczas dodawania aliasuWłaściwości, 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 SecondValue elementu 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.

Type:	Object
Position:	3
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TypeName

Określa nazwę typu.

Jeśli typ jest klasą w przestrzeni nazw systemu lub typem, który ma akcelerator typu, możesz wprowadzić krótką nazwę typu. W przeciwnym razie wymagana jest pełna nazwa typu. Ten parametr jest skuteczny tylko wtedy, gdy obiekt InputObject jest obiektem PSObject.

Ten parametr został wprowadzony w programie Windows PowerShell 3.0.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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. Odwołanie. 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.

Type:	Object
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Dane wejściowe

PSObject

Do tego polecenia cmdlet można przekazać 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 -is operatora . 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 parametrów MemberType, Name, Value i SecondValue są opcjonalne. Jeśli pominięto nazwy parametrów, nienazwane wartości parametrów muszą być wyświetlane w następującej kolejności: MemberType, Name, Value i SecondValue.

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

Możesz użyć zmiennej automatycznej $this w blokach skryptu, które definiują wartości nowych właściwości i metod. Zmienna $this odwołuje 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.

Add-Member

Składnia

Opis

Przykłady

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

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

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

Przykład 4. Dodawanie metody skryptu do obiektu FileInfo

Przykład 5. Tworzenie obiektu niestandardowego

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

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

Parametry

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

Dane wejściowe

Dane wyjściowe

Uwagi

Opinia

Dodatkowe zasoby

Add-Member

Składnia

Opis

Przykłady

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

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

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

Przykład 4. Dodawanie metody skryptu do obiektu FileInfo

Przykład 5. Tworzenie obiektu niestandardowego

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

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

Parametry

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Opinia

Dodatkowe zasoby