Informationen zu Functions OutputTypeAttribute

Artikel
05/09/2024

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 ParameterSetName-Parameter verwenden, um verschiedene Ausgabetypen für jeden Parametersatz auflisten.

Das OutputType-Attribut wird für einfache und erweiterte Funktionen unterstützt. Sie ist unabhängig vom CmdletBinding-Attribut.

Das OutputType-Attribut stellt den Wert der OutputType-Eigenschaft des System.Management.Automation.FunctionInfo-Objekts bereit, das das Get-Command Cmdlet zurückgibt.

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 ParameterSetName-Parameter ist optional.

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

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

Sie können den 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 vorangestellt ist.

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: Create einer Funktion, die über den OutputType von String verfügt

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

  "Hello, $Name"
}

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

(Get-Command Send-Greeting).OutputType

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

Beispiel 2: Verwenden des Output-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 er ungenau ist.

Die Get-Time Funktion gibt eine Zeichenfolge zurück, die die Kurzform 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ückgeben soll.

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 die Eigenschaften Name und Type verfügen.

Um nur den Namen der einzelnen Ausgabetypen abzurufen, verwenden Sie einen Befehl im folgenden Format.

(Get-Command Get-Time).OutputType | ForEach {$_.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.