Add-Member
Ajoute des propriétés et des méthodes personnalisées à un 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) à un instance d’un objet PowerShell. Par instance, 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 Add-Member, dirigez l’objet vers Add-Member, 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 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 les instance de l’objet, y compris les membres supplémentaires, dans un fichier. Ensuite, vous pouvez utiliser l’applet Import-Clixml de commande pour recréer le instance de l’objet à partir des informations stockées dans le fichier exporté.
À partir 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 le paramètre NotePropertyMembers, qui utilise une table de hachage des noms et valeurs des propriétés de note.
Par ailleurs, à compter de Windows PowerShell 3.0, le paramètre PassThru, qui génère un objet de sortie, est moins utile. 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é de note d’état avec la valeur « Done » à l’objet FileInfo qui représente le Test.txt fichier.
La première commande utilise l’applet de Get-ChildItem 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é 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
DoneExemple 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 de Get-ChildItem commande pour obtenir l’objet Test.txtFileInfo .
La deuxième commande ajoute la propriété Size alias. 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
2394Exemple 3 : Ajouter une propriété de note StringUse à une chaîne
Cet exemple montre comment ajouter la propriété de note StringUse à une chaîne.
Étant donné que Add-Member impossible d’ajouter des types aux 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é de note, Display.
$A = "A string"
$A = $A | Add-Member -NotePropertyMembers @{StringUse="Display"} -PassThru
$A.StringUse
DisplayExemple 4 : Ajouter une méthode de script à un objet FileInfo
Cet exemple montre comment ajouter la méthode de script SizeInMB à un objet FileInfo qui calcule la taille du fichier sur le MegaByte 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 actif. 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 SizeInMB 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.43Exemple 5 : Copier toutes les propriétés d’un objet dans un autre
Cette fonction copie toutes les propriétés d'un objet dans un autre objet.
La foreach boucle utilise l’applet Get-Member de commande pour obtenir chacune des propriétés de l’objet From . Les commandes au sein de la foreach boucle sont exécutées en série sur chacune des propriétés.
La Add-Member commande 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 Value . 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 : Create un objet personnalisé
Cet exemple crée un objet personnalisé Asset .
L’applet New-Object de commande crée un PSObject. L’exemple enregistre le PSObject dans la $Asset variable.
La deuxième commande utilise l’accélérateur [ordered] de type pour créer un dictionnaire ordonné de noms et de valeurs. La commande enregistre le résultat dans la $D variable .
La troisième commande utilise le paramètre NotePropertyMembers de l’applet Add-Member de commande pour ajouter le dictionnaire dans la $D variable au PSObject.
La propriété TypeName attribue un nouveau nom, Asset, au PSObject.
La dernière commande envoie le nouvel objet Asset à l’applet de Get-Member commande. 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 CoreParamè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 |
| 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 :
- RemarqueProperty
- AliasProperty
- ScriptProperty
- CodeProperty
- ScriptMethod
- CodeMethod
Pour plus d’informations sur ces valeurs, consultez PsMemberTypes, énumération 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 que l’objet n’a pas, PowerShell retourne une erreur.
| Type: | PSMemberTypes |
| Aliases: | Type |
| Accepted values: | AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All |
| 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 une table de hachage ou un dictionnaire ordonné de valeurs et de noms de la propriété de note. Tapez une table de hachage ou un dictionnaire dans lequel les clés sont les noms des propriétés de note et les valeurs sont celles des propriétés de note.
Pour plus d’informations sur les tables de hachage et les dictionnaires trié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 la propriété 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 aucun résultat.
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 les membres ajoutés uniquement au wrapper PSObject des 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, CodeProperty ou CodeMethod.
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 lors de l’accès à l’aide de l’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 Value , 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 |
| 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 n’est effectif que lorsque l’objet 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, ScriptProperty ou CodeMethod , vous pouvez fournir des informations supplémentaires facultatives à 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
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 pouvez ajouter des membres uniquement aux objets PSObject . Pour déterminer si un objet est un objet PSObject , utilisez l’opérateur -is .
Pour instance, pour tester un objet stocké dans la $obj variable, tapez $obj -is [PSObject].
Les noms des paramètres MemberType, Name, Value et SecondValue sont facultatifs. Si vous omettez les noms des paramètres, les valeurs de paramètre sans nom 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 variable automatique dans des $this blocs de script qui définissent les valeurs des nouvelles propriétés et méthodes.
La $this variable fait référence à la instance de l’objet auquel les propriétés et les méthodes sont ajoutées. Pour plus d’informations sur la $this variable, consultez about_Automatic_Variables.