Add-Member

Référence

Module:: Microsoft.PowerShell.Utility

Ajoute des propriétés et méthodes personnalisées à une instance d’un objet 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

L’applet Add-Member de commande vous permet d’ajouter des membres (propriétés et méthodes) à une instance d’un objet PowerShell. Par exemple, vous pouvez ajouter un membre NoteProperty qui contient une description de l’objet ou d’un membre ScriptMethod qui exécute un script pour modifier l’objet.

Pour utiliser Add-Member, diriger l’objet Add-Membervers , ou utiliser le paramètre InputObject pour spécifier l’objet.

Le paramètre MemberType indique le type de membre que vous souhaitez ajouter. Le paramètre Name attribue un nom au nouveau membre et le paramètre Value définit la valeur du membre.

Les propriétés et méthodes que vous ajoutez le sont uniquement à l'instance spécifique de l'objet spécifié. Add-Member ne modifie pas le type d’objet. Pour créer un type d’objet, utilisez l’applet de Add-Type commande.

Vous pouvez également utiliser l’applet Export-Clixml de commande pour enregistrer l’instance de l’objet, y compris les membres supplémentaires, dans un fichier. Vous pouvez ensuite utiliser l’applet Import-Clixml de commande pour recréer l’instance de l’objet à partir des informations stockées dans le fichier exporté.

À compter de Windows PowerShell 3.0, Add-Member dispose de nouvelles fonctionnalités qui facilitent l’ajout de propriétés de note aux objets. Vous pouvez utiliser les paramètres NotePropertyName et NotePropertyValue pour définir une propriété de note ou utiliser le paramètre NotePropertyMembers , qui prend une table de hachage des noms et des valeurs de propriété de note.

En outre, à partir de Windows PowerShell 3.0, le paramètre PassThru , qui génère un objet de sortie, est nécessaire moins fréquemment. Add-Member ajoute désormais les nouveaux membres directement à l’objet d’entrée d’autres types. Pour plus d’informations, consultez la description du paramètre PassThru .

Exemples

Exemple 1 : Ajouter une propriété de note à un OBJET PSObject

L’exemple suivant ajoute une propriété Status note avec la valeur « Done » à l’objet FileInfo qui représente le Test.txt fichier.

La première commande utilise l’applet Get-ChildItem de commande pour obtenir un objet FileInfo représentant le Test.txt fichier. Il l’enregistre dans la $a variable.

La deuxième commande ajoute la propriété de note à l’objet dans $a.

La troisième commande utilise la notation par points pour obtenir la valeur de la propriété Status de l’objet dans $a. Comme le montre la sortie, la valeur est Done.

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

Done

Exemple 2 : Ajouter une propriété d’alias à un OBJET PSObject

L’exemple suivant ajoute une propriété d’alias Size à l’objet qui représente le Test.txt fichier. La nouvelle propriété est un alias pour la propriété Length .

La première commande utilise l’applet Get-ChildItem de commande pour obtenir l’objet Test.txtFileInfo .

La deuxième commande ajoute la propriété d’alias Size . La troisième commande utilise la notation par points pour obtenir la valeur de la nouvelle propriété Size .

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

2394

Exemple 3 : Ajouter une propriété de note StringUse à une chaîne

Cet exemple montre comment ajouter la propriété StringUse note à une chaîne. Comme Add-Member vous ne pouvez pas ajouter de types à des objets d’entrée String , vous pouvez spécifier le paramètre PassThru pour générer un objet de sortie. La dernière commande de l'exemple affiche la nouvelle propriété.

Cet exemple utilise le paramètre NotePropertyMembers . La valeur du paramètre NotePropertyMembers est une table de hachage. La clé est le nom de la propriété de note, StringUse et la valeur est la valeur de la propriété note, Display.

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

Display

Exemple 4 : Ajouter une méthode de script à un objet FileInfo

Cet exemple ajoute la méthode de script SizeIn Mo à un objet FileInfo qui calcule la taille du fichier au mégaoctet le plus proche. La deuxième commande crée un ScriptBlock qui utilise la méthode statique Round du [math] type pour arrondir la taille du fichier à la deuxième décimale.

Le paramètre Value utilise également la $This variable automatique, qui représente l’objet actuel. La $This variable est valide uniquement dans les blocs de script qui définissent de nouvelles propriétés et méthodes.

La dernière commande utilise la notation par points pour appeler la nouvelle méthode de script SizeIn Mo sur l’objet dans 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

Exemple 5 : Créer un objet personnalisé

Cet exemple crée un objet personnalisé Asset .

