Partilhar via

Add-Member

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Adiciona propriedades e métodos personalizados a uma instância de um objeto do PowerShell.

Sintaxe

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

Description

O cmdlet Add-Member permite adicionar membros (propriedades e métodos) a uma instância de um objeto do PowerShell. Por exemplo, você pode adicionar um membro NoteProperty que contém uma descrição do objeto ou um ScriptMethod membro que executa um script para alterar o objeto.

Para usar Add-Member, canalize o objeto para Add-Memberou use o parâmetro InputObject para especificar o objeto.

O parâmetro MemberType indica o tipo de membro que você deseja adicionar. O parâmetro Name atribui um nome ao novo membro e o parâmetro Value define o valor do membro.

As propriedades e métodos que você adiciona são adicionados somente à instância específica do objeto que você especificar. Add-Member não altera o tipo de objeto. Para criar um novo tipo de objeto, use o cmdlet Add-Type.

Você também pode usar o cmdlet Export-Clixml para salvar a instância do objeto, incluindo os membros adicionais, em um arquivo. Em seguida, você pode usar o cmdlet Import-Clixml para recriar a instância do objeto a partir das informações armazenadas no arquivo exportado.

A partir do Windows PowerShell 3.0, Add-Member tem novos recursos que facilitam a adição de propriedades de anotação a objetos. Você pode usar o NotePropertyName e parâmetros NotePropertyValue para definir uma propriedade note ou usar o parâmetro NotePropertyMembers, que usa uma tabela de hash de nomes e valores de propriedade de nota.

Além disso, a partir do Windows PowerShell 3.0, o parâmetro PassThru, que gera um objeto de saída, é necessário com menos frequência. Add-Member agora adiciona os novos membros diretamente ao objeto de entrada de mais tipos. Para obter mais informações, consulte a PassThru descrição do parâmetro.

Exemplos

Exemplo 1: Adicionar uma propriedade note a um PSObject

O exemplo a seguir adiciona uma propriedade de Status note com um valor de "Done" ao objeto FileInfo que representa o arquivo Test.txt.

O primeiro comando usa o cmdlet Get-ChildItem para obter um objeto FileInfo que representa o arquivo Test.txt. Salva-o na variável $a.

O segundo comando adiciona a propriedade note ao objeto em $a.

O terceiro comando usa notação de ponto para obter o valor da propriedade Status do objeto em $a. Como mostra a saída, o valor é Done.

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

Done

Exemplo 2: Adicionar uma propriedade alias a um PSObject

O exemplo a seguir adiciona uma propriedade Size alias ao objeto que representa o arquivo Test.txt. A nova propriedade é um alias para a propriedade Length.

O primeiro comando usa o cmdlet Get-ChildItem para obter o Test.txtFileInfo objeto.

O segundo comando adiciona a propriedade Tamanho alias. O terceiro comando usa notação de ponto para obter o valor da nova propriedade Size.

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

2394

Exemplo 3: Adicionar uma propriedade de nota StringUse a uma cadeia de caracteres

Este exemplo adiciona a propriedade StringUse note a uma cadeia de caracteres. Como Add-Member não pode adicionar tipos a String objetos de entrada, você pode especificar o parâmetro PassThru para gerar um objeto de saída. O último comando no exemplo exibe a nova propriedade.

Este exemplo usa o parâmetro NotePropertyMembers. O valor do parâmetro NotePropertyMembers é uma tabela de hash. A chave é o nome da propriedade note, StringUse, e o valor é o valor da propriedade note, Display.

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

Display

Exemplo 4: Adicionar um método de script a um objeto FileInfo

Este exemplo adiciona o método de script SizeInMB a um objeto FileInfo que calcula o tamanho do arquivo para o MegaByte mais próximo. O segundo comando cria um ScriptBlock que usa o método estático Round do tipo [math] para arredondar o tamanho do arquivo para a segunda casa decimal.

O parâmetro Value também usa a variável automática $This, que representa o objeto atual. A variável $This é válida apenas em blocos de script que definem novas propriedades e métodos.

O último comando usa notação de ponto para chamar o novo SizeInMB método de script no objeto na variável $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

Exemplo 5: Criar um objeto personalizado

Este exemplo cria um Asset objeto personalizado.

O cmdlet New-Object cria um PSObject que é salvo na variável $Asset. O acelerador de tipo [ordered] cria um dicionário ordenado que é armazenado na variável $d. O $Asset de tubulação para Add-Member adiciona os pares chave-valor no dicionário ao objeto como membros do NoteProperty. parâmetro TypeName atribui o Asset de tipo ao PSObject . O cmdlet Get-Member mostra o tipo e as propriedades do objeto. No entanto, as propriedades são listadas em ordem alfabética, não na ordem em que foram adicionadas.

$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

Inspecionar a lista bruta de propriedades mostra as propriedades na ordem em que foram adicionadas ao objeto. Format-Table é usado neste exemplo para criar uma saída semelhante a Get-Member.

Exemplo 6: Adicionar um AliasProperty a um objeto

Neste exemplo, criamos um objeto personalizado que contém dois membros NoteProperty. O tipo para um NoteProperty reflete o tipo do valor armazenado na propriedade. Nesse caso, a propriedade Age é uma cadeia de caracteres.

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

A propriedade intAge é um AliasProperty para a propriedade Age, mas o tipo é garantido para ser uint32.

Exemplo 7: Adicionar métodos get e set a um objeto personalizado

Este exemplo mostra como definir métodos Get e set que acessam uma propriedade profundamente aninhada.

$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

Observe que a propriedade Title é um ScriptProperty que tem um método Get e set. Quando atribuímos um novo valor à propriedade Title, o método set é chamado e altera o valor da propriedade Role na propriedade Position.

Parâmetros

-Force

Por padrão, Add-Member não pode adicionar um novo membro se o objeto já tiver um membro com o mesmo. Quando você usa o parâmetro Force, Add-Member substitui o membro existente pelo novo membro. Não é possível usar o parâmetro Force para substituir um membro padrão de um tipo.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-InputObject

Especifica o objeto ao qual o novo membro é adicionado. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtenha os objetos.

Tipo:PSObject
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-MemberType

Especifica o tipo de membro a ser adicionado. Este parâmetro é obrigatório. Os valores aceitáveis para este parâmetro são:

  • AliasProperty
  • CodeMethod
  • CodeProperty
  • ObservaçãoPropriedade
  • ScriptMethod
  • ScriptProperty

Para obter informações sobre esses valores, consulte de enumeração PSMemberTypes no SDK do PowerShell.

Nem todos os objetos têm todos os tipos de membros. Se você especificar um tipo de membro que o objeto não tem, o PowerShell retornará um erro.

Tipo:PSMemberTypes
Aliases:Type
Valores aceites:AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Name

Especifica o nome do membro que este cmdlet adiciona.

Tipo:String
Position:1
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-NotePropertyMembers

Especifica uma hashtable ou dicionário ordenado que contém o par chave-valor que representa nomes NoteProperty e seus valores. Para obter mais informações sobre tabelas de hash e dicionários ordenados no PowerShell, consulte about_Hash_Tables.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:IDictionary
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-NotePropertyName

Especifica o nome da propriedade note.

Use esse parâmetro com o parâmetro NotePropertyValue. Este parâmetro é opcional.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-NotePropertyValue

Especifica o valor da propriedade note.

Use esse parâmetro com o parâmetro NotePropertyName. Este parâmetro é opcional.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Object
Position:1
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-PassThru

Retorna um objeto que representa o item com o qual você está trabalhando. Por padrão, esse cmdlet não gera nenhuma saída.

