Add-Member
Adiciona propriedades e métodos personalizados a uma instância de um objeto do PowerShell.
Sintaxe
TypeNameSet (Default)
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 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
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
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 é Done.
$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
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
$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
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
$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 objeto personalizado Asset.
O cmdlet New-Object cria um PSObject salvo na variável $Asset. O acelerador de tipo [ordered] cria um dicionário ordenado 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 NoteProperty.
parâmetro typeName atribui o tipo Asset 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 de 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 é uma AliasProperty para a propriedade Age, mas o tipo tem a garantia de 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 é uma ScriptProperty que tem um método Get e Set. Quando atribuimos 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 poderá 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.
Você não pode usar o parâmetro Force para substituir um membro padrão de um tipo.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
MemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
NotePropertySingleMemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
NotePropertyMultiMemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | PSObject |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-MemberType
Especifica o tipo do membro a ser adicionado. Este parâmetro é obrigatório. Os valores aceitáveis para este parâmetro são:
- Propriedade de alias
- Método de código
- Propriedade do código
- Propriedade de Observação
- Método de script
- Propriedade do script
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 membro. Se você especificar um tipo de membro que o objeto não tem, o PowerShell retornará um erro.
Propriedades do parâmetro
| Tipo: | PSMemberTypes |
| Valor padrão: | None |
| Valores aceitos: | AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | Tipo |
Conjuntos de parâmetros
MemberSet
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Name
Especifica o nome do membro que este cmdlet adiciona.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
MemberSet
| Cargo: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-NotePropertyMembers
Especifica um dicionário com hash ou ordenado que contém um par chave-valor que representa NoteProperty nomes 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.
Propriedades do parâmetro
| Tipo: | IDictionary |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
NotePropertyMultiMemberSet
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
NotePropertySingleMemberSet
| Cargo: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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.
Propriedades do parâmetro
| Tipo: | Object |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
NotePropertySingleMemberSet
| Cargo: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-SecondValue
Especifica informações adicionais opcionais sobre AliasProperty, ScriptProperty ou membros do CodeProperty.
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
Para um CodeProperty, o valor deve ser uma referência a um método que implementa um acessador Set. Use o método GetMethod() de uma referência de tipo para obter uma referência a um método. O método deve usar um único parâmetro que seja um PSObject. O acessador Get é atribuído usando o parâmetro valor.
Para um ScriptProperty, o valor deve ser um bloco de script que implementa um acessador Set. O acessador Get é atribuído usando o parâmetro valor.
Propriedades do parâmetro
| Tipo: | Object |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
MemberSet
| Cargo: | 3 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
TypeNameSet
| Cargo: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
NotePropertyMultiMemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
NotePropertySingleMemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
MemberSet
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Value
Especifica o valor inicial do membro adicionado. Se você adicionar um membro AliasProperty, CodePropertyou 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 usar um único parâmetro que seja um PSObject. O acessador Set é 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 acessador Set é atribuído usando o parâmetro SecondValue.
Propriedades do parâmetro
| Tipo: | Object |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
MemberSet
| Cargo: | 2 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | 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 redirecionar 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 estendido recentemente.
Observações
Você pode adicionar membros somente para objetos de tipo 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 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.