lundi 24 octobre 2011

Add-Member

NOM
    Add-Member

RÉSUMÉ
    Ajoute un membre personnalisé défini par l'utilisateur à une instance d'un objet Windows PowerShell.

SYNTAXE
    Add-Member [-MemberType] {AliasProperty | CodeProperty | Property | NoteProperty | ScriptProperty | Properties | PropertySet | Method | CodeMethod | ScriptMethod | Methods | ParameterizedProperty | MemberSet | Event | All} [-Name] <string> -InputObject <psobject> [[-Value] <Object>] [[-SecondValue] <Object>] [-Force] [-PassThru] [<CommonParameters>]


DESCRIPTION
    L'applet de commande Add-Member ajoute un membre personnalisé défini par l'utilisateur à une instance d'un objet Windows PowerShell. Elle vous permet d'ajouter les types de membres suivants : AliasProperty, CodeProperty, NoteProperty, ScriptProperty, PropertySet, CodeMethod, MemberSet et ScriptMethod. Vous définissez la valeur initiale du membre en utilisant le paramètre Value. En ce qui concerne AliasProperty, ScriptProperty, CodeProperty et CodeMethod, vous pouvez fournir des informations supplémentaires à l'aide du paramètre SecondValue.

    Les membres supplémentaires sont ajoutés à l'instance particulière de l'objet que vous dirigez vers Add-Member ou spécifiez à l'aide du paramètre InputObject. Le membre supplémentaire est disponible uniquement pendant que cette instance existe. Vous pouvez utiliser l'applet de commande Export-Clixml pour enregistrer l'instance, y compris les membres supplémentaires, dans un fichier. Les informations stockées dans ce fichier peuvent être utilisées par l'applet de commande Import-Clixml pour recréer l'instance de l'objet.


PARAMÈTRES
    -Force [<SwitchParameter>]
        Ajoute un nouveau membre même si un autre membre portant le même nom existe déjà. Ne fonctionne pas pour les membres principaux d'un type.

        Obligatoire ?                false
        Position ?                   named
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  false

    -InputObject <psobject>
        Spécifie l'objet auquel le nouveau membre est ajouté. Entrez une variable contenant les objets ou tapez une commande ou une expression permettant d'obtenir ces objets.

        Obligatoire ?                true
        Position ?                   named
        Valeur par défaut
        Accepter l'entrée de pipeline ?       true (ByValue)
        Accepter les caractères génériques ?  false

    -MemberType <PSMemberTypes>
        Spécifie le type de membre à ajouter.  Ce paramètre est obligatoire.

        Les valeurs valides pour ce paramètre sont :
        -- AliasProperty : propriété qui définit un nouveau nom pour une propriété existante.
        -- CodeMethod : méthode qui référence une méthode statique d'une classe Microsoft .NET Framework.
        -- CodeProperty : propriété qui référence une propriété statique d'une classe .NET Framework.
        -- MemberSet : collection prédéfinie de propriétés et de méthodes, telles que PSBase, PSObject et PSTypeNames.
        -- Method : méthode de l'objet .NET Framework sous-jacent.
        -- NoteProperty : propriété ayant une valeur statique.
        -- ParameterizedProperty : propriété qui utilise des paramètres et des valeurs de paramètre.
        -- Property : propriété de l'objet .NET Framework sous-jacent.
        -- PropertySet : collection prédéfinie de propriétés d'objet.
        -- ScriptMethod : méthode dont la valeur est la sortie d'un script.
        -- ScriptProperty : propriété dont la valeur est la sortie d'un script.

        -- All : obtient tous les types de membres.
        -- Methods : obtient tous les types de méthodes de l'objet (par exemple method, codemethod, scriptmethod).
        -- Properties : obtient tous les types de propriétés de l'objet (par exemple property, codeproperty, aliasprope
        rty, scriptproperty).

        Tous les objets ne possèdent pas chaque type de membre. Si vous spécifiez un type de membre non associé à l'objet, Windows PowerShell retourne une erreur.

        Le type de membre Event n'est pas valide pour Add-Member.

        Obligatoire ?                true
        Position ?                   1
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  true

    -Name <string>
        Spécifie le nom du membre à ajouter.

        Si vous omettez le nom du paramètre « Name », la valeur du paramètre -Name doit être la deuxième valeur de paramètre sans nom dans la commande. Si vous incluez le nom de paramètre, les paramètres peuvent apparaître dans tout ordre.

        Obligatoire ?                true
        Position ?                   2
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  false

    -PassThru [<SwitchParameter>]
        Passe l'objet récemment étendu au pipeline. Par défaut, cette applet de commande ne génère aucune sortie.

        Obligatoire ?                false
        Position ?                   named
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  false

    -SecondValue <Object>
        Spécifie des informations supplémentaires facultatives relatives aux membres AliasProperty, ScriptProperty, CodeProperty ou CodeMethod. Si vous utilisez ce paramètre lors de l'ajout d'un AliasProperty, il doit alors s'agir d'un type de données. Une conversion (transtypage) en type de données spécifié est ajoutée à la valeur d'AliasProperty. Par exemple, si vous ajoutez un AliasProperty qui fournit un autre nom pour une propriété de type chaîne, vous pouvez également affecter la valeur System.Int32 au paramètre SecondValue pour indiquer que la valeur de cette propriété de type chaîne doit être convertie en un nombre entier en cas d'accès via 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. Dans ce cas, 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.

        Obligatoire ?                false
        Position ?                   4
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  false

    -Value <Object>
        Spécifie la valeur initiale du membre ajouté. Si vous ajoutez un membre AliasProperty, CodeProperty ou CodeMethod, vous pouvez fournir des informations supplémentaires facultatives en utilisant le paramètre SecondValue.

        Obligatoire ?                false
        Position ?                   3
        Valeur par défaut
        Accepter l'entrée de pipeline ?       false
        Accepter les caractères génériques ?  false

    <CommonParameters>
        Cette applet de commande prend en charge les paramètres courants : Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer et OutVariable. Pour plus d'informations, tapez
        « get-help about_commonparameters ».

