Informationen zu 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 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.
SIEHE AUCH
about_Functions_Advanced_Methods