about_Functions_OutputTypeAttribute

Description courte

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

Description longue

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

L’attribut OutputType est pris en charge sur 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 Get-Command de commande.

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

Syntaxe

L’attribut OutputType des fonctions a 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èdent l’instruction Param .

L’exemple suivant montre le placement de l’attribut OutputType dans une fonction simple.

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

  <function body>
}

L’exemple suivant montre le placement 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

Exemple 1 : Créer une fonction qui a le OutputType de chaîne

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

  "Hello, $Name"
}

Pour afficher la propriété de type de sortie résultante, utilisez l’applet de Get-Command commande.

(Get-Command Send-Greeting).OutputType
Name                                               Type
----                                               ----
System.String                                      System.String

Exemple 2 : Utiliser l’attribut OutputType pour indiquer les types de sortie dynamiques

La fonction avancée suivante utilise l’attribut OutputType pour indiquer que la fonction retourne différents types en fonction du 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>
}

Exemple 3 : Montre quand une sortie réelle diffère de OutputType

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

La Get-Time fonction retourne une chaîne qui contient la forme courte de l’heure dans n’importe quel objet DateTime . Toutefois, l’attribut OutputType signale qu’il retourne un objet System.DateTime .

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

  $DateTime.ToShortTimeString()
}

La GetType() méthode confirme que la fonction retourne une chaîne.

(Get-Time -DateTime (Get-Date)).GetType().FullName
System.String

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

(Get-Command Get-Time).OutputType
Name                                      Type
----                                      ----
System.DateTime                           System.DateTime

Exemple 4 : fonction qui ne doit pas avoir de sortie

L’exemple suivant montre une fonction personnalisée qui doit effectuer une action, mais qui ne retourne rien.

function Invoke-Notepad
{
  [OutputType([System.Void])]
  Param ()
  & notepad.exe | Out-Null
}

Notes

La valeur de la propriété OutputType d’un objet FunctionInfo est un tableau d’objets System.Management.Automation.PSTypeName , qui ont chacune 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-Date).OutputType | Select-Object -ExpandProperty Name

Ou sa version plus courte.

(Get-Command Get-Date).OutputType.Name

La valeur de la propriété OutputType peut être null. Utilisez une valeur Null lorsque la sortie n’est pas un type .NET, tel qu’un objet WMI ou une vue mise en forme d’un objet.

Voir aussi