about_Functions_OutputTypeAttribute

Artikel
10/04/2023

Kort beskrivning

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

Lång beskrivning

Attributet OutputType visar en lista över de .NET-typer av objekt som funktionerna returnerar. Du kan använda den valfria parametern ParameterSetName 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 egenskapen OutputType 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 -instruktionenParam.

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 of String

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

  "Hello, $Name"
}

Om du vill se den resulterande egenskapen för utdatatyp använder du cmdleten Get-Command .

(Get-Command Send-Greeting).OutputType

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

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

Följande avancerade funktion använder attributet OutputType för att indikera 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 värdet 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 en åtgärd men inte returnera något.

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

Kommentar

Värdet för egenskapen OutputType för ett FunctionInfo-objekt är en matris med objekten System.Management.Automation.PSTypeName, 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-Date).OutputType | Select-Object -ExpandProperty Name

Eller dess kortare version.

(Get-Command Get-Date).OutputType.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.