about_Functions_OutputTypeAttribute
簡短描述
描述報告函式傳回之物件類型的屬性。
詳細描述
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 物件或物件的格式化檢視。
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應