Add-Member (Microsoft.PowerShell.Utility)

Add-Member

Модуль:

Microsoft.PowerShell.Utility

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

Синтаксис

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

Описание

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

Чтобы использовать Add-Member, передайте объект в Add-Member или используйте параметр 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.

Примеры

Пример 1. Добавление свойства примечания к PSObject

В следующем примере добавляется свойство примечания Status со значением «Done» к объекту 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

Пример 2. Добавление свойства псевдонима в PSObject

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

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

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

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

2394

Пример 3. Добавление свойства примечания StringUse в строку

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

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

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

Display

Пример 4. Добавление метода сценария к объекту FileInfo.

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

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

Последняя команда использует запись через точку для вызова нового метода сценария 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

Пример 5. Создание пользовательского объекта

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

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

Пример 6. Добавление AliasProperty к объекту

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

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

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

Пример 7. Добавление методов get и set в пользовательский объект

В этом примере показано, как определить методы 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 в . Позиционируйте свойство.

Параметры

-Force

По умолчанию Add-Member не может добавить новый элемент, если у объекта уже есть такой же элемент. При использовании параметра Force Add-Member заменяет существующий элемент новым. Параметр Force нельзя использовать для замены стандартного члена типа.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-InputObject

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

Тип :

PSОбъект

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

True

Принимайте подстановочные знаки:

False

-MemberType

Указывает тип добавляемого элемента. Этот параметр является обязательным. Допустимые значения этого параметра:

• AliasProperty
• CodeMethod
• CodeProperty
• NoteProperty
• ScriptMethod
• ScriptProperty

Сведения об этих значениях см. в разделе Перечисление PSMemberTypes в PowerShell SDK.

Не все объекты имеют все типы членов. Если вы укажете тип члена, которого нет у объекта, PowerShell вернет ошибку.

Тип :

PSMemberTypes

Псевдонимы:

Type

Принятые значения:

AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Name

Указывает имя члена, добавляемого этим командлетом.

Тип :

String

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-NotePropertyMembers

Указывает хеш-таблицу или упорядоченный словарь, содержащий пару ключ-значение, представляющую имена NoteProperty и их значения. Дополнительные сведения о хэш-таблицах и упорядоченных словарях в PowerShell см. в разделе about_Hash_Tables.

Этот параметр был введен в Windows PowerShell 3.0.

Тип :

IСловарь

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-NotePropertyName

Указывает имя свойства заметки.

Используйте этот параметр с параметром NotePropertyValue. Этот параметр является необязательным.

Этот параметр был введен в Windows PowerShell 3.0.

Тип :

String

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-NotePropertyValue

Указывает значение свойства примечания.

Используйте этот параметр с параметром NotePropertyName. Этот параметр является необязательным.

Этот параметр был введен в Windows PowerShell 3.0.

Тип :

Объект

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-PassThru

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

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

В Windows PowerShell 2.0 Add-Member добавлял элементы только в оболочку PSObject объектов, а не в сам объект. Используйте параметр PassThru, чтобы создать выходной объект для любого объекта, имеющего оболочку PSObject.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-SecondValue

Указывает необязательную дополнительную информацию об элементах AliasProperty, ScriptProperty или CodeProperty.

Если этот параметр используется при добавлении AliasProperty, он должен иметь тип данных. Преобразование в указанный тип данных добавляется к значению AliasProperty. Например, если вы добавите AliasProperty, предоставляющий альтернативное имя для строкового свойства, вы также можете указать параметр SecondValue для System.Int32. чтобы указать, что значение этого строкового свойства должно быть преобразовано в целое число при доступе с использованием соответствующего AliasProperty.

Для CodeProperty значение должно быть ссылкой на метод, реализующий метод доступа Set. Используйте метод GetMethod() ссылки на тип, чтобы получить ссылку на метод. Метод должен принимать один параметр — PSObject. Аксессор Get назначается с помощью параметра Value.

Для ScriptProperty значением должен быть блок сценария, реализующий метод доступа Set. Аксессор Get назначается с помощью параметра Value.

Тип :

Объект

Позиция:

3

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-TypeName

Указывает имя типа.

Если тип является классом в пространстве имен System или типом, имеющим ускоритель типов, вы можете ввести короткое имя типа. В противном случае требуется полное имя типа. Этот параметр действует только в том случае, если InputObject является PSObject.

Этот параметр был введен в Windows PowerShell 3.0.

Тип :

String

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Value

Указывает начальное значение добавленного члена. Если вы добавите элемент AliasProperty, CodeProperty или ScriptProperty, вы можете предоставить дополнительную информацию с помощью параметра SecondValue.

• Для AliasProperty значение должно быть именем свойства, для которого создается псевдоним.
• Для CodeMethod значение должно быть ссылкой на метод. Используйте метод GetMethod() ссылки на тип, чтобы получить ссылку на метод.
• Для CodeProperty значение должно быть ссылкой на метод, реализующий метод доступа Get. Используйте метод GetMethod() ссылки на тип, чтобы получить ссылку на метод. ссылка. Метод должен принимать один параметр — PSObject. Аксессор Set назначается с помощью параметра SecondValue.
• Для ScriptMethod значение должно быть блоком сценария.
• Для ScriptProperty значение должно быть блоком сценария, реализующим метод доступа Get. Аксессор Set назначается с помощью параметра SecondValue.

Тип :

Объект

Позиция:

2

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

PSObject

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

Выходы

Нет

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

Объект

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

Примечания

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

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

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

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

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