Compartilhar 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
   [-NotePropertyMembers] <IDictionary>
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]
Add-Member
   [-NotePropertyName] <String>
   [-NotePropertyValue] <Object>
   -InputObject <PSObject>
   [-TypeName <String>]
   [-Force]
   [-PassThru]
   [<CommonParameters>]
Add-Member
   [-MemberType] <PSMemberTypes>
   [-Name] <String>
   [[-Value] <Object>]
   [[-SecondValue] <Object>]
   -InputObject <PSObject>
   [-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 membro ScriptMethod que executa um script para alterar o objeto.

Para usar Add-Member, redirecione 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 os 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 aos objetos. Você pode usar os parâmetros NotePropertyName e NotePropertyValue para definir uma propriedade de anotação ou usar o parâmetro NotePropertyMembers, que usa uma tabela de hash de nomes e valores de propriedade de anotação.

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 descrição do parâmetro PassThru.

Exemplos

Exemplo 1: adicionar uma propriedade de anotação a um PSObject

O exemplo a seguir adiciona uma propriedade de nota Status com um valor "Concluído" ao objeto FileInfo que representa o arquivo .

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

O segundo comando adiciona a propriedade de anotação ao objeto em $a.

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

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

Done

Exemplo 2: Adicionar uma propriedade de 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 para obter o objeto FileInfo.

O segundo comando adiciona a propriedade Size 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 anotação StringUse a uma cadeia de caracteres

Este exemplo adiciona a propriedade de nota StringUse a uma cadeia de caracteres. Como Add-Member não pode adicionar tipos a objetos de entrada String, 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 de anotação, StringUsee o valor é o valor da propriedade de anotação, 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 para arredondar o tamanho do arquivo para o segundo local 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 somente em blocos de script que definem novas propriedades e métodos.

O último comando usa a notação de ponto para chamar o novo método de script SizeInMB no objeto na variável .

$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: Copiar todas as propriedades de um objeto para outro

Essa função copia todas as propriedades de um objeto para outro objeto.

O loop foreach usa o cmdlet Get-Member para obter cada uma das propriedades do objeto From. Os comandos dentro do loop foreach são executados em série em cada uma das propriedades.

O comando Add-Member adiciona a propriedade do objeto From ao objeto To como um NoteProperty. O valor é copiado usando o parâmetro Value. Ele usa o parâmetro Force para adicionar membros com o mesmo nome de membro.

function Copy-Property ($From, $To)
{
    $properties = Get-Member -InputObject $From -MemberType Property
    foreach ($p in $properties)
    {
        $To | Add-Member -MemberType NoteProperty -Name $p.Name -Value $From.$($p.Name) -Force
    }
}

Exemplo 6: Criar um objeto personalizado

Este exemplo cria um objeto personalizado Asset.

O cmdlet cria umPSObject . O exemplo salva a PSObject na variável .

O segundo comando usa o acelerador de tipo [ordered] para criar um dicionário ordenado de nomes e valores. O comando salva o resultado na variável $D.

O terceiro comando usa o parâmetro NotePropertyMembers do cmdlet para adicionar o dicionário à variável aoPSObject . A propriedade TypeName atribui um novo nome, Asset, ao PSObject.

O último comando canaliza o novo objeto Asset para o cmdlet Get-Member. A saída mostra que o objeto tem um nome de tipo de Asset e as propriedades de anotação que definimos no dicionário ordenado.

$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

Parâmetros

-Force

Indica que esse cmdlet adiciona um novo membro até mesmo que o objeto tenha um membro personalizado com o mesmo nome. Você não pode usar o parâmetro Force para substituir um membro padrão de um tipo.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 obtém os objetos.

Tipo:PSObject
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-MemberType

Especifica o tipo do membro a ser adicionado. Esse parâmetro é necessário. Os valores aceitáveis para este parâmetro são:

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

Para obter informações sobre esses valores, consulte de Enumeração PSMemberTypes na biblioteca MSDN.

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

Tipo:PSMemberTypes
Aliases:Type
Valores aceitos:AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Name

Especifica o nome do membro que este cmdlet adiciona.

Tipo:String
Cargo:1
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-NotePropertyMembers

Especifica uma tabela de hash ou um dicionário ordenado de valores e nomes de propriedade de anotação. Digite uma tabela ou dicionário de hash no qual as chaves são nomes de propriedade de anotação e os valores são valores de propriedade de anotação.

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
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-NotePropertyName

Especifica o nome da propriedade de anotação.

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

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-NotePropertyValue

Especifica o valor da propriedade de anotação.

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

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Object
Cargo:1
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 membros adicionados somente ao wrapper de objetos do PSObject, não ao objeto. Use o parâmetro PassThru para criar um objeto de saída para qualquer objeto que tenha um wrapper PSObject.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SecondValue

Especifica informações adicionais opcionais sobre membrosAliasProperty, ScriptProperty, CodePropertyou CodeMethod.

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 doAliasProperty .

Por exemplo, se você adicionar um AliasProperty que fornece um nome alternativo para uma propriedade de cadeia de caracteres, você também poderá especificar um parâmetro SecondValue de System.Int32 para indicar que o valor dessa propriedade de cadeia de caracteres deve ser convertido em um inteiro quando acessado usando o correspondenteAliasProperty .

Você pode usar o parâmetro SecondValue para especificar um ScriptBlock adicional ao adicionar um membro ScriptProperty . O primeiro scriptBlock, especificado no parâmetro de valor , é usado para obter o valor de uma variável. O segundo ScriptBlock, especificado no parâmetro SecondValue, é usado para definir o valor de uma variável.

Tipo:Object
Cargo:3
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 curto do tipo. Caso contrário, o nome de tipo completo será necessário. Esse parâmetro só é eficaz quando o InputObject é umPSObject .

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Value

Especifica o valor inicial do membro adicionado. Se você adicionar umAliasProperty, CodeProperty, ScriptProperty ou membro CodeMethod, você poderá fornecer informações adicionais opcionais usando o parâmetro SecondValue.

Tipo:Object
Cargo:2
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

PSObject

Você pode canalizar qualquer tipo de objeto para este cmdlet.

Saídas

None or System.Object

Quando você usa o parâmetro PassThru, esse cmdlet retorna o objeto recém-estendido. Caso contrário, esse cmdlet não gerará nenhuma saída.

Observações

Você pode adicionar membros apenas a objetos 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].

Os nomes dos parâmetros MemberType, Name, Valuee SecondValue são opcionais. Se você omitir os nomes de parâmetro, os valores de parâmetro 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 $this automática em blocos de script que definem os valores de novas propriedades e métodos. A variável $this refere-se à instância do objeto à qual as propriedades e os métodos estão sendo adicionados. Para obter mais informações sobre a variável $this, consulte about_Automatic_Variables.