Add-Member

Módulo:

Microsoft.PowerShell.Utility

Agrega propiedades y métodos personalizados a una instancia de un objeto de 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

El Add-Member cmdlet permite agregar miembros (propiedades y métodos) a una instancia de un objeto de PowerShell. Por ejemplo, puede agregar un miembro NoteProperty que contenga una descripción del objeto o un miembro ScriptMethod que ejecute un script para cambiar el objeto.

Para usar Add-Member, canalice el objeto a Add-Membero use el parámetro InputObject para especificar el objeto .

El parámetro MemberType indica el tipo de miembro que desea agregar. El parámetro Name asigna un nombre al nuevo miembro y el parámetro Value establece el valor del miembro.

Las propiedades y los métodos que agregue se agregan solo a la instancia concreta del objeto especificado. Add-Member no cambia el tipo de objeto. Para crear un nuevo tipo de objeto, use el Add-Type cmdlet .

También puede usar el Export-Clixml cmdlet para guardar la instancia del objeto, incluidos los miembros adicionales, en un archivo. A continuación, puede usar el Import-Clixml cmdlet para volver a crear la instancia del objeto a partir de la información almacenada en el archivo exportado.

A partir de Windows PowerShell 3.0, Add-Member tiene nuevas características que facilitan la adición de propiedades de nota a objetos. Puede usar los parámetros NotePropertyName y NotePropertyValue para definir una propiedad de nota o usar el parámetro NotePropertyMembers , que toma una tabla hash de los nombres y valores de las propiedades de nota.

Además, a partir de Windows PowerShell 3.0, el parámetro PassThru , que genera un objeto de salida, es necesario con menos frecuencia. Add-Member ahora agrega los nuevos miembros directamente al objeto de entrada de más tipos. Para obtener más información, consulte la descripción del parámetro PassThru .

Ejemplos

Ejemplo 1: Agregar una propiedad note a un PSObject

En el ejemplo siguiente se agrega una propiedad Status Note con un valor de "Done" al objeto FileInfo que representa el Test.txt archivo.

El primer comando usa el Get-ChildItem cmdlet para obtener un objeto FileInfo que representa el Test.txt archivo. Lo guarda en la $a variable .

El segundo comando agrega la propiedad note al objeto en $a.

El tercer comando usa la notación de puntos para obtener el valor de la propiedad Status del objeto en $a. Como se muestra en la salida, el valor es Done.

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

Done

Ejemplo 2: Agregar una propiedad de alias a un PSObject

En el ejemplo siguiente se agrega una propiedad de alias Size al objeto que representa el Test.txt archivo. La nueva propiedad es un alias para la propiedad Length .

El primer comando usa el Get-ChildItem cmdlet para obtener el Test.txtobjeto FileInfo .

El segundo comando agrega la propiedad Alias de tamaño . El tercer comando usa la notación de puntos para obtener el valor de la nueva propiedad Size .

$A = Get-ChildItem C:\Temp\test.txt
$A | Add-Member -MemberType AliasProperty -Name Size -Value Length
$A.Size

2394

Ejemplo 3: Agregar una propiedad stringUse note a una cadena

En este ejemplo se agrega la propiedad StringUse note a una cadena. Dado Add-Member que no se pueden agregar tipos a objetos de entrada String , puede especificar el parámetro PassThru para generar un objeto de salida. El último comando del ejemplo muestra la nueva propiedad.

En este ejemplo se usa el parámetro NotePropertyMembers . El valor del parámetro NotePropertyMembers es una tabla hash. La clave es el nombre de la propiedad note, StringUse y el valor es el valor de la propiedad note, Display.

$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse

Display

Ejemplo 4: Agregar un método de script a un objeto FileInfo

En este ejemplo se agrega el método de script SizeInMB a un objeto FileInfo que calcula el tamaño del archivo al megabyte más cercano. El segundo comando crea un scriptBlock que usa el método estático Round del [math] tipo para redondear el tamaño del archivo hasta la segunda posición decimal.

