Add-Member

Командлет Add-Member позволяет добавлять элементы (свойства и методы) в экземпляр объекта PowerShell. Например, можно добавить элемент NoteProperty, содержащий описание объекта или члена ScriptMethod, который запускает скрипт для изменения объекта.

Чтобы использовать Add-Member, передайте объект в Add-Memberили используйте параметр inputObject InputObject, чтобы указать объект.

Параметр MemberType указывает тип элемента, который требуется добавить. Параметр Name назначает имя новому элементу, а параметр Value задает значение элемента.

Добавляемые свойства и методы добавляются только к конкретному экземпляру указанного объекта. Add-Member не изменяет тип объекта. Чтобы создать новый тип объекта, используйте командлет Add-Type.

Можно также использовать командлет Export-Clixml для сохранения экземпляра объекта, включая дополнительные члены в файле. Затем можно использовать командлет Import-Clixml для повторного создания экземпляра объекта из сведений, хранящихся в экспортируемом файле.

Начиная с Windows PowerShell 3.0, Add-Member имеет новые функции, которые упрощают добавление свойств заметок в объекты. Можно использовать параметры NotePropertyName и NotePropertyValue для определения свойства заметки или использования параметра NotePropertyMembers, которая принимает хэш-таблицу имен свойств и значений.

Кроме того, начиная с Windows PowerShell 3.0, параметр PassThru, который создает выходной объект, требуется реже. Add-Member теперь добавляет новые члены непосредственно в входной объект большего количества типов. Дополнительные сведения см. в описании параметра PassThru.

В следующем примере добавляется свойство заметки состояния со значением "Готово" в объект FileInfo, представляющий файл Test.txt.

Первая команда использует командлет Get-ChildItem для получения объекта FileInfo, представляющего файл Test.txt. Он сохраняет его в переменной $a.

Вторая команда добавляет свойство note в объект в $a.

Третья команда использует нотацию точек для получения значения свойства Status объекта в $a. Как показано в выходных данных, значение равно Done.

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

Done

В следующем примере добавляется свойство псевдонима размера в объект, представляющий файл Test.txt. Новое свойство является псевдонимом свойства Length.

Первая команда использует командлет Get-ChildItem для получения объекта Test.txtFileInfo.

Вторая команда добавляет свойство псевдонима Size. Третья команда использует нотацию точек для получения значения нового свойства Size.

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

2394

В этом примере StringUse свойство заметки добавляется в строку. Так как Add-Member не удается добавить типы в объекты ввода String, можно указать параметр PassThru для создания выходного объекта. Последняя команда в примере отображает новое свойство.

В этом примере используется параметр NotePropertyMembers. Значение параметра NotePropertyMembers является хэш-таблицей. Ключом является имя свойства заметки, StringUse, а значением является значение свойства заметки, Display.

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

Display

В этом примере метод скрипта SizeInMB добавляется в объект FileInfo, который вычисляет размер файла в ближайший Мегабайт. Вторая команда создает ScriptBlock, которая использует статический метод раунда из типа [Math] для округления размера файла до второго десятичного разряда.

Параметр Value также использует автоматическую переменную $this, представляющую текущий объект. Переменная $this действительна только в блоках скриптов, определяющих новые свойства и методы.

Последняя команда использует нотацию точек для вызова нового метода скрипта sizeIn MB SizeInMB в объекте в переменной $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

В этом примере создается пользовательский объект актива.

Командлет New-Object создает PSObject, сохраненный в переменной $Asset. Ускоритель типов [ordered] создает упорядоченный словарь, хранящийся в переменной $d. Пипсинг $Asset для Add-Member добавляет пары "ключ-значение" в словарь к объекту в виде элементов NoteProperty. параметр TypeName назначает тип AssetPSObject. Командлет 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.

В этом примере мы создадим пользовательский объект, содержащий два элемента NoteProperty. Тип NoteProperty отражает тип значения, хранящегося в свойстве. В этом случае свойство age является строкой.

$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

Свойство IntAge является псевдонимом AliasProperty для свойства Age, но тип гарантированно будет uint32.

В этом примере показано, как определить 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 является ScriptProperty с Методом Get и Set. При назначении нового значения свойству title вызывается метод set и изменяет значение свойства role в свойстве Position.

PSObject

Вы можете передать любой объект в этот командлет.

None

По умолчанию этот командлет не возвращает выходные данные.

Object

При использовании параметра PassThru этот командлет возвращает новый расширенный объект.

Элементы можно добавлять только в объекты типа PSObject PSObject. Чтобы определить, является ли объект объектом PSObject, используйте оператор -is. Например, чтобы проверить объект, хранящийся в переменной $obj, введите $obj -is [psobject].

объекты типа PSObject поддерживают их список элементов в том порядке, в который были добавлены члены.

Имена MemberType, Name, Valueи SecondValue являются необязательными. Если имена параметров опущены, значения неименованных параметров должны отображаться в этом порядке: MemberType, Name, Valueи SecondValue.

Если вы включаете имена параметров, параметры могут отображаться в любом порядке.

Вы можете использовать $this автоматическую переменную в блоках скриптов, определяющих значения новых свойств и методов. Переменная $this ссылается на экземпляр объекта, к которому добавляются свойства и методы. Дополнительные сведения об переменной $this см. в about_Automatic_Variables.