Partager via

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.

Syntaxe

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

Description

L’applet de commande Add-Member 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 un membre ScriptMethod qui exécute un script pour modifier l’objet.

Pour utiliser , dirigez l’objet vers , ou utilisez 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 Valeur définit la valeur du membre.

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

Vous pouvez également utiliser l’applet de commande Export-Clixml pour enregistrer l’instance de l’objet, y compris les membres supplémentaires, dans un fichier. Vous pouvez ensuite utiliser l’applet de commande Import-Clixml 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 fichier .

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

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 fichier Test.txt. La nouvelle propriété est un alias pour la propriété Length.

La première commande utilise l’applet de commande pour obtenir l’objet FileInfo .

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 ajoute la propriété stringUse note à une chaîne. Étant donné que ne peut pas ajouter de types à 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é 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 SizeInMB à un objet FileInfo qui calcule la taille de fichier au mégaoctet le plus proche. La deuxième commande crée un ScriptBlock qui utilise la méthode statique Round du type pour arrondir la taille du fichier à la deuxième décimale.

Le paramètre Value utilise également la variable automatique $This, qui représente l’objet actuel. La variable $This 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 SizeInMB SizeInMB sur l’objet dans la 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 : Copier toutes les propriétés d’un objet vers un autre

Cette fonction copie toutes les propriétés d’un objet vers un autre objet.

La boucle foreach utilise l’applet de commande Get-Member pour obtenir chacune des propriétés de l’objet From. Les commandes de la boucle foreach sont effectuées en série sur chacune des propriétés.

La commande Add-Member ajoute la propriété de l’objet From à l’objet To en tant que NoteProperty. La valeur est copiée à l’aide du paramètre valeur . Il utilise le paramètre Force pour ajouter des membres portant le même nom de membre.

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

Exemple 6 : Créer un objet personnalisé

Cet exemple crée un objet personnalisé Asset.

L’applet de commande crée unPSObject . L’exemple enregistre le PSObject dans la variable $Asset.

La deuxième commande utilise l’accélérateur de type [ordered] pour créer un dictionnaire ordonné de noms et de valeurs. La commande enregistre le résultat dans la variable $D.

La troisième commande utilise le paramètre NotePropertyMembers de l’applet de commande Add-Member pour ajouter le dictionnaire dans la variable $D à la PSObject. La propriété TypeName attribue un nouveau nom, Asset, auPSObject .

La dernière commande canalise le nouvel objet Asset vers l’applet de commande Get-Member. La sortie indique que l’objet a un nom de type Asset et les propriétés de note que nous avons définies dans le dictionnaire ordonné.

$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

Paramètres

-Force

Indique que cette applet de commande ajoute un nouveau membre, même si l’objet a un membre personnalisé portant le même nom. Vous ne pouvez pas utiliser le paramètre Force pour remplacer un membre standard d’un type.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-InputObject

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

Type:PSObject
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-MemberType

Spécifie le type du membre à ajouter. Ce paramètre est requis. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • RemarqueProperty
  • AliasProperty
  • ScriptProperty
  • CodeProperty
  • ScriptMethod
  • CodeMethod

Pour plus d’informations sur ces valeurs, consultez énumération PSMemberTypes dans msdn library.

Tous les objets n’ont pas tous les types de membres. Si vous spécifiez un type de membre dont l’objet n’a pas, PowerShell retourne une erreur.

Type:PSMemberTypes
Alias:Type
Valeurs acceptées:AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Name

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

Type:String
Position:1
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-NotePropertyMembers

Spécifie une table de hachage ou un dictionnaire ordonné de noms et de valeurs de propriétés de note. Tapez une table de hachage ou un dictionnaire dans lequel les clés sont des noms de propriétés de note et les valeurs sont des valeurs de propriété de note.

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
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques: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
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques: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
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-PassThru

Retourne un objet représentant l’élément avec lequel vous travaillez. 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é des membres uniquement au wrapper d’objets PSObject, et non à l’objet. Utilisez le paramètre passThru pour créer un objet de sortie pour tout objet doté d’un wrapper PSObject.

Type:SwitchParameter
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-SecondValue

Spécifie des informations supplémentaires facultatives sur aliasProperty, scriptProperty, codePropertyou membres de CodeMethod.

Si elle est utilisée lors de l’ajout d’unAliasProperty , 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 duAliasProperty .

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 lorsque vous y accédez à l’aide du AliasProperty correspondant.

Vous pouvez utiliser le paramètre SecondValue pour spécifier un ScriptBlock supplémentaire lors de l’ajout d’un membre ScriptProperty. Le premier ScriptBlock, spécifié dans le paramètre valeur , est utilisé pour obtenir la valeur d’une variable. Le deuxième ScriptBlock, spécifié dans le paramètre SecondValue , est utilisé pour définir la valeur d’une variable.

Type:Object
Position:3
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-TypeName

Spécifie un nom pour le type.

Lorsque le type est une classe dans l’espace de noms system 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 requis. Ce paramètre est effectif uniquement lorsque le InputObject est unPSObject .

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

Type:String
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Value

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

Type:Object
Position:2
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

PSObject

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

Sorties

None or System.Object

Lorsque vous utilisez le paramètre passThru , cette applet de commande retourne l’objet nouvellement étendu. Sinon, cette applet de commande ne génère aucune sortie.

Notes

Vous ne pouvez ajouter des membres qu’à objets 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 variable $obj, tapez $obj -is [PSObject].

Les noms desMemberType , Name, Valueet Paramètres de 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, Valueet SecondValue.

Si vous incluez les noms de paramètres, les paramètres peuvent apparaître dans n’importe quel ordre.

Vous pouvez utiliser la variable automatique $this dans les blocs de script qui définissent les valeurs des nouvelles propriétés et méthodes. La variable $this 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 variable $this, consultez about_Automatic_Variables.