Freigeben über

about_Functions_OutputTypeAttribute

Kurzbeschreibung

Beschreibt ein Attribut, das den Typ des Objekts angibt, welches die Funktion zurückgibt.

Lange Beschreibung

Das OutputType-Attribut listet die .NET-Objekttypen auf, die von den Funktionen zurückgegeben werden. Sie können den optionalen Parameter "ParameterSetName" verwenden, um unterschiedliche Ausgabetypen für jeden Parametersatz auflisten.

Das OutputType-Attribut wird für einfache und erweiterte Funktionen unterstützt. Es ist unabhängig vom CmdletBinding-Attribut . Das OutputType-Attribut stellt den Wert der OutputType-Eigenschaft des Vom Cmdlet zurückgegebenen System.Management.Automation.FunctionInfo-ObjektsGet-Command bereit.

Hinweis

Der OutputType-Attributwert wird nicht vom Funktionscode abgeleitet oder mit der tatsächlichen Funktionsausgabe verglichen. Daher kann der Wert ungenau sein.

Das OutputType-Attribut informiert außerdem die Ergebnisse der Registerkartenabschluss für Situationen wie: Command | Select <Tab> und Command | Where <Tab>.

Syntax

Das OutputType-Attribut von Funktionen weist die folgende Syntax auf:

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

Der Parameter "ParameterSetName " ist optional.

Sie können mehrere Typen im OutputType-Attribut auflisten.

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

Sie können den Parameter "ParameterSetName " verwenden, um anzugeben, dass unterschiedliche Parametersätze unterschiedliche Typen zurückgeben.

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

Platzieren Sie die OutputType-Attributanweisungen in der Attributliste, die der param Anweisung vorausgeht.

Das folgende Beispiel zeigt die Platzierung des OutputType-Attributs in einer einfachen Funktion.

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

  <function body>
}

Das folgende Beispiel zeigt die Platzierung des OutputType-Attributs in erweiterten Funktionen.

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

Examples

Beispiel 1: Erstellen einer Funktion mit dem OutputType von String

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

  "Hello, $Name"
}

Verwenden Sie das Get-Command Cmdlet, um die resultierende Ausgabetypeigenschaft anzuzeigen.

(Get-Command Send-Greeting).OutputType

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

Beispiel 2: Verwenden des OutputType-Attributs zum Angeben dynamischer Ausgabetypen

Die folgende erweiterte Funktion verwendet das OutputType-Attribut , um anzugeben, dass die Funktion unterschiedliche Typen zurückgibt, je nachdem, welcher Parametersatz im Funktionsbefehl verwendet wird.

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

Beispiel 3: Zeigt an, wann sich eine tatsächliche Ausgabe vom OutputType unterscheidet.

Im folgenden Beispiel wird veranschaulicht, dass der Wert der Ausgabetypeigenschaft den Wert des OutputType-Attributs anzeigt, auch wenn es ungenau ist.

Die Get-Time Funktion gibt eine Zeichenfolge zurück, die die kurze Form der Uhrzeit in einem beliebigen DateTime-Objekt enthält. Das OutputType-Attribut meldet jedoch, dass es ein System.DateTime-Objekt zurückgibt.

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

  $DateTime.ToShortTimeString()
}

Die GetType() Methode bestätigt, dass die Funktion eine Zeichenfolge zurückgibt.

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

System.String

Die OutputType-Eigenschaft , die ihren Wert aus dem OutputType-Attribut abruft, meldet jedoch, dass die Funktion ein DateTime-Objekt zurückgibt.

(Get-Command Get-Time).OutputType

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

Beispiel 4: Eine Funktion, die keine Ausgabe haben sollte

Das folgende Beispiel zeigt eine benutzerdefinierte Funktion, die eine Aktion ausführen soll, aber nichts zurückgibt.

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

Hinweise

Der Wert der OutputType-Eigenschaft eines FunctionInfo-Objekts ist ein Array von System.Management.Automation.PSTypeName-Objekten, die jeweils Über Name- und Type-Eigenschaften verfügen.

Verwenden Sie einen Befehl mit dem folgenden Format, um nur den Namen jedes Ausgabetyps abzurufen.

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

Oder seine kürzere Version.

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

Der Wert der OutputType-Eigenschaft kann null sein. Verwenden Sie einen NULL-Wert, wenn die Funktion keine Ausgabe in den Erfolgsdatenstrom schreibt. Wenn die Funktion die Ausgabe schreibt, sie aber nicht kennen, verwenden Sie "System.Object".

Siehe auch

  • Last updated on