about_Functions_OutputTypeAttribute

  • Articolo

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 tipi di output diversi per ogni set di parametri.

L'attributo OutputType è supportato in 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 Get-Command cmdlet.

Il valore dell'attributo OutputType è solo una nota di documentazione. Non è derivato dal codice della funzione o confrontato con l'output effettivo della funzione. 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 nell'attributo OutputType .

[OutputType([<Type1>],[<Type2>],[<Type3>])]

È possibile usare il parametro ParameterSetName per indicare che i diversi set di parametri restituiscono tipi diversi.

[OutputType([<Type1>], ParameterSetName=("<Set1>","<Set2>"))]
[OutputType([<Type2>], ParameterSetName="<Set3>")]

Inserire le istruzioni dell'attributo OutputType nell'elenco di attributi che precede l'istruzione Param .

Nell'esempio seguente viene illustrato il posizionamento dell'attributo OutputType in una funzione semplice.

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

  <function body>
}

Nell'esempio seguente viene illustrato 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

Esempio 1: Creare una funzione con OutputType di String

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

  "Hello, $Name"
}

Per visualizzare la proprietà del tipo di output risultante, usare il Get-Command cmdlet .

(Get-Command Send-Greeting).OutputType

Name                                               Type
----                                               ----
System.String                                      System.String

Esempio 2: Usare l'attributo OutputType per indicare i tipi di output dinamici

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 della 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>
}

Esempio 3: Mostra quando un output effettivo è diverso da OutputType

Nell'esempio seguente viene illustrato che il valore della proprietà del tipo di output visualizza il valore dell'attributo OutputType , anche quando è impreciso.

La Get-Time funzione restituisce una stringa che contiene la forma breve dell'ora 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 GetType() metodo conferma che la funzione restituisce una stringa.

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

System.String

Tuttavia, la proprietà OutputType , che ottiene il relativo valore dall'attributo OutputType , segnala che la funzione restituisce un oggetto DateTime .

(Get-Command Get-Time).OutputType

Name                                      Type
----                                      ----
System.DateTime                           System.DateTime

Esempio 4: Una funzione che non deve avere output

L'esempio seguente mostra una funzione personalizzata che deve eseguire un'azione ma non restituire nulla.

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

Note

Il valore della proprietà OutputType di un oggetto FunctionInfo è una matrice di oggetti System.Management.Automation.PSTypeName , ognuno con proprietà Name e Type .

Per ottenere solo il nome di ogni tipo di output, usare un comando con il formato seguente.

(Get-Command Get-Date).OutputType | Select-Object -ExpandProperty Name

O la sua versione più breve.

(Get-Command Get-Date).OutputType.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 visualizzazione formattata di un oggetto .

Vedi anche