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 .NET d’objets que les fonctions retournent. 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. Elle est indépendante de l’attribut CmdletBinding.
L’attribut OutputType fournit la valeur de la propriété OutputType de l’objet System.Management.Automation.FunctionInfo que l’applet de Get-Command commande retourne.
La valeur de l’attribut OutputType n’est qu’une note de documentation. Il n’est pas dérivé du code de la fonction ni 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ède 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 l’emplacement 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 : Create une fonction qui a le OutputType de String
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 Output 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 function.
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 : indique quand une sortie réelle diffère du 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 abrégée 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 et sans retourner quoi que ce soit.
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 , 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.