about_Functions_OutputTypeAttribute

適用於: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

主題

about_Functions_OutputTypeAttribute

簡短描述

描述報告函式所傳回之物件類型的屬性。

詳細描述

OutputType 屬性列出函式所傳回之物件的 .NET 類型。您可以使用其選擇性 ParameterSetName 參數，列出每個參數集的不同輸出類型。

簡單和進階函式都支援 OutputType 屬性。該屬性與 CmdletBinding 屬性無關。

OutputType 屬性提供 Get-Command Cmdlet 所傳回之 System.Management.Automation.FunctionInfo 物件的 OutputType 屬性值。

OutputType 屬性值只是文件附註；並不是衍生自函式程式碼，也不是與實際函式輸出比較的結果。因此，該值可能不正確。

語法

函式的 OutputType 屬性語法如下：

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

ParameterSetName 是選擇性參數。

您可以列出 OutputType 屬性中的多種類型。

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

您可以使用 ParameterSetName 參數，表示不同參數集會傳回不同類型。

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

將 OutputType 屬性陳述式放在 Param 陳述式之前的屬性清單中。

下列範例顯示簡單函式中的 OutputType 屬性位置。

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

            <function body>
        }

下列範例顯示進階函式中的 OutputType 屬性位置。

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

範例

下列函式使用 OutputType 屬性來表示它會傳回字串值。

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

          Hello, $Name      
        }

若要查看產生的輸出類型屬性，請使用 Get-Command Cmdlet。

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

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

                                                                                    

下列進階函式使用 OutputType 屬性來表示函式會根據函式命令中所使用的參數集，傳回不同類型。

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

下列範例示範輸出類型屬性值會顯示 OutputType 屬性的值，即使該值不正確亦然。

Get-Time 函式會傳回字串，其中包含任何日期時間物件中時間的簡短形式。不過，OutputType 屬性回報它會傳回 System.DateTime 物件。

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

Get-Type 方法確認函式會傳回字串。

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

不過，從 OutputType 屬性取得其值的 OutputType 屬性回報函式會傳回日期時間物件。

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

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

附註

FunctionInfo 物件的 OutputType 屬性值是 System.Management.Automation.PSTypeName 物件的陣列，每個輸出都有 Name 和 Type 屬性。

若只要取得每個輸出類型的名稱，請使用下列格式的命令。

        (Get-Command Get-Time).OutputType | ForEach {$_.Name}

OutputType 屬性的值可以是 null。當輸出不是 .NET 類型時 (例如 WMI 物件或物件的格式化檢視)，請使用 null 值。

另請參閱

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute