about_Functions_OutputTypeAttribute

發行項
03/20/2024

簡短描述

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

詳細描述

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

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

OutputType 屬性會提供 Cmdlet 傳回之 System.Management.Automation.FunctionInfo 物件的 Get-Command 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>
}

範例

範例 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：使用 OutputType 屬性來指出動態輸出類型

下列進階函式會使用 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-Date).OutputType | Select-Object -ExpandProperty Name

或其較短的版本。

(Get-Command Get-Date).OutputType.Name

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