about_Functions_OutputTypeAttribute
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.
