about_Functions_OutputTypeAttribute
Краткое описание
Содержит описание атрибута, который сообщает о типе объекта, возвращаемого функцией.
Подробное описание
Атрибут OutputType перечисляет типы объектов .NET, возвращаемые функциями. Его необязательный параметр ParameterSetName можно использовать для перечисления различных типов выходных данных для каждого набора параметров.
Атрибут OutputType поддерживается в простых и расширенных функциях. Он не зависит от атрибута CmdletBinding .
Атрибут 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. Create функции, которая имеет тип вывода String
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 или форматируемое представление объекта.