Add-Member

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

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.

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

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

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

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

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

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

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.

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

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.

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.