about_Functions_OutputTypeAttribute
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.