about_Functions_OutputTypeAttribute

  • Cikk

Rövid leírás

Egy attribútumot ír le, amely a függvény által visszaadott objektum típusát jelenti.

Hosszú leírás

Az OutputType attribútum felsorolja a függvények által visszaadott .NET-típusú objektumokat. Az opcionális ParameterSetName paraméter használatával különböző kimeneti típusokat listázhat az egyes paraméterkészletekhez.

Az OutputType attribútum egyszerű és speciális függvényeken támogatott. Független a CmdletBinding attribútumtól.

Az OutputType attribútum a parancsmag által visszaadott System.Management.Automation.FunctionInfo objektum Get-Command OutputType tulajdonságának értékét adja meg.

Az OutputType attribútum értéke csak dokumentációs megjegyzés. Nem a függvénykódból származik, és nem hasonlítja össze a tényleges függvénykimenettel. Így előfordulhat, hogy az érték pontatlan.

Syntax

A függvények OutputType attribútuma a következő szintaxist tartalmazza:

[OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
[OutputType("<TypeNameString>", ParameterSetName="<Name>")]

A ParameterSetName paraméter megadása nem kötelező.

Az OutputType attribútumban több típust is listázhat.

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

A ParameterSetName paraméter használatával jelezheti, hogy a különböző paraméterkészletek különböző típusokat adnak vissza.

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

Helyezze a OutputType attribútumutasításokat az utasítást megelőző Param attribútumlistában.

Az alábbi példa a OutputType attribútum egyszerű függvényben való elhelyezését mutatja be.

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

  <function body>
}

Az alábbi példa az OutputType attribútum speciális függvényekben való elhelyezését mutatja be.

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

Példák

1. példa: Karakterlánc kimeneti típusával rendelkező függvény létrehozása

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

  "Hello, $Name"
}

Az eredményként kapott kimeneti típus tulajdonság megtekintéséhez használja a Get-Command parancsmagot.

(Get-Command Send-Greeting).OutputType

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

2. példa: Az OutputType attribútum használata a dinamikus kimeneti típusok jelzésére

Az alábbi speciális függvény az OutputType attribútummal jelzi, hogy a függvény a függvényparancsban használt paraméterkészlettől függően különböző típusokat ad vissza.

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

3. példa: Azt mutatja, hogy a tényleges kimenet mikor tér el az OutputType-tól

Az alábbi példa bemutatja, hogy a kimeneti típus tulajdonság értéke akkor is megjeleníti a OutputType attribútum értékét, ha az pontatlan.

A Get-Time függvény egy karakterláncot ad vissza, amely bármely DateTime objektumban tartalmazza az idő rövid formáját. Az OutputType attribútum azonban azt jelenti, hogy egy System.DateTime objektumot ad vissza.

function Get-Time
{
  [OutputType([DateTime])]
  Param (
    [parameter(Mandatory=$true)]
    [Datetime]$DateTime
  )

  $DateTime.ToShortTimeString()
}

A GetType() metódus megerősíti, hogy a függvény egy sztringet ad vissza.

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

System.String

Az OutputType tulajdonság azonban, amely az OutputType attribútumból szerzi be az értékét, azt jelenti, hogy a függvény egy DateTime objektumot ad vissza.

(Get-Command Get-Time).OutputType

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

4. példa: Olyan függvény, amely nem rendelkezik kimenettel

Az alábbi példa egy egyéni függvényt mutat be, amely műveletet hajt végre, de semmit nem ad vissza.

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

Jegyzetek

A FunctionInfo objektum OutputType tulajdonságának értéke System.Management.Automation.PSTypeName objektumok tömbje, amelyek mindegyike név- és típustulajdonságokkal rendelkezik.

Ha csak az egyes kimeneti típusok nevét szeretné lekérni, használjon egy alábbi formátumú parancsot.

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

Vagy rövidebb verziója.

(Get-Command Get-Date).OutputType.Name

Az OutputType tulajdonság értéke null lehet. Null értéket akkor használjon, ha a kimenet nem .NET-típus, például WMI-objektum vagy egy objektum formázott nézete.

Lásd még