El parámetro Value también usa la $This variable automática, que representa el objeto actual. La $This variable solo es válida en bloques de script que definen nuevas propiedades y métodos.

El último comando usa la notación de puntos para llamar al nuevo método de script SizeInMB en el objeto de la $A variable .

$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

Ejemplo 5: Crear un objeto personalizado

En este ejemplo se crea un objeto personalizado Asset .

El New-Object cmdlet crea un PSObject que se guarda en la $Asset variable . El [ordered] acelerador de tipos crea un diccionario ordenado almacenado en la $d variable . Canalización $Asset para Add-Member agregar los pares clave-valor en el diccionario al objeto como miembros NoteProperty . El parámetro TypeName asigna el tipo Asset al PSObject. El Get-Member cmdlet muestra el tipo y las propiedades del objeto. Sin embargo, las propiedades se enumeran en orden alfabético, no en el orden en que se agregaron.

$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

Al inspeccionar la lista sin procesar de propiedades se muestran las propiedades en el orden en que se agregaron al objeto . Format-Table se usa en este ejemplo para crear una salida similar a Get-Member.

Ejemplo 6: Agregar aliasProperty a un objeto

En este ejemplo se crea un objeto personalizado que contiene dos miembros NoteProperty . El tipo de una propiedad NoteProperty refleja el tipo del valor almacenado en la propiedad . En este caso, la propiedad Age es una cadena.

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

La propiedad intAge es aliasProperty para la propiedad Age, pero se garantiza que el tipo es uint32.

Ejemplo 7: Adición de métodos get y set a un objeto personalizado

En este ejemplo se muestra cómo definir métodos Get y Set que acceden a una propiedad profundamente anidada.

$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 la propiedad Title es un ScriptProperty que tiene un método Get y Set . Cuando asignamos un nuevo valor a la propiedad Title , se llama al método Set y cambia el valor de la propiedad Role en la propiedad Position .

Parámetros

-Force

De forma predeterminada, Add-Member no se puede agregar un nuevo miembro si el objeto ya tiene un miembro con el mismo. Cuando se usa el parámetro Force , Add-Member reemplaza el miembro existente por el nuevo miembro. No se puede usar el parámetro Force para reemplazar un miembro estándar de un tipo.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputObject

Especifica el objeto al que se agrega el nuevo miembro. Especifique una variable que contenga los objetos o escriba un comando o una expresión que obtenga los objetos.

Type:	PSObject
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-MemberType

Especifica el tipo del miembro que se va a agregar. Este parámetro es obligatorio. Los valores permitidos para este parámetro son los siguientes:

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

Para obtener información sobre estos valores, consulte Enumeración PSMemberTypes en el SDK de PowerShell.

No todos los objetos tienen cada uno de los tipos de miembro. Si especifica un tipo de miembro que el objeto no tiene, PowerShell devuelve un error.

Type:	PSMemberTypes
Aliases:	Type
Accepted values:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Especifica el nombre del miembro que agrega este cmdlet.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-NotePropertyMembers

Especifica un diccionario hash o ordenado que contiene un par clave-valor que representa los nombres NoteProperty y sus valores. Para obtener más información sobre las tablas hash y los diccionarios ordenados en PowerShell, consulte about_Hash_Tables.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:	IDictionary
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-NotePropertyName

Especifica el nombre de la propiedad de nota.

Use este parámetro con el parámetro NotePropertyValue . Este parámetro es opcional.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-NotePropertyValue

Especifica el valor de la propiedad note.

Use este parámetro con el parámetro NotePropertyName . Este parámetro es opcional.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:	Object
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-PassThru

Devuelve un objeto que representa el elemento con el que está trabajando. De forma predeterminada, este cmdlet no genera ninguna salida.

Para la mayoría de los objetos, Add-Member agrega los nuevos miembros al objeto de entrada. Sin embargo, cuando el objeto de entrada es una cadena, Add-Member no puede agregar el miembro al objeto de entrada. Para estos objetos, use el parámetro PassThru para crear un objeto de salida.

En Windows PowerShell 2.0, Add-Member solo se agregaron miembros al contenedor PSObject de objetos, no al objeto . Use el parámetro PassThru para crear un objeto de salida para cualquier objeto que tenga un contenedor PSObject .

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SecondValue

Especifica información adicional opcional sobre los miembros AliasProperty, ScriptProperty o CodeProperty.

Si se usa al agregar un AliasProperty, este parámetro debe ser un tipo de datos. Se agrega una conversión al tipo de datos especificado al valor de AliasProperty. Por ejemplo, si agrega un AliasProperty que proporciona un nombre alternativo para una propiedad de cadena, también puede especificar un parámetro SecondValue de System.Int32 para indicar que el valor de esa propiedad de cadena se debe convertir en un entero cuando se tiene acceso a él mediante el aliasProperty correspondiente.

Para codeProperty, el valor debe ser una referencia a un método que implemente un descriptor de acceso Set. Use el GetMethod() método de una referencia de tipo para obtener una referencia a un método. El método debe tomar un único parámetro que sea PSObject. El descriptor de acceso Get se asigna mediante el parámetro Value .

Para un ScriptProperty, el valor debe ser un bloque de script que implemente un descriptor de acceso Set . El descriptor de acceso Get se asigna mediante el parámetro Value .

Type:	Object
Position:	3
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TypeName

Especifica un nombre para el tipo.

Cuando el tipo es una clase en el espacio de nombres System o en un tipo que tiene un acelerador de tipos, puede escribir el nombre corto del tipo. De lo contrario, se requiere el nombre de tipo completo. Este parámetro solo es efectivo cuando InputObject es un PSObject.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Value

Especifica el valor inicial del miembro agregado. Si agrega un miembro AliasProperty, CodeProperty o ScriptProperty, puede proporcionar información adicional mediante el parámetro SecondValue.

• Para aliasProperty, el valor debe ser el nombre de la propiedad que se va a establecer como alias.
• Para codeMethod, el valor debe ser una referencia a un método . Use el GetMethod() método de una referencia de tipo para obtener una referencia a un método.
• Para codeProperty, el valor debe ser una referencia a un método que implementa un descriptor de acceso Get. Use el GetMethod() método de una referencia de tipo para obtener una referencia a un método. Referencia. El método debe tomar un único parámetro que sea PSObject. El descriptor de acceso Set se asigna mediante el parámetro SecondValue .
• Para un ScriptMethod, el valor debe ser un bloque de script.
• Para un ScriptProperty, el valor debe ser un bloque de script que implemente un descriptor de acceso Get . El descriptor de acceso Set se asigna mediante el parámetro SecondValue .

Type:	Object
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

PSObject

Puede canalizar cualquier objeto a este cmdlet.

Salidas

None

De forma predeterminada, este cmdlet no devuelve ninguna salida.

Object

Cuando se usa el parámetro PassThru , este cmdlet devuelve el objeto recién extendido.

Notas

Solo puede agregar miembros a objetos de tipo PSObject . Para determinar si un objeto es un objeto PSObject , use el -is operador . Por ejemplo, para probar un objeto almacenado en la $obj variable , escriba $obj -is [psobject].

Los objetos de tipo PSObject mantienen su lista de miembros en el orden en que los miembros se agregaron al objeto .

Los nombres de los parámetros MemberType, Name, Value y SecondValue son opcionales. Si omite los nombres de parámetro, los valores de parámetro sin nombre deben aparecer en este orden: MemberType, Name, Value y SecondValue.

Si incluye los nombres de parámetro, estos pueden aparecer en cualquier orden.

Puede usar la $this variable automática en bloques de script que definen los valores de las nuevas propiedades y métodos. La $this variable hace referencia a la instancia del objeto al que se agregan las propiedades y los métodos. Para obtener más información sobre la $this variable, consulte about_Automatic_Variables.

Vínculos relacionados

• Export-Clixml
• Get-Member
• Import-Clixml
• New-Object
• about_Automatic_Variables
• System.Type.GetMethod()