about_Functions_OutputTypeAttribute

  • Artikel

Kurze Beschreibung

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.

Der Wert des Attributs OutputType ist nur ein Dokumentationshinweis. Sie wird nicht vom Funktionscode abgeleitet oder mit der tatsächlichen Funktionsausgabe verglichen. Daher kann der Wert ungenau sein.

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

Beispiele

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 Ausgabe kein .NET-Typ ist, z. B. ein WMI-Objekt oder eine formatierte Ansicht eines Objekts.

Weitere Informationen