about_Functions_OutputTypeAttribute

  • Статья

Краткое описание

Содержит описание атрибута, который сообщает о типе объекта, возвращаемого функцией.

Подробное описание

Атрибут OutputType содержит типы объектов .NET, возвращаемые функциями. Вы можете использовать его необязательный параметр ParameterSetName для перечисления различных типов выходных данных для каждого набора параметров.

Атрибут OutputType поддерживается для простых и расширенных функций. Он не зависит от атрибута КомандлетBinding .

Атрибут OutputType предоставляет значение свойства OutputType объекта System.Management.Automation.FunctionInfo, возвращаемого командлетомGet-Command.

Значение атрибута 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 строки

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

  "Hello, $Name"
}

Чтобы просмотреть полученное свойство типа выходных данных, используйте Get-Command командлет.

(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
}

Примечания.

Значение свойства OutputType объекта FunctionInfo представляет собой массив объектов System.Management.Automation.PSTypeName, которые имеют свойства Name и Type.

Чтобы получить только имя каждого выходного типа, используйте команду со следующим форматом.

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

Или ее более короткая версия.

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

Значение свойства OutputType может иметь значение NULL. Используйте значение NULL, если выходные данные не является типом .NET, например объектом WMI или форматированным представлением объекта.

См. также