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>
}
示例
示例 1:创建一个 OutputType 为 String 的函数
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 类型(例如 WMI 对象或某个对象的格式化视图)时,请使用 null 值。
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