about_Functions_OutputTypeAttribute

Článek
2024-01-20

Krátký popis

Popisuje atribut, který hlásí typ objektu, který funkce vrátí.

Dlouhý popis

Atribut OutputType uvádí typy objektů .NET, které funkce vrací. Volitelný parametr ParameterSetName můžete použít k výpisu různých výstupních typů pro každou sadu parametrů.

Atribut OutputType je podporován u jednoduchých a pokročilých funkcí. Je nezávislý na atributu CmdletBinding .

Atribut OutputType poskytuje hodnotu OutputType vlastnost System.Management.Automation.FunctionInfo objektu, který rutina Get-Command vrátí.

Hodnota atributu OutputType je pouze poznámka k dokumentaci. Neodvozuje se z kódu funkce ani ve srovnání se skutečným výstupem funkce. Proto může být hodnota nepřesná.

Syntaxe

Atribut OutputType funkcí má následující syntaxi:

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

Parametr ParameterSetName je volitelný.

V atributu OutputType můžete vypsat více typů.

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

Parametr ParameterSetName můžete použít k označení, že různé sady parametrů vracejí různé typy.

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

Umístěte příkazy atributu OutputType do seznamu atributů, který předchází param příkazu.

Následující příklad ukazuje umístění outputType atributu v jednoduché funkci.

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

  <function body>
}

Následující příklad ukazuje umístění outputType atributu v pokročilých funkcích.

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říklady

Příklad 1: Vytvoření funkce, která má OutputType řetězce

function Send-Greeting
{
  [OutputType([string])]
  param ($Name)

  "Hello, $Name"
}

Pokud chcete zobrazit výslednou vlastnost výstupního typu, použijte rutinu Get-Command .

(Get-Command Send-Greeting).OutputType

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

Příklad 2: Použití atributu OutputType k označení dynamických typů výstupu

Následující pokročilá funkce používá outputType atribut k označení, že funkce vrací různé typy v závislosti na sadě parametrů použité v příkazu funkce.

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

Příklad 3: Ukazuje, kdy se skutečný výstup liší od outputType

Následující příklad ukazuje, že hodnota vlastnosti výstupního typu zobrazuje hodnotu OutputType atributu, i když je nepřesná.

Funkce Get-Time vrátí řetězec, který obsahuje krátkou formu času v libovolném objektu DateTime . Atribut OutputType však hlásí, že vrací System.DateTime objekt.

function Get-Time
{
  [OutputType([datetime])]
  param (
    [Parameter(Mandatory=$true)]
    [datetime]$DateTime
  )

  $DateTime.ToShortTimeString()
}

Metoda GetType() potvrzuje, že funkce vrací řetězec.

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

System.String

Nicméně OutputType vlastnost, která získá jeho hodnotu z OutputType atributu, hlásí, že funkce vrací DateTime objekt.

(Get-Command Get-Time).OutputType

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

Příklad 4: Funkce, která by neměla mít výstup

Následující příklad ukazuje vlastní funkci, která by měla provést akci, ale nevrací nic.

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

Notes

Hodnota OutputType vlastnost FunctionInfo objektu je pole System.Management.Automation.PSTypeName objekty, které mají vlastnosti Name a Type.

Pokud chcete získat pouze název každého typu výstupu, použijte příkaz s následujícím formátem.

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

Nebo jeho kratší verze.

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

Hodnota OutputType vlastnost může být null. Hodnotu null použijte, pokud výstup není typem .NET, jako je objekt WMI nebo formátované zobrazení objektu.

Sdílet prostřednictvím