about_Functions_OutputTypeAttribute

  • Artigo

Breve descrição

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

Descrição longa

O atributo OutputType lista os tipos .NET de objetos que as funções retornam. Você pode usar seu parâmetro opcional ParameterSetName 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 Get-Command cmdlet retorna.

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

Sintaxe

O atributo OutputType das 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 conjuntos de parâmetros diferentes retornam tipos diferentes.

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

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

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

Exemplo 1: Criar uma função que tenha o OutputType de String

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

  "Hello, $Name"
}

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

(Get-Command Send-Greeting).OutputType

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

Exemplo 2: Use o atributo OutputType para indicar tipos de saída dinâmicos

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

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

Exemplo 3: Mostra quando uma saída real difere do OutputType

O exemplo a seguir demonstra que o valor da propriedade de tipo de saída exibe o valor do atributo OutputType , mesmo quando ele é impreciso.

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

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

  $DateTime.ToShortTimeString()
}

O GetType() método confirma que a função retorna uma cadeia de caracteres.

(Get-Time -DateTime (Get-Date)).GetType().FullName

System.String

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

(Get-Command Get-Time).OutputType

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

Exemplo 4: Uma função que não deve ter saída

O exemplo a seguir mostra uma função personalizada que deve executar uma ação, mas não retornar nada.

function Invoke-Notepad
{
  [OutputType([System.Void])]
  Param ()
  & notepad.exe | Out-Null
}

Notas

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

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

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

Ou a sua versão mais curta.

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

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

Consulte também