about_Functions_OutputTypeAttribute

  • Artículo

Se aplica a: Windows PowerShell 3.0

TEMA

about_Functions_OutputTypeAttribute

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 .NET de los objetos devueltos por las funciones. Puede usar su parámetro opcional ParameterSetName par enumerar los diferentes tipos de salida de cada conjunto de parámetros.

El atributo OutputType es compatible con las 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 devuelto por el cmdlet Get-Command.

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

SINTAXIS

El atributo OutputType de las funciones tiene la siguiente sintaxis:

        [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 diferentes conjuntos de parámetros devuelven tipos diferentes.

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

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

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

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

            <function body>
        }

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

La función siguiente usa el atributo OutputType para indicar que devuelve un valor de cadena.

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

          Hello, $Name      
        }

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

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

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

La siguiente función avanzada usa el atributo OutputType para indicar que la función devuelve distintos tipos según el conjunto de parámetros que se usa 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>
       }

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

La función Get-Time devuelve una cadena que contiene la forma abreviada del tiempo 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 Get-Type confirma que la función devuelve una cadena.

        PS C:\> (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.

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

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

NOTAS

El valor de la propiedad OutputType de un objeto FunctionInfo es una matriz de objetos System.Management.Automation.PSTypeName, cada uno de los cuales 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-Time).OutputType | ForEach {$_.Name}

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

VEA TAMBIÉN

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute