about_Functions_OutputTypeAttribute

簡短描述

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

完整描述

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

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

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

OutputType 屬性值只是文件備註。 它不是衍生自函式程式碼,或與實際的函式輸出相較之下。 因此,此值可能不正確。

Syntax

函式的 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>
}

範例

範例 1:建立具有 String OutputType 的函式

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

  "Hello, $Name"
}

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

(Get-Command Send-Greeting).OutputType
Name                                               Type
----                                               ----
System.String                                      System.String

範例 2:使用 Output 屬性來指出動態輸出類型

下列進階函式會使用 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>
}

範例 3:顯示實際輸出與 OutputType 有何不同

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

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

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

  $DateTime.ToShortTimeString()
}

方法 GetType() 會確認函式會傳回字串。

(Get-Time -DateTime (Get-Date)).GetType().FullName
System.String

不過,從 OutputType 屬性取得其值的 OutputType 屬性會報告函式會傳回 DateTime 物件。

(Get-Command Get-Time).OutputType
Name                                      Type
----                                      ----
System.DateTime                           System.DateTime

範例 4:不應該有輸出的函式

下列範例示範應該執行的自訂函式,但不會傳回任何專案。

function Invoke-Notepad
{
  [OutputType([System.Void])]
  Param ()
  & notepad.exe | Out-Null
}

備註

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

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

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

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

另請參閱