Om Functions OutputTypeAttribute

Artikel
05/09/2024

KORT BESKRIVNING

Beskriver ett attribut som rapporterar den typ av objekt som funktionen returnerar.

LÅNG BESKRIVNING

Attributet OutputType listar de .NET-typer av objekt som funktionerna returnerar. Du kan använda den valfria ParameterSetName-parametern för att visa olika utdatatyper för varje parameteruppsättning.

Attributet OutputType stöds för enkla och avancerade funktioner. Den är oberoende av attributet CmdletBinding.

Attributet OutputType innehåller värdet för outputtype-egenskapen för objektet System.Management.Automation.FunctionInfo som cmdleten Get-Command returnerar.

Attributet OutputType är bara en dokumentationsanteckning. Den härleds inte från funktionskoden eller jämförs med de faktiska funktionsutdata. Därför kan värdet vara felaktigt.

SYNTAX

Attributet OutputType för funktioner har följande syntax:

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

Parametern ParameterSetName är valfri.

Du kan visa flera typer i attributet OutputType.

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

Du kan använda parametern ParameterSetName för att ange att olika parameteruppsättningar returnerar olika typer.

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

Placera OutputType-attributinstruktionerna i attributlistan som föregår -instruktionen Param .

I följande exempel visas placeringen av attributet OutputType i en enkel funktion.

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

  <function body>
}

I följande exempel visas placeringen av attributet OutputType i avancerade funktioner.

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

EXEMPEL

Exempel 1: Skapa en funktion som har outputtype-strängen

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

  "Hello, $Name"
}

Om du vill se den resulterande utdatatypens egenskap använder du cmdleten Get-Command .

(Get-Command Send-Greeting).OutputType

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

Exempel 2: Använd attributet Output för att ange dynamiska utdatatyper

Följande avancerade funktion använder attributet OutputType för att ange att funktionen returnerar olika typer beroende på parameteruppsättningen som används i funktionskommandot.

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

Exempel 3: Visar när faktiska utdata skiljer sig från OutputType

I följande exempel visas att egenskapsvärdet för utdatatypen visar värdet för attributet OutputType, även om det är felaktigt.

Funktionen Get-Time returnerar en sträng som innehåller den korta formen av tiden i ett DateTime-objekt. Attributet OutputType rapporterar dock att det returnerar ett System.DateTime-objekt .

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

  $DateTime.ToShortTimeString()
}

Metoden GetType() bekräftar att funktionen returnerar en sträng.

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

System.String

Egenskapen OutputType, som hämtar dess värde från attributet OutputType, rapporterar dock att funktionen returnerar ett DateTime-objekt .

(Get-Command Get-Time).OutputType

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

Exempel 4: En funktion som inte ska ha utdata

I följande exempel visas en anpassad funktion som ska utföra och åtgärder men inte returnera något.

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

ANTECKNINGAR

Värdet för egenskapen OutputType för ett FunctionInfo-objekt är en matris med System.Management.Automation.PSTypeName-objekt som var och en har egenskaper för Namn och Typ.

Om du bara vill hämta namnet på varje utdatatyp använder du ett kommando med följande format.

(Get-Command Get-Time).OutputType | ForEach {$_.Name}

Värdet för egenskapen OutputType kan vara null. Använd ett null-värde när utdata inte är en .NET-typ, till exempel ett WMI-objekt eller en formaterad vy av ett objekt.