À propos de Functions OutputTypeAttribute

Article
06/21/2023

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 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 des 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. Il n’est pas dérivé du code de fonction ou comparé à la sortie réelle de la fonction. Par conséquent, la valeur peut être inexacte.

SYNTAX

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 ensembles 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 Sortie 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 incorrecte.

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 et agir, mais qui ne retourne rien.

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

REMARQUES

La valeur de la propriété OutputType d’un objet FunctionInfo est un tableau d’objets System.Management.Automation.PSTypeName , chacun 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 lorsque la sortie n’est pas un type .NET, tel qu’un objet WMI ou une vue mise en forme d’un objet.