about_Functions_OutputTypeAttribute

Descripción breve

Describe un atributo que informa del 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 sencillas y avanzadas. Es independiente del atributo cmdletbinding de. El atributo outputType proporciona el valor de la propiedad OutputType del objeto System.Management.Automation.FunctionInfo que devuelve el cmdlet Get-Command.

Nota:

El valor del atributo OutputType 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.

El atributo OutputType también informa a los resultados de finalización de tabulación para situaciones como: Command | Select <Tab> y Command | Where <Tab>.

Syntax

El atributo outputType de 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 los distintos conjuntos de parámetros devuelven tipos diferentes.

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

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

En el ejemplo siguiente se muestra la ubicación del atributo OutputType 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 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>
}

Examples

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 cmdlet Get-Command.

(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 diferentes 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 función Get-Time 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 método GetType() 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 cada uno tiene 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 función no escriba ninguna salida en la secuencia Success . Si la función escribe la salida, pero no conoce el tipo, use System.Object.

Consulte también

  • Last updated on