about_Functions_OutputTypeAttribute

Mis à jour: mai 2014

S'applique à: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

RUBRIQUE

about_Functions_OutputTypeAttribute

DESCRIPTION COURTE

Décrit un attribut qui indique le type d'objet retourné par la fonction.

DESCRIPTION DÉTAILLÉE

L'attribut OutputType répertorie les types .NET d'objets retournés par les fonctions. Vous pouvez utiliser son paramètre ParameterSetName facultatif pour répertorier différents types de sorties pour chaque jeu de paramètres.

L'attribut OutputType est pris en charge dans les fonctions simples et avancées. Il est indépendant de l'attribut CmdletBinding.

L'attribut OutputType fournit la valeur de la propriété OutputType de l'objet System.Management.Automation.FunctionInfo retourné par l'applet de commande Get-Command.

La valeur de l'attribut OutputType est uniquement une note de documentation. Elle n'est pas dérivée du code de fonction ni comparée à la sortie de fonction réelle. Par conséquent, la valeur peut être inexacte.

SYNTAXE

L'attribut OutputType des fonctions présente la syntaxe suivante :

        [OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
        [OutputType("<TypeNameString>", ParameterSetName="<Name>")]

Le paramètre ParameterSetName est facultatif.

Vous pouvez répertorier plusieurs types dans l'attribut OutputType.

        [OutputType([<Type1>],[<Type2>],[<Type3>])]

Vous pouvez utiliser le paramètre ParameterSetName pour indiquer que différents jeux de paramètres retournent différents types.

        [OutputType([<Type1>], ParameterSetName="<Set1>","<Set2>")]
        [OutputType([<Type2>], ParameterSetName="<Set3>")]

Placez les instructions d'attribut OutputType dans la liste des attributs qui précède l'instruction Param.

L'exemple suivant illustre le positionnement de l'attribut OutputType dans une fonction simple.

        function SimpleFunction2
        {
    [OutputType([<Type>])]
            Param ($Parameter1)

            <function body>
        }

L'exemple suivant illustre le positionnement de l'attribut OutputType dans les fonctions avancées.

       function AdvancedFunction1
       {
           [OutputType([<Type>])]
           Param (      
               [parameter(Mandatory=$true)]
               [String[]]
               $Parameter1  
           )     
                  
         <function body>
       }

       function AdvancedFunction2
       {
           [CmdletBinding(SupportsShouldProcess=<Boolean>)]
           [OutputType([<Type>])]
           Param (      
               [parameter(Mandatory=$true)]
               [String[]]
               $Parameter1  
           )     
                  
         <function body>
       }

EXEMPLES

La fonction suivante utilise l'attribut OutputType pour indiquer qu'elle retourne une valeur de chaîne.

        function Send-Greeting
        {
          [OutputType([String])]   
          Param ($Name)

          Hello, $Name      
        }

Pour afficher la propriété de type de sortie obtenue, utilisez l'applet de commande Get-Command.

        PS C:\> (Get-Command Send-Greeting).OutputType

        Name                                               Type                                                                                                     
        ----                                               ----                                                                                                     
        System.String                                      System.String        

                                                                                    

La fonction avancée suivante utilise l'attribut OutputType pour indiquer que la fonction retourne des types différents selon le jeu de paramètres utilisé dans la commande de fonction.

       function Get-User
       {
           [CmdletBinding(DefaultParameterSetName="ID")]

           [OutputType("System.Int32", ParameterSetName="ID")]
           [OutputType([String], ParameterSetName="Name")]

           Param (      
               [parameter(Mandatory=$true, ParameterSetName="ID")]
               [Int[]]
               $UserID,

               [parameter(Mandatory=$true, ParameterSetName="Name")]
               [String[]]
               $UserName
           )     
                  
         <function body>
       }

L'exemple suivant montre que la valeur de propriété de type de sortie affiche la valeur de l'attribut OutputType, même quand elle est inexacte.

La fonction Get-Time retourne une chaîne qui contient la forme abrégée de l'heure dans n'importe quel objet DateTime. Toutefois, l'attribut OutputType signale qu'elle retourne un objet System.DateTime.

        function Get-Time
        { 
            [OutputType([DateTime])]
            Param
            (
               [parameter(Mandatory=$true)]
               [Datetime]$DateTime       
            )
            $DateTime.ToShortTimeString()
        }  

La méthode Get-Type confirme que la fonction retourne une chaîne.

        PS C:\> (Get-Time -DateTime (Get-Date)).Gettype().FullName
        System.String

Toutefois, la propriété OutputType, qui obtient sa valeur de l'attribut OutputType, signale que la fonction retourne un objet DateTime.

        PS C:\> (Get-Command Get-Time).OutputType

        Name                                      Type                                                                                                     
        ----                                      ----                                                                                                     
        System.DateTime                           System.DateTime

REMARQUES

La valeur de la propriété OutputType d'un objet FunctionInfo est un tableau d'objets System.Management.Automation.PSTypeName, chacun d'entre eux ayant des propriétés Name et Type.

Pour obtenir uniquement le nom de chaque type de sortie, utilisez une commande au format suivant.

        (Get-Command Get-Time).OutputType | ForEach {$_.Name}

La valeur de la propriété OutputType peut être null. Utilisez une valeur null quand la sortie n'est pas un type .NET, comme un objet WMI ou une vue formatée d'un objet.

VOIR AUSSI

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute