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