Поделиться через

about_Functions_OutputTypeAttribute

Назначение: Windows PowerShell 3.0

РАЗДЕЛ

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

ПРИМЕРЫ

Приведенная ниже функция использует атрибут OutputType для указания на то, что она возвращает строковое значение.

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

          Hello, $Name      
        }

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

        PS C:\> (Get-Command Send-Greeting).OutputType

        Name                                               Type                                                                                                     
        ----                                               ----                                                                                                     
        System.String                                      System.String

Приведенная ниже расширенная функция использует атрибут 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>
       }

В примере ниже показано, что свойство типа выходных данных содержит значение атрибута OutputType, даже если оно неточное.

Функция Get-Time возвращает строку, содержащую значение времени из объекта DateTime в краткой форме. Однако атрибут OutputType сообщает, что она возвращает объект System.DateTime.

        function Get-Time
        { 
            [OutputType([DateTime])]
            Param
            (
               [parameter(Mandatory=$true)]
               [Datetime]$DateTime       
            )
            $DateTime.ToShortTimeString()
        }

Метод Get-Type подтверждает, что функция возвращает строку.

        PS C:\> (Get-Time -DateTime (Get-Date)).Gettype().FullName
        System.String

Однако свойство OutputType, которое получает значение из атрибута OutputType, сообщает, что функция возвращает объект DateTime.

        PS C:\> (Get-Command Get-Time).OutputType

        Name                                      Type                                                                                                     
        ----                                      ----                                                                                                     
        System.DateTime                           System.DateTime

ПРИМЕЧАНИЯ

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

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

        (Get-Command Get-Time).OutputType | ForEach {$_.Name}

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

СМ. ТАКЖЕ

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute