Add-Member

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-Membermetody 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 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 Windows PowerShell 3.0, ma nowe funkcje, Add-Member 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 Windows PowerShell 3.0, parametr PassThru, który generuje obiekt wyjściowy, jest wymagany 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, który reprezentuje Test.txt plik, dodaje właściwość Notatki o stanie z wartością "Done".

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ść note do obiektu w pliku $a.

Trzecie polecenie używa notacji kropkowej, aby uzyskać wartość właściwości Status obiektu w .$a Jak widać w danych wyjściowych, wartość to "Done" (Gotowe).

$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, który reprezentuje Test.txt plik. Nowa właściwość jest aliasem właściwości Length .

Pierwsze polecenie używa Get-ChildItem polecenia cmdlet do pobrania Test.txt obiektu 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 właściwość StringUse note jest dodana do ciągu. Ponieważ Add-Member nie można dodać typów do obiektów wejściowych Ciąg , 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 note, 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 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 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. W przykładzie jest zapisywany obiekt PSObject w zmiennej $Asset .

Drugie polecenie używa akceleratora [ordered] typów do utworzenia uporządkowanego słownika nazw i wartości. Polecenie zapisuje wynik w zmiennej $D .

Trzecie polecenie używa parametru Add-MemberNotePropertyMembers polecenia cmdlet, aby dodać słownik w zmiennej $D do obiektu PSObject. Właściwość TypeName przypisuje nową nazwę Asset do obiektu PSObject.

Ostatnie polecenie powoduje potoki nowego obiektu elementu zawartości do Get-Member polecenia cmdlet . Dane wyjściowe pokazują, że obiekt ma nazwę typu Element zawartości i właściwości notatki zdefiniowane w uporządkowanym słowniku.

$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

TypeName: Asset

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
Name        NoteProperty System.String Name=Server30
PSVersion   NoteProperty System.String PSVersion=4.0
System      NoteProperty System.String System=Server Core

Parametry

-Force

Wskazuje, że to polecenie cmdlet dodaje nowy element członkowski, nawet obiekt ma niestandardowy element członkowski o tej samej nazwie. Nie można użyć parametru Force , aby zastąpić standardowy element członkowski typu.

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

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

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

Informacje o tych wartościach można znaleźć w temacie PSMemberTypes Enumeration in the PowerShell SDK (Wyliczenie PSMemberTypes w zestawie SDK programu PowerShell).

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, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:0
Default value:None
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
Accept pipeline input:False
Accept wildcard characters:False
-NotePropertyMembers

Określa tabelę skrótów lub uporządkowany słownik nazw i wartości właściwości notatek. Wpisz tabelę skrótu lub słownik, w którym klucze są zanotowane nazwy właściwości, a wartości są wartościami właściwoś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 Windows PowerShell 3.0.

Type:IDictionary
Position:0
Default value:None
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 Windows PowerShell 3.0.

Type:String
Position:0
Default value:None
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 Windows PowerShell 3.0.

Type:Object
Position:1
Default value:None
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 żadnego wyniku.

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

W Windows PowerShell 2.0 Add-Member dodano elementy członkowskie tylko do otoki OBIEKTÓW 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
Accept pipeline input:False
Accept wildcard characters:False
-SecondValue

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

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 SecondValueelementu System.Int32 , aby wskazać, że wartość tej właściwości ciągu powinna zostać przekonwertowana na liczbę całkowitą po korzystaniu z odpowiedniego aliasuProperty.

Możesz użyć parametru SecondValue , aby określić dodatkowy element ScriptBlock podczas dodawania elementu członkowskiego ScriptProperty . Pierwszy element ScriptBlock określony w parametrze Value służy do pobierania wartości zmiennej. Drugi scriptBlock określony w parametrze SecondValue służy do ustawiania wartości zmiennej.

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

Określa nazwę typu.

Jeśli typ jest klasą w przestrzeni nazw systemowej 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 Windows PowerShell 3.0.

Type:String
Position:Named
Default value:None
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, ScriptProperty lub CodeMethod, możesz podać opcjonalne dodatkowe informacje przy użyciu parametru SecondValue.

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

Dane wejściowe

PSObject

Do tego polecenia cmdlet można przekazać potok dowolnego typu obiektu.

Dane wyjściowe

None or System.Object

Jeśli używasz parametru PassThru , to polecenie cmdlet zwraca nowo rozszerzony obiekt. W przeciwnym razie to polecenie cmdlet nie generuje żadnych danych wyjściowych.

Uwagi

Elementy członkowskie można dodawać tylko do obiektów 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].

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 skryptów, 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.