about_Functions_OutputTypeAttribute
Aggiornamento: maggio 2014
Si applica a: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
ARGOMENTO
about_Functions_OutputTypeAttribute
DESCRIZIONE BREVE
Descrive un attributo che segnala il tipo di oggetto restituito dalla funzione.
DESCRIZIONE LUNGA
L'attributo OutputType elenca i tipi .NET di oggetti restituiti dalle funzioni. È possibile usare il parametro facoltativo ParameterSetName per elencare differenti tipi di output per ogni set di parametri.
L'attributo OutputType è supportato sulle funzioni semplici e avanzate. È indipendente dall'attributo CmdletBinding.
L'attributo OutputType fornisce il valore della proprietà OutputType dell'oggetto System.Management.Automation.FunctionInfo restituito dal cmdlet Get-Command.
Il valore dell'attributo OutputType è solo una nota di documentazione, non è derivato dal codice della funzione o confrontato con l'output della funzione effettiva. Di conseguenza, il valore potrebbe non essere accurato.
SINTASSI
L'attributo OutputType delle funzioni ha la sintassi seguente:
[OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
[OutputType("<TypeNameString>", ParameterSetName="<Name>")]
Il parametro ParameterSetName è facoltativo.
È possibile elencare più tipi di attributo OutputType.
[OutputType([<Type1>],[<Type2>],[<Type3>])]
È possibile usare il parametro ParameterSetName per indicare che differenti parametri impostano tipi restituiti diversi.
[OutputType([<Type1>], ParameterSetName="<Set1>","<Set2>")]
[OutputType([<Type2>], ParameterSetName="<Set3>")]
Inserire le istruzioni di attributo OutputType nell'elenco di attributi che precede l'istruzione Param.
L'esempio seguente illustra il posizionamento dell'attributo OutputType in una funzione semplice.
function SimpleFunction2
{
[OutputType([<Type>])]
Param ($Parameter1)
<function body>
}
L'esempio seguente illustra il posizionamento dell'attributo OutputType nelle funzioni avanzate.
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>
}
ESEMPI
La funzione seguente usa l'attributo OutputType per indicare che restituisce un valore stringa.
function Send-Greeting
{
[OutputType([String])]
Param ($Name)
Hello, $Name
}
Per visualizzare la proprietà del tipo di output risultante, usare il cmdlet Get-Command.
PS C:\> (Get-Command Send-Greeting).OutputType
Name Type
---- ----
System.String System.String
La funzione avanzata seguente usa l'attributo OutputType per indicare che la funzione restituisce tipi diversi a seconda del set di parametri usato nel comando di funzione.
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'esempio seguente dimostra che il valore della proprietà del tipo di output visualizza il valore dell'attributo OutputType, anche quando non è preciso.
La funzione Get-Time restituisce una stringa che contiene la forma breve dell'orario in qualsiasi oggetto DateTime. Tuttavia, l'attributo OutputType segnala che restituisce un oggetto System.DateTime.
function Get-Time
{
[OutputType([DateTime])]
Param
(
[parameter(Mandatory=$true)]
[Datetime]$DateTime
)
$DateTime.ToShortTimeString()
}
Il metodo Get-Type conferma che la funzione restituisce una stringa.
PS C:\> (Get-Time -DateTime (Get-Date)).Gettype().FullName
System.String
Tuttavia, la proprietà OutputType, che ottiene il valore dall'attributo OutputType, segnala che la funzione restituisce un oggetto DateTime.
PS C:\> (Get-Command Get-Time).OutputType
Name Type
---- ----
System.DateTime System.DateTime
NOTE
Il valore della proprietà OutputType di un oggetto FunctionInfo è una matrice di oggetti System.Management.Automation.PSTypeName, ognuno dei quali presenta proprietà Name e Type.
Per ottenere solo il nome di ogni tipo di output, usare un comando con il formato seguente.
(Get-Command Get-Time).OutputType | ForEach {$_.Name}
Il valore della proprietà OutputType può essere null. Usare un valore null quando l'output non è un tipo .NET, ad esempio un oggetto WMI o una vista formattata di un oggetto.
VEDERE ANCHE
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute