Add-Member
Adiciona propriedades e métodos personalizados a uma instância de um objeto do PowerShell.
Syntax
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 Add-Member
cmdlet 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
, direcione o objeto para Add-Member
ou 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 acrescentados apenas à instância específica do objeto especificado por você. Add-Member
não altera o tipo de objeto. Para criar um novo tipo de objeto, use o Add-Type
cmdlet .
Você também pode usar o Export-Clixml
cmdlet para salvar a instância do objeto, incluindo os membros adicionais, em um arquivo. Em seguida, você pode usar o Import-Clixml
cmdlet 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 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 valores e nomes de propriedades 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 anotação status com um valor de "Done" ao objeto FileInfo que representa o Test.txt
arquivo.
O primeiro comando usa o Get-ChildItem
cmdlet para obter um objeto FileInfo que representa o Test.txt
arquivo. Ele o salva na $a
variável .
O segundo comando adiciona a propriedade note ao objeto em $a
.
O terceiro comando usa a 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 de alias Size ao objeto que representa o Test.txt
arquivo. A nova propriedade é um alias para a propriedade Length .
O primeiro comando usa o Get-ChildItem
cmdlet para obter o Test.txt
objeto FileInfo.
O segundo comando adiciona a propriedade de alias Size . 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 anotação StringUse a uma cadeia de caracteres.
Como Add-Member
não é possível adicionar tipos aos 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, 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 [math]
tipo para arredondar o tamanho do arquivo para o segundo local decimal.
O parâmetro Value também usa a $This
variável automática, que representa o objeto atual. A $This
variável é válida somente em blocos de script que definem novas propriedades e métodos.
O último comando usa notação de ponto para chamar o novo método de script SizeInMB no objeto na $A
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
Esta função copia todas as propriedades de um objeto em outro objeto.
O foreach
loop usa o Get-Member
cmdlet para obter cada uma das propriedades do objeto From . Os comandos dentro do foreach
loop são executados em série em cada uma das propriedades.
O Add-Member
comando 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: Create um objeto personalizado
Este exemplo cria um objeto personalizado Asset .
O New-Object
cmdlet cria um PSObject. O exemplo salva o PSObject na $Asset
variável .
O segundo comando usa o [ordered]
acelerador de tipo para criar um dicionário ordenado de nomes e valores. O comando salva o resultado na $D
variável.
O terceiro comando usa o parâmetro NotePropertyMembers do Add-Member
cmdlet para adicionar o dicionário na $D
variável ao PSObject.
A propriedade TypeName atribui um novo nome, Asset, ao PSObject.
O último comando redireciona o novo objeto Asset para o Get-Member
cmdlet . 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, 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.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InputObject
Especifica o objeto ao qual o novo membro é adicionado. Insira uma variável que contém os objetos ou digite um comando ou uma expressão que obtém os objetos.
Type: | PSObject |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-MemberType
Especifica o tipo do membro a ser adicionado. Este parâmetro é necessário. Os valores aceitáveis para esse parâmetro são:
- Noteproperty
- Aliasproperty
- ScriptProperty
- Codeproperty
- Scriptmethod
- CodeMethod
Para obter informações sobre esses valores, consulte 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.
Type: | PSMemberTypes |
Aliases: | Type |
Accepted values: | AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
Especifica o nome do membro que este cmdlet adiciona.
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NotePropertyMembers
Especifica uma tabela de hash ou dicionário ordenado de valores e nomes de propriedade de observação. Digite uma tabela de hash ou dicionário no qual as chaves são os nomes de propriedade de observação e os valores são valores de propriedade de observação.
Para obter mais informações sobre tabelas de hash e dicionários ordenados no PowerShell, consulte about_Hash_Tables.
Este parâmetro foi introduzido no Windows PowerShell 3.0.
Type: | IDictionary |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NotePropertyName
Especifica o nome da propriedade note.
Use este parâmetro com o parâmetro NotePropertyValue. Esse parâmetro é opcional.
Este parâmetro foi introduzido no Windows PowerShell 3.0.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NotePropertyValue
Especifica o valor da propriedade note.
Use esse parâmetro com o parâmetro NotePropertyName . Esse parâmetro é opcional.
Este parâmetro foi introduzido no Windows PowerShell 3.0.
Type: | Object |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Retorna um objeto que representa o item com que você está trabalhando. Por padrão, este cmdlet não gera 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 é possível adicionar o membro ao objeto de entrada.
Para estes 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 PSObject 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 PSObject .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SecondValue
Especifica informações opcionais adicionais sobre membros AliasProperty, ScriptProperty, CodeProperty ou CodeMethod.
Se usado ao adicionar um AliasProperty, esse parâmetro deverá ser um tipo de dados. Uma conversão para o tipo de dados especificado é adicionada ao valor de AliasProperty.
Por exemplo, se você adicionar um AliasProperty que fornece um nome alternativo para uma propriedade de cadeia de caracteres, 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 AliasProperty correspondente.
Você pode usar o parâmetro SecondValue para especificar um ScriptBlock adicional 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.
Type: | Object |
Position: | 3 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TypeName
Especifica um nome para o tipo.
Quando o tipo é uma classe no namespace Sistema ou um tipo que tem um acelerador de tipo, você pode inserir o nome curto do tipo. Caso contrário, é necessário o nome completo do tipo. Esse parâmetro só é eficaz quando InputObject é um PSObject.
Este parâmetro foi introduzido no Windows PowerShell 3.0.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Value
Especifica o valor inicial do membro adicionado. Se você adicionar um membro AliasProperty, CodeProperty, ScriptProperty ou CodeMethod , poderá fornecer informações adicionais opcionais usando o parâmetro SecondValue .
Type: | Object |
Position: | 2 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Entradas
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, este cmdlet não gera nenhuma saída.
Observações
Você pode adicionar membros somente a objetos PSObject . Para determinar se um objeto é um objeto PSObject , use o -is
operador .
Por exemplo, para testar um objeto armazenado na $obj
variável, digite $obj -is [PSObject]
.
Os nomes dos parâmetros MemberType, Name, Value e 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, Value e SecondValue.
Se você incluir os nomes dos parâmetros, os parâmetros podem aparecer em qualquer ordem.
Você pode usar a $this
variável automática em blocos de script que definem os valores de novas propriedades e métodos.
A $this
variável refere-se à instância do objeto à qual as propriedades e os métodos estão sendo adicionados. Para obter mais informações sobre a $this
variável, consulte about_Automatic_Variables.