Para a maioria dos objetos, Add-Member adiciona os novos membros ao objeto de entrada. No entanto, quando o objeto de entrada é uma cadeia de caracteres, Add-Member não pode adicionar o membro ao objeto de entrada. Para esses objetos, use o parâmetro PassThru para criar um objeto de saída.

No Windows PowerShell 2.0, Add-Member adicionado membros somente ao PSObject wrapper de objetos, não ao objeto. Use o parâmetro PassThru para criar um objeto de saída para qualquer objeto que tenha um wrapper de PSObject.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-SecondValue

Especifica informações adicionais opcionais sobre AliasProperty , ScriptPropertyou CodeProperty membros.

Se usado ao adicionar um AliasProperty, esse parâmetro deve ser um tipo de dados. Uma conversão para o tipo de dados especificado é adicionada ao valor do AliasProperty. Por exemplo, se você adicionar um AliasProperty que forneça um nome alternativo para uma propriedade string, você também pode especificar um SecondValue parâmetro de System.Int32 para indicar que o valor dessa propriedade string deve ser convertido em um inteiro quando acessado usando o AliasPropertycorrespondente.

Para um CodeProperty, o valor deve ser uma referência a um método que implementa um set acessador. Use o método GetMethod() de uma referência de tipo para obter uma referência a um método. O método deve ter um único parâmetro que é um PSObject. O acessador Get é atribuído usando o parâmetro Value.

Para um ScriptProperty, o valor deve ser um bloco de script que implementa um set acessador. O acessador Get é atribuído usando o parâmetro Value.

Tipo:Object
Position:3
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-TypeName

Especifica um nome para o tipo.

Quando o tipo é uma classe no namespace System ou um tipo que tem um acelerador de tipo, você pode inserir o nome abreviado do tipo. Caso contrário, o nome completo do tipo é necessário. Esse parâmetro é efetivo somente quando o InputObject é um PSObject.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Value

Especifica o valor inicial do membro adicionado. Se você adicionar um AliasProperty, CodePropertyou membro do ScriptProperty, poderá fornecer informações adicionais usando o parâmetro SecondValue.

  • Para um AliasProperty, o valor deve ser o nome da propriedade que está sendo aliased.
  • Para um CodeMethod, o valor deve ser uma referência a um método. Use o método GetMethod() de uma referência de tipo para obter uma referência a um método.
  • Para um CodeProperty, o valor deve ser uma referência a um método que implementa um acessador Get. Use o método GetMethod() de uma referência de tipo para obter uma referência a um método. referência. O método deve ter um único parâmetro que é um PSObject. O set acessador é atribuído usando o parâmetro SecondValue.
  • Para um ScriptMethod, o valor deve ser um bloco de script.
  • Para um ScriptProperty, o valor deve ser um bloco de script que implementa um acessador Get. O set acessador é atribuído usando o parâmetro SecondValue.
Tipo:Object
Position:2
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

PSObject

Você pode canalizar qualquer objeto para este cmdlet.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

Object

Quando você usa o parâmetro PassThru, esse cmdlet retorna o objeto recém-estendido.

Notas

Você pode adicionar membros somente a objetos de tipo de PSObject. Para determinar se um objeto é um objeto PSObject, use o operador -is. Por exemplo, para testar um objeto armazenado na variável $obj, digite $obj -is [psobject].

objetos de tipo PSObject mantêm sua lista de membros na ordem em que os membros foram adicionados ao objeto.

Os nomes dos parâmetros MemberType, Name, Valuee SecondValue são opcionais. Se você omitir os nomes dos parâmetros, os valores de parâmetros sem nome deverão aparecer nesta ordem: MemberType, Name, Valuee SecondValue.

Se você incluir os nomes dos parâmetros, os parâmetros poderão aparecer em qualquer ordem.

Você pode usar a variável automática $this em blocos de script que definem os valores de novas propriedades e métodos. A variável $this refere-se à instância do objeto ao qual as propriedades e métodos estão sendo adicionados. Para obter mais informações sobre a variável $this, consulte about_Automatic_Variables.