Add-Member

Module:

Microsoft.PowerShell.Utility Module

Ajoute des propriétés et méthodes personnalisées à une instance d’un objet PowerShell.

Syntaxe

TypeNameSet (Par défaut)

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

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 d’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 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 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. 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é 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 du 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 : 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
$Asset | Add-Member -NotePropertyMembers @{Name="Server30"} -TypeName Asset
$Asset | Add-Member -NotePropertyMembers @{System="Server Core"}
$Asset | Add-Member -NotePropertyMembers @{PSVersion="4.0"}
$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   : Doris
Age    : 20
IntAge : 20

PS> $obj.Age + 1

201

PS> $obj.IntAge + 1

21

La propriété IntAge est 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.

Propriétés du paramètre

Type:	SwitchParameter
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

MemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

NotePropertySingleMemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

NotePropertyMultiMemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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.

Propriétés du paramètre

Type:	PSObject
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	True
Valeur du pipeline:	True
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-MemberType

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

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

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

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.

Propriétés du paramètre

Type:	PSMemberTypes
Valeur par défaut:	None
Valeurs acceptées:	AliasProperty, CodeMethod, CodeProperty, NoteProperty, ScriptMethod, ScriptProperty
Prend en charge les caractères génériques:	False
DontShow:	False
Alias:	Catégorie

Jeux de paramètres

MemberSet

Position:	0
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-Name

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

MemberSet

Position:	1
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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.

Propriétés du paramètre

Type:	IDictionary
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NotePropertyMultiMemberSet

Position:	0
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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.

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NotePropertySingleMemberSet

Position:	0
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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.

Propriétés du paramètre

Type:	Object
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

NotePropertySingleMemberSet

Position:	1
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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.

Propriétés du paramètre

Type:	SwitchParameter
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

(All)

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

-SecondValue

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

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

Propriétés du paramètre

Type:	Object
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

MemberSet

Position:	3
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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 obligatoire. Ce paramètre est effectif uniquement lorsque le InputObject est unPSObject .

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

Propriétés du paramètre

Type:	String
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

TypeNameSet

Position:	Named
Obligatoire:	True
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

NotePropertyMultiMemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

NotePropertySingleMemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

MemberSet

Position:	Named
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	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 .

Propriétés du paramètre

Type:	Object
Valeur par défaut:	None
Prend en charge les caractères génériques:	False
DontShow:	False

Jeux de paramètres

MemberSet

Position:	2
Obligatoire:	False
Valeur du pipeline:	False
Valeur du pipeline par nom de propriété:	False
Valeur des arguments restants:	False

CommonParameters

Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.

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 variable $obj, 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 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.

Liens associés

• Export-Clixml
• Get-Member
• Import-Clixml
• New-Object
• à propos des variables automatiques
• System.Type.GetMethod()