about_Functions_OutputTypeAttribute

  • Artículo

Descripción breve

Describe un atributo que indica el tipo de objeto que devuelve la función.

Descripción larga

El atributo OutputType enumera los tipos de objetos de .NET que devuelven las funciones. Puede usar su parámetro ParameterSetName opcional para enumerar diferentes tipos de salida para cada conjunto de parámetros.

El atributo OutputType se admite en funciones simples y avanzadas. Es independiente del atributo CmdletBinding .

El atributo OutputType proporciona el valor de la propiedad OutputType del objeto System.Management.Automation.FunctionInfo que devuelve el Get-Command cmdlet.

El valor del atributo OutputType solo es una nota de la documentación. No se deriva del código de función ni se compara con la salida de la función real. Por lo tanto, el valor puede ser inexacto.

Sintaxis

El atributo OutputType de las funciones tiene la sintaxis siguiente:

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

El parámetro ParameterSetName es opcional.

Puede enumerar varios tipos en el atributo OutputType .

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

Puede usar el parámetro ParameterSetName para indicar que distintos conjuntos de parámetros devuelven diferentes tipos.

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

Coloque las instrucciones de atributo OutputType en la lista de atributos que precede a la Param instrucción .

En el ejemplo siguiente se muestra la ubicación del atributo OutputType en una función simple.

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

  <function body>
}

En el ejemplo siguiente se muestra la ubicación del atributo OutputType en funciones avanzadas.

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

Ejemplos

Ejemplo 1: Creación de una función con outputType de cadena

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

  "Hello, $Name"
}

Para ver la propiedad de tipo de salida resultante, use el Get-Command cmdlet .

(Get-Command Send-Greeting).OutputType

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

Ejemplo 2: Usar el atributo OutputType para indicar tipos de salida dinámicos

La siguiente función avanzada usa el atributo OutputType para indicar que la función devuelve distintos tipos en función del conjunto de parámetros usado en el comando de función.

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

Ejemplo 3: muestra cuándo una salida real difiere de OutputType

En el ejemplo siguiente se muestra que el valor de la propiedad de tipo de salida muestra el valor del atributo OutputType , incluso cuando es inexacto.

La Get-Time función devuelve una cadena que contiene la forma corta de la hora en cualquier objeto DateTime . Sin embargo, el atributo OutputType informa de que devuelve un objeto System.DateTime .

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

  $DateTime.ToShortTimeString()
}

El GetType() método confirma que la función devuelve una cadena.

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

System.String

Sin embargo, la propiedad OutputType , que obtiene su valor del atributo OutputType , informa de que la función devuelve un objeto DateTime .

(Get-Command Get-Time).OutputType

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

Ejemplo 4: función que no debe tener salida

En el ejemplo siguiente se muestra una función personalizada que debe realizar una acción, pero no devolver nada.

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

Notas

El valor de la propiedad OutputType de un objeto FunctionInfo es una matriz de objetos System.Management.Automation.PSTypeName , que tienen propiedades Name y Type .

Para obtener solo el nombre de cada tipo de salida, use un comando con el formato siguiente.

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

O su versión más corta.

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

El valor de la propiedad OutputType puede ser NULL. Use un valor NULL cuando la salida no sea un tipo de .NET, como un objeto WMI o una vista con formato de un objeto.

Consulte también