ENTRÉES
    System.Management.Automation.PSObject
        Vous pouvez diriger n'importe quel type d'objet vers Add-Member.


SORTIES
    Aucun ou System.Object
        Lorsque vous utilisez le paramètre PassThru, Add-Member retourne l'objet récemment étendu. Sinon, cette applet de commande ne génère aucune sortie.


NOTES


        Vous pouvez ajouter uniquement des membres aux objets PSObjects. 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 des paramètres MemberType, Name, Value et SecondValue sont facultatifs. Si vous omettez les noms de paramètre, les valeurs de paramètre sans nom doivent apparaître dans l'ordre suivant : MemberType, Name, Value, SecondValue. Si vous incluez les noms de paramètre, les paramètres peuvent apparaître dans n'importe quel ordre.


    -------------------------- EXEMPLE 1 --------------------------

    C:\PS>$a = (get-childitem)[0]

    C:\PS> $a | add-member -membertype noteproperty -name Status -value done

    C:\PS> $a | get-member -type noteproperty

       TypeName: System.IO.DirectoryInfo

    Name          MemberType   Definition
    ----          ----------   ----------
    PSChildName   NoteProperty System.String PSChildName=Co
    PSDrive       NoteProperty System.Management.Automation
    PSIsContainer NoteProperty System.Boolean PSIsContainer
    PSParentPath  NoteProperty System.String PSParentPath=M
    PSPath        NoteProperty System.String PSPath=Microso
    PSProvider    NoteProperty System.Management.Automation
    Status        NoteProperty System.String Status=done


    Description
    -----------
    Ces commandes ajoutent la propriété de note Status à un objet DirectoryInfo retourné par Get-ChildItem et lui attribuent la valeur « done ».

    La première commande obtient le premier objet retourné par Get-Childitem (index 0).

    La deuxième commande ajoute la propriété de note.

    La troisième commande utilise un opérateur de pipeline (|) pour envoyer l'objet mis à jour à l'applet de commande Get-Member. La sortie montre que la propriété a été ajoutée.





    -------------------------- EXEMPLE 2 --------------------------

    C:\PS>$a = (get-childitem)[0]

    C:\PS> $a | add-member -membertype aliasproperty -name FileLength -value Length

    C:\PS> $a.filelength


    Description
    -----------
    Ces commandes ajoutent la propriété d'alias FileLength à un objet DirectoryInfo retourné par Get-ChildItem. La nouvelle propriété est un alias de la propriété Length.

    La première commande obtient le premier objet retourné par Get-Childitem (index 0).

    La deuxième commande ajoute la propriété d'alias.

    La troisième ligne de la commande retourne la valeur de la nouvelle propriété FileLength.





    -------------------------- EXEMPLE 3 --------------------------

    C:\PS>$a = "a string"

    C:\PS> $a = $a | add-member -membertype noteproperty -name StringUse -value Display -passthru

    C:\PS> $a.StringUse


    Description
    -----------
    Ces commandes ajoutent la propriété StringUse à une chaîne. Étant donné que la chaîne n'est pas un objet PSObject, vous devez inclure le paramètre PassThru dans la commande pour enregistrer la chaîne étendue dans la variable. La dernière commande de l'exemple affiche la nouvelle propriété.





    -------------------------- EXEMPLE 4 --------------------------

    C:\PS>$a = "this is a string"

    C:\PS> $a = add-member -inputobject $a -membertype scriptmethod -name words `
    -value {$this.split()} -passthru

    C:\PS> $a.words()


    Description
    -----------
    Ces commandes ajoutent une méthode de script à un objet chaîne. La méthode de script expose la méthode Split() de la classe de bibliothèque de classes .NET Framework System.String pour permettre le retour de mots individuels dans une chaîne via l'appel d'une méthode nommée « Words » sur l'objet chaîne. Notez que le paramètre PassThru est spécifié pour forcer Add-Member à retourner l'objet chaîne étendue en tant que sortie à stocker dans la variable $a.





    -------------------------- EXEMPLE 5 --------------------------

    C:\PS>$event = get-eventlog -logname system -newest 1

    C:\PS> $event.TimeWritten | get-member

    C:\PS> add-member -inputobject $event -membertype aliasproperty -name When `
    -value TimeWritten -secondvalue System.String

    C:\PS> $event.When | get-member


    Description
    -----------
    Ces commandes ajoutent un AliasProperty à un objet EventLogEntry retourné par les applets de commande Get-EventLog.
     L'AliasProperty est nommé « When » et est un alias de la propriété TimeWritten de l'objet. Le paramètre SecondValue est utilisé pour spécifier que la valeur de propriété doit être convertie en type System.String en cas d'accès via AliasProperty ; la propriété TimeWritten est un objet DateTime.

    La première commande utilise l'applet de commande Get-EventLog pour récupérer l'événement le plus récent du journal des événements système et l'enregistrer dans la variable $event.

    La deuxième commande accède à la propriété TimeWritten de cet événement et la dirige vers l'applet de commande Get-Member pour montrer que la propriété est de type DateTime. Ensuite, Add-Member est utilisé pour ajouter un membre AliasProperty à l'instance de l'objet EventLogEntry stocké dans la variable $event. Le paramètre Name est utilisé pour donner au nom du nouveau membre la valeur « When » et le paramètre Value est utilisé pour spécifier qu'il s'agit d'un alias de la propriété TimeWritten. Le paramètre SecondValue sert à indiquer que, lorsque ce nouveau membre est utilisé, la valeur qu'il retourne doit être transtypée de son type d'origine System.DateTime en un type System.String.

    La troisième commande accède au nouveau membre et le dirige vers l'applet de commande Get-Member pour confirmer que son type est System.String.





    -------------------------- EXEMPLE 6 --------------------------

    C:\PS>function Copy-Property ($From, $To)

    {
      foreach ($p in Get-Member -InputObject $From -MemberType Property)
      {
         Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name
         -Value $From.$($p.Name) -Force

         $To.$($p.Name) = $From.$($p.Name)
       }
    }


    Description
    -----------
    Cette fonction copie toutes les propriétés d'un objet vers un autre objet.

    La première commande de la fonction déclare le nom de cette dernière et liste ses paramètres.

    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 exécuté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 propriété NoteProperty. Elle utilise le paramètre Force pour permettre à la commande d'ajouter des membres portant le même nom.

    La dernière commande de la fonction donne à la nouvelle propriété le nom de la propriété d'origine.






LIENS CONNEXES
    Online version: http://go.microsoft.com/fwlink/?LinkID=113280
    Get-Member
    Export-Clixml
    Import-Clixml

Aucun commentaire:

Enregistrer un commentaire