L’applet New-Object de commande crée un PSObject enregistré dans la $Asset variable. L’accélérateur [ordered] de type crée un dictionnaire ordonné stocké dans la $d variable. Piping $Asset pour Add-Member ajouter les paires clé-valeur dans le dictionnaire à l’objet en tant que membres NoteProperty . Le paramètre TypeName affecte le type Asset au PSObject. L’applet Get-Member de commande affiche le type et les propriétés de l’objet. Toutefois, les propriétés sont répertoriées par ordre alphabétique, et non dans l’ordre dans lequel elles ont été ajoutées.

$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

L’inspection de la liste brute des propriétés affiche les propriétés dans l’ordre dans lequel elles ont été ajoutées à l’objet. Format-Table est utilisé dans cet exemple pour créer une sortie similaire à Get-Member.

Exemple 6 : Ajouter un AliasProperty à un objet

Dans cet exemple, nous créons un objet personnalisé qui contient deux membres NoteProperty . Le type d’une propriété NoteProperty reflète le type de la valeur stockée dans la propriété. Dans ce cas, la propriété Age est une chaîne.

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 propriété intAge est un AliasProperty pour la propriété Age , mais le type est garanti comme uint32.

Exemple 7 : Ajouter des méthodes get et set à un objet personnalisé

Cet exemple montre comment définir des méthodes Get et Set qui accèdent à une propriété profondément imbriquée.

$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

Notez que la propriété Title est un ScriptProperty qui a une méthode Get et Set . Lorsque nous affectons une nouvelle valeur à la propriété Title , la méthode Set est appelée et modifie la valeur de la propriété Role dans la propriété Position .

Paramètres

-Force

Par défaut, Add-Member ne peut pas ajouter de nouveau membre si l’objet possède déjà un membre avec le même membre. Lorsque vous utilisez le paramètre Force , Add-Member remplace le membre existant par le nouveau membre. Vous ne pouvez pas utiliser le paramètre Force pour remplacer un membre standard d’un type.

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

-InputObject

Spécifie l'objet auquel le nouveau membre est ajouté. Entrez une variable contenant les objets, ou tapez une commande ou une expression qui obtient ces objets.

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

-MemberType

Spécifie le type du membre à ajouter. Ce paramètre est obligatoire. Les valeurs valides pour ce paramètre sont :

AliasProperty
CodeMethod
CodeProperty
RemarqueProperty
ScriptMethod
ScriptProperty

Pour plus d’informations sur ces valeurs, consultez énumération PSMemberTypes dans le Kit de développement logiciel (SDK) PowerShell.

Certains objets n'ont pas chaque type de membre. Si vous spécifiez un type de membre dont l’objet n’a pas, PowerShell retourne une erreur.

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

Spécifie le nom du membre ajouté par cette applet de commande.

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

-NotePropertyMembers

Spécifie un dictionnaire de hachage ou ordonné qui contient une paire clé-valeur représentant les noms NoteProperty et leurs valeurs. Pour plus d’informations sur les tables de hachage et les dictionnaires ordonnés dans PowerShell, consultez about_Hash_Tables.

Ce paramètre a été introduit dans Windows PowerShell 3.0.

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

-NotePropertyName

Spécifie le nom de la propriété de note.

Utilisez ce paramètre avec le paramètre NotePropertyValue . Ce paramètre est facultatif.

Ce paramètre a été introduit dans Windows PowerShell 3.0.

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

-NotePropertyValue

Spécifie la valeur de propriété de note.

Utilisez ce paramètre avec le paramètre NotePropertyName . Ce paramètre est facultatif.

Ce paramètre a été introduit dans Windows PowerShell 3.0.

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

-PassThru

Retourne un objet représentant l’élément que vous utilisez. Par défaut, cette applet de commande ne génère aucune sortie.

Pour la plupart des objets, Add-Member ajoute les nouveaux membres à l’objet d’entrée. Toutefois, lorsque l’objet d’entrée est une chaîne, Add-Member ne peut pas ajouter le membre à l’objet d’entrée. Pour ces objets, utilisez le paramètre PassThru pour créer un objet de sortie.

Dans Windows PowerShell 2.0, Add-Member ajout de membres uniquement au wrapper PSObject d’objets, et non à l’objet. Utilisez le paramètre PassThru pour créer un objet de sortie pour tout objet qui a un wrapper PSObject .

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

-SecondValue

Spécifie des informations supplémentaires facultatives sur les membres AliasProperty, ScriptProperty ou CodeProperty .

S’il est utilisé lors de l’ajout d’un AliasProperty, ce paramètre doit être un type de données. Une conversion vers le type de données spécifié est ajoutée à la valeur de l’AliasProperty. Par exemple, si vous ajoutez un AliasProperty qui fournit un autre nom pour une propriété de chaîne, vous pouvez également spécifier un paramètre SecondValue de System.Int32 pour indiquer que la valeur de cette propriété de chaîne doit être convertie en entier lorsqu’elle est accessible à l’aide de l’AliasProperty correspondant.

Pour un CodeProperty, la valeur doit être une référence à une méthode qui implémente un accesseur Set . Utilisez la GetMethod() méthode d’une référence de type pour obtenir une référence à une méthode. La méthode doit prendre un paramètre unique qui est un PSObject. L’accesseur Get est affecté à l’aide du paramètre Value .

Pour un ScriptProperty, la valeur doit être un bloc de script qui implémente un accesseur Set . L’accesseur Get est affecté à l’aide du paramètre Value .

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

-TypeName

Spécifie un nom pour le type.

Lorsque le type est une classe dans l’espace de noms System ou un type qui a un accélérateur de type, vous pouvez entrer le nom court du type. Sinon, le nom de type complet est obligatoire. Ce paramètre est effectif uniquement lorsque InputObject est un OBJET PSObject.

Ce paramètre a été introduit dans Windows PowerShell 3.0.

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

-Value

Spécifie la valeur initiale du membre ajouté. Si vous ajoutez un membre AliasProperty, CodeProperty ou ScriptProperty , vous pouvez fournir des informations supplémentaires à l’aide du paramètre SecondValue .

Pour un AliasProperty, la valeur doit être le nom de la propriété en cours d’alias.
Pour un CodeMethod, la valeur doit être une référence à une méthode. Utilisez la GetMethod() méthode d’une référence de type pour obtenir une référence à une méthode.
Pour un CodeProperty, la valeur doit être une référence à une méthode qui implémente un accesseur Get . Utilisez la GetMethod() méthode d’une référence de type pour obtenir une référence à une méthode. Référence. La méthode doit prendre un paramètre unique qui est un PSObject. L’accesseur Set est affecté à l’aide du paramètre SecondValue .
Pour un ScriptMethod, la valeur doit être un bloc de script.
Pour un ScriptProperty, la valeur doit être un bloc de script qui implémente un accesseur Get . L’accesseur Set est affecté à l’aide du paramètre SecondValue .

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

Entrées

PSObject

Vous pouvez diriger n’importe quel objet vers cette applet de commande.

Sorties

None

Par défaut, cette applet de commande ne retourne aucune sortie.

Object

Lorsque vous utilisez le paramètre PassThru , cette applet de commande retourne l’objet nouvellement étendu.

Notes

Vous pouvez ajouter des membres uniquement aux objets de type PSObject . Pour déterminer si un objet est un objet PSObject , utilisez l’opérateur -is . Par exemple, pour tester un objet stocké dans la $obj variable, tapez $obj -is [psobject].

Les objets de type PSObject conservent leur liste de membres dans l’ordre dans lequel les membres ont été ajoutés à l’objet.

Les noms des paramètres MemberType, Name, Value et SecondValue sont facultatifs. Si vous omettez les noms de paramètres, les valeurs de paramètre non nommées doivent apparaître dans cet ordre : MemberType, Name, Value et SecondValue.

Si vous incluez les noms de paramètres, les paramètres peuvent apparaître dans tout ordre.

Vous pouvez utiliser la $this variable automatique dans les blocs de script qui définissent les valeurs des nouvelles propriétés et méthodes. La $this variable fait référence à l’instance de l’objet auquel les propriétés et méthodes sont ajoutées. Pour plus d’informations sur la $this variable, consultez about_Automatic_Variables.

Add-Member

Syntax

Description

Exemples

Exemple 1 : Ajouter une propriété de note à un OBJET PSObject

Exemple 2 : Ajouter une propriété d’alias à un OBJET PSObject

Exemple 3 : Ajouter une propriété de note StringUse à une chaîne

Exemple 4 : Ajouter une méthode de script à un objet FileInfo

Exemple 5 : Créer un objet personnalisé

Exemple 6 : Ajouter un AliasProperty à un objet

Exemple 7 : Ajouter des méthodes get et set à un objet personnalisé

Paramètres

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

Entrées

Sorties

Notes

Commentaires

Ressources supplémentaires

Add-Member

Syntax

Description

Exemples

Exemple 1 : Ajouter une propriété de note à un OBJET PSObject

Exemple 2 : Ajouter une propriété d’alias à un OBJET PSObject

Exemple 3 : Ajouter une propriété de note StringUse à une chaîne

Exemple 4 : Ajouter une méthode de script à un objet FileInfo

Exemple 5 : Créer un objet personnalisé

Exemple 6 : Ajouter un AliasProperty à un objet

Exemple 7 : Ajouter des méthodes get et set à un objet personnalisé

Paramètres

-Force

-InputObject

-MemberType

-Name

-NotePropertyMembers

-NotePropertyName

-NotePropertyValue

-PassThru

-SecondValue

-TypeName

-Value

Entrées

Sorties

Notes

Liens associés

Commentaires

Ressources supplémentaires