about_Functions_OutputTypeAttribute

Aplica-se a: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TÓPICO

about_Functions_OutputTypeAttribute

DESCRIÇÃO BREVE

Descreve um atributo que informa o tipo de objeto que a função retorna.

DESCRIÇÃO LONGA

O atributo OutputType lista os tipos .NET de objetos que retornam as funções. Você pode usar seu parâmetro ParameterSetName opcional para listar diferentes tipos de saída para cada conjunto de parâmetros.

O atributo OutputType é suportado em funções simples e avançadas. É independente do atributo CmdletBinding.

O atributo OutputType fornece o valor da propriedade OutputType do objeto System.Management.Automation.FunctionInfo que o cmdlet Get-Command retorna.

O valor do atributo OutputType é apenas uma nota de documentação. Não é derivado do código de função ou comparado com a saída real da função. Como tal, o valor pode ser impreciso.

SINTAXE

O atributo OutputType funções tem a seguinte sintaxe:

        [OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
        [OutputType("<TypeNameString>", ParameterSetName="<Name>")]

O parâmetro ParameterSetName é opcional.

Você pode listar vários tipos no atributo OutputType.

        [OutputType([<Type1>],[<Type2>],[<Type3>])]

Você pode usar o parâmetro ParameterSetName para indicar que outro parâmetro define tipos diferentes de retorno.

        [OutputType([<Type1>], ParameterSetName="<Set1>","<Set2>")]
        [OutputType([<Type2>], ParameterSetName="<Set3>")]

Coloque as declarações de atributo OutputType na lista de atributos que precede a instrução Param.

O exemplo a seguir mostra o posicionamento do atributo OutputType em uma função simples.

        function SimpleFunction2
        {
    [OutputType([<Type>])]
            Param ($Parameter1)

            <function body>
        }

O exemplo a seguir mostra o posicionamento do atributo OutputType em funções avançadas.

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

EXEMPLOS

A função a seguir usa o atributo OutputType para indicar que ele retorna um valor de cadeia de caracteres.

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

          Hello, $Name      
        }

Para ver a saída resultante para a propriedade do tipo, use o cmdlet Get-Command.

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

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

                                                                                    

A seguinte função avançada usa o atributo OutputType para indicar que a função retorna tipos diferentes, dependendo do conjunto de parâmetros usado no comando da função.

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

O exemplo a seguir demonstra que o valor de propriedade do tipo de saída exibe o valor do atributo OutputType, mesmo quando não estiver correto.

A função Get-Time retorna uma cadeia de caracteres que contém a forma abreviada do tempo de qualquer objeto DateTime. No entanto, o atributo OutputType informa que ele retorna um objeto System. DateTime.

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

O método Get-Type confirma que a função retorna uma cadeia de caracteres.

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

No entanto, a propriedade OutputType, que obtém o valor do atributo OutputType, informa que a função retorna um objeto DateTime.

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

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

OBSERVAÇÕES

O valor da propriedade OutputType de um objeto FunctionInfo é uma matriz de objetos System.Management.Automation.PSTypeName, cada um dos quais possuindo as propriedades Name e Type.

Para obter somente o nome de cada tipo de saída, use um comando com o seguinte formato.

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

O valor da propriedade OutputType pode ser nulo. Use um valor nulo quando a saída não for um tipo .NET, como em um objeto WMI ou uma exibição formatada de um objeto.

CONSULTE TAMBÉM

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute