about_Functions_OutputTypeAttribute

Letzte Aktualisierung: Mai 2014

Betrifft: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

THEMA

about_Functions_OutputTypeAttribute

KURZE BESCHREIBUNG

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

LANGE BESCHREIBUNG

Das Attribut OutputType listet die .NET-Typen der von der Funktion zurückgegebenen Objekte auf. Mit seinem optionalen Parameter ParameterSetName können Sie die verschiedenen Ausgabetypen der einzelnen Parametersätze auflisten.

Das Attribut OutputType wird von einfachen und erweiterten Funktionen unterstützt. Es ist unabhängig vom Attribut CmdletBinding.

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

Der Wert des Attributs OutputType ist lediglich ein Dokumentationshinweis. Er wird weder vom Funktionscode abgeleitet noch mit der tatsächlichen Ausgabe der Funktion verglichen. Der Wert kann daher auch falsch sein.

SYNTAX

Das Attribut OutputType von Funktionen hat die folgende Syntax:

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

Der Parameter ParameterSetName ist optional.

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

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

Mit dem Parameter ParameterSetName können Sie darauf hinweisen, dass die einzelnen Parametersätze unterschiedliche Ausgabetypen haben.

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

Die Anweisungen mit dem OutputType-Attribut müssen in die Attributliste vor der Param-Anweisung eingefügt werden.

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

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

            <function body>
        }

Das folgende Beispiel zeigt die Platzierung des Attributs OutputType 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

Die folgende Funktion verwendet das OutputType-Attribut, um anzugeben, dass sie einen Zeichenfolgewert zurückgibt.

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

          Hello, $Name      
        }

Die daraus resultierende OutputType-Eigenschaft können Sie mit dem Cmdlet Get-Command abrufen.

        PS C:\> (Get-Command Send-Greeting).OutputType

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

                                                                                    

Die folgende erweiterte Funktion gibt mit dem Attribut OutputType an, dass die Funktion je nach Parametersatz, der im Funktionsbefehl verwendet wird, unterschiedliche Typen zurückgibt.

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

Das folgende Beispiel zeigt, dass die OutputType-Eigenschaft den Wert des Attributs OutputType anzeigt, selbst wenn dieser falsch ist.

Die Funktion Get-Time gibt eine Zeichenfolge mit der Kurzform des Zeitwerts aus DateTime-Objekten zurück. Das Attribut OutputType gibt jedoch an, dass die Funktion ein System.DateTime-Objekt zurückgibt.

        function Get-Time
        { 
            [OutputType([DateTime])]
            Param
            (
               [parameter(Mandatory=$true)]
               [Datetime]$DateTime       
            )
            $DateTime.ToShortTimeString()
        }  

Die Get-Type-Methode bestätigt, dass die Funktion eine Zeichenfolge zurückgibt.

        PS C:\> (Get-Time -DateTime (Get-Date)).Gettype().FullName
        System.String

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

        PS C:\> (Get-Command Get-Time).OutputType

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

HINWEISE

Der Wert der OutputType-Eigenschaft eines FunctionInfo-Objekts ist ein Array aus System.Management.Automation.PSTypeName-Objekten, von denen jedes Namen- und Typeigenschaften aufweist.

Um nur den Namen des jeweiligen Ausgabetyps abzurufen, geben Sie einen Befehl mit dem folgenden Format ein.

        (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 (was zum Beispiel bei einem WMI-Objekt oder einer formatierten Objektansicht der Fall ist).

SIEHE AUCH

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute