Add-Member

Módulo:

Microsoft.PowerShell.Utility Module

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

Sintaxe

TypeNameSet (Predefinição)

Add-Member
    -InputObject <PSObject>
    -TypeName <String>
    [-PassThru]
    [<CommonParameters>]

NotePropertyMultiMemberSet

Add-Member
    [-NotePropertyMembers] <IDictionary>
    -InputObject <PSObject>
    [-TypeName <String>]
    [-Force]
    [-PassThru]
    [<CommonParameters>]

NotePropertySingleMemberSet

Add-Member
    [-NotePropertyName] <String>
    [-NotePropertyValue] <Object>
    -InputObject <PSObject>
    [-TypeName <String>]
    [-Force]
    [-PassThru]
    [<CommonParameters>]

MemberSet

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 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 . Como mostra a saída, 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 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: Copiar todas as propriedades de um objeto para outro

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

O loop de 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 Asset objeto personalizado.

O cmdlet New-Object cria um PSObject. O exemplo salva o PSObject na variável $Asset.

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 na 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 nota 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, mesmo que o objeto tenha um membro personalizado com o mesmo nome. Não é possível usar o parâmetro Force para substituir um membro padrão de um tipo.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

NotePropertyMultiMemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

NotePropertySingleMemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

MemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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.

Propriedades dos parâmetros

Tipo:	PSObject
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	True
Valor do pipeline:	True
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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:

• ObservaçãoPropriedade
• 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 membros. Se você especificar um tipo de membro que o objeto não tem, o PowerShell retornará um erro.

Propriedades dos parâmetros

Tipo:	PSMemberTypes
Default value:	None
Valores aceites:	AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Tipo

Conjuntos de parâmetros

MemberSet

Position:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Name

Especifica o nome do membro que este cmdlet adiciona.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

MemberSet

Position:	1
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-NotePropertyMembers

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

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.

Propriedades dos parâmetros

Tipo:	IDictionary
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

NotePropertyMultiMemberSet

Position:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

NotePropertySingleMemberSet

Position:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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.

Propriedades dos parâmetros

Tipo:	Object
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

NotePropertySingleMemberSet

Position:	1
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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 .

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-SecondValue

Especifica informações adicionais opcionais sobre AliasProperty, ScriptProperty, CodePropertyou CodeMethod 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 fornece 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 correspondente AliasProperty.

Você pode usar o parâmetro SecondValue para especificar um adicional ScriptBlock ao adicionar um membro ScriptProperty . O primeiro ScriptBlock , especificado no parâmetro Value, é 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.

Propriedades dos parâmetros

Tipo:	Object
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

MemberSet

Position:	3
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	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.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

TypeNameSet

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

NotePropertyMultiMemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

NotePropertySingleMemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

MemberSet

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Value

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

Propriedades dos parâmetros

Tipo:	Object
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

MemberSet

Position:	2
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

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.

Notas

Você pode adicionar membros somente a objetos PSObject. Para determinar se um objeto é um objeto PSObject , use o operador .

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

Ligações Relacionadas

• Export-Clixml
• Get-Member
• Import-Clixml
• Novo-Objeto
• Sobre as Variáveis Automáticas