关于函数 OutputTypeAttribute

简短描述

描述报告函数返回的对象类型的属性。

详细描述

OutputType 属性列出了函数返回的对象的 .NET 类型。您可以使用其可选的 ParameterSetName 参数列出每个参数集的不同输出类型。

简单和高级函数都支持 OutputType 属性。它独立于 CmdletBinding 属性。

OutputType 属性提供 Get-CommandSystem.Management.Automation.FunctionInfo 对象的 OutputType 属性值。 /code> cmdlet 返回。

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 对象的数组，每个对象都有 名称和类型属性。

要仅获取每种输出类型的名称，请使用以下格式的命令。

(Get-Command Get-Date).OutputType | Select-Object -ExpandProperty Name

或者它的较短版本。

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

OutputType 属性的值可以为 null。当输出不是 .NET 类型（例如 WMI 对象或对象的格式化视图）时，请使用 null 值。

参见

• about_函数
• about_功能_高级
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute