about_Functions_CmdletBindingAttribute

Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

TEMA

about_Functions_CmdletBindingAttribute

DESCRIPCIÓN BREVE

Describe el atributo que hace que una función se comporte como un cmdlet compilado.

DESCRIPCIÓN LARGA

El atributo CmdletBinding es un atributo de funciones que las hace operar como cmdlets compilados escritos en C#, y proporciona acceso a características de los cmdlets.

Windows PowerShell® enlaza los parámetros de funciones que tienen el atributo CmdletBinding de la misma forma que enlaza los parámetros de los cmdlets compilados. La variable automática $PSCmdlet está disponible para las funciones con el atributo CmdletBinding, pero la variable $Args no está disponible.

En las funciones que tienen el atributo CmdletBinding, los parámetros desconocidos y los argumentos posicionales que carecen de parámetros posicionales coincidentes hacen que falle el enlace de parámetros.

Nota: Los cmdlets compilados usan el atributo Cmdlet necesario, que es similar al atributo CmdletBinding que se describe en este tema.

SINTAXIS

En el ejemplo siguiente se muestra el formato de una función que especifica todos los argumentos opcionales del atributo CmdletBinding. A continuación de este ejemplo se ofrece una breve descripción de cada argumento.

        {
          [CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

          Param ($Parameter1)
          Begin{}
          Process{}
          End{}
        }

ConfirmImpact

El argumento ConfirmImpact especifica cuándo se debe confirmar la acción de la función mediante una llamada al método ShouldProcess. La llamada al método ShouldProcess muestra un mensaje de confirmación solo cuando el argumento ConfirmImpact es igual o mayor que el valor de la variable de preferencia $ConfirmPreference. (El valor predeterminado del argumento es Medium). Especifique este argumento solo si también especifica el argumento SupportsShouldProcess.

Para más información sobre las solicitudes de confirmación, consulte "Requesting Confirmation" en MSDN (Microsoft Developer Network) Library, en https://go.microsoft.com/fwlink/?LinkId=136658.

DefaultParameterSetName

El argumento DefaultParameterSetName especifica el nombre del conjunto de parámetros que Windows PowerShell tratará de usar si no puede determinar qué conjunto de parámetros usar. Puede evitar este problema haciendo que el único parámetro de cada conjunto de parámetros sea un parámetro obligatorio.

HelpURI

El argumento HelpURI especifica la dirección de Internet (identificador uniforme de recursos [URI]) de la versión en línea del tema de ayuda que describe la función. El valor del argumento HelpURI debe empezar por "http" o "https".

El valor del argumento HelpURI se usa para el valor de la propiedad HelpURI del objeto CommandInfo devuelto por Get-Command para la función.

Sin embargo, cuando se instalan los archivos de ayuda en el equipo y el valor del primer vínculo en la sección RelatedLinks del archivo de ayuda es un URI o el valor de la primera directiva .Link en la ayuda basada en comentarios es un URI, el URI del archivo de ayuda se usa como el valor de la propiedad HelpUri de la función.

El cmdlet Get-Help usa el valor de la propiedad HelpURI para buscar la versión en línea del tema de ayuda de la función cuando se especifica el parámetro Online de Get-Help en un comando.

SupportsPaging

El argumento SupportsPaging agrega los parámetros First, Skip e IncludeTotalCount a la función. Estos parámetros permiten a los usuarios seleccionar la salida de un conjunto de resultados muy grande. Este argumento está diseñado para cmdlets y funciones que devuelven datos de almacenes de datos de gran tamaño que admiten la selección de datos, como una base de datos SQL.

Este argumento se introdujo en Windows PowerShell 3.0.

En primer lugar:

Obtiene solo los primeros "n" objetos.

Omitir:

Ignora los primeros "n" objetos y, a continuación, obtiene los objetos restantes.

IncludeTotalCount:

Informa del número de objetos del conjunto de datos (un entero) seguido de los objetos. Si el cmdlet no puede determinar el recuento total, devuelve "Recuento total desconocido".

Windows PowerShell incluye NewTotalCount, un método auxiliar que obtiene el valor de recuento total que se debe devolver e incluye una estimación de la precisión del valor de recuento total.

La función de ejemplo siguiente muestra cómo agregar compatibilidad para los parámetros de paginación a una función avanzada.

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             param()

             $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
             $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First + $FirstNumber - 1, 100)

             if ($PSCmdlet.PagingParameters.IncludeTotalCount)
             {
                 $TotalCountAccuracy = 1.0
                 $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100, $TotalCountAccuracy)
                 Write-Output $TotalCount
             }
             $FirstNumber .. $LastNumber | Write-Output
         }

SupportsShouldProcess

El argumento SupportsShouldProcess agrega los parámetros Confirm y WhatIf a la función. El parámetro Confirm solicita confirmación al usuario antes de ejecutar el comando en cada objeto de la canalización. El parámetro WhatIf enumera los cambios que hará el comando, en lugar de ejecutar el comando.

PositionalBinding

El argumento PositionalBinding determina si los parámetros de la función son posicionales de forma predeterminada. El valor predeterminado es $True. Puede usar el argumento PositionalBinding con un valor $False para deshabilitar el enlace posicional.

El argumento PositionalBinding se introdujo en Windows PowerShell3.0.

Si los parámetros posicionales, el nombre del parámetro es opcional. Windows PowerShell asocia valores de parámetros sin nombre con los parámetros de la función según el orden o la posición de los valores de parámetro sin nombre en el comando de la función.

Si los parámetros no son posicionales (son parámetros "con nombre"), se requiere en el comando el nombre del parámetro (o una abreviatura o alias del nombre).

Si PositionalBinding es $True, los parámetros de la función son posicionales de forma predeterminada. Windows PowerShell asigna un número de posición a los parámetros en el orden en que se declaran en la función.

Si PositionalBinding es $False, los parámetros de la función no son posicionales de forma predeterminada. A menos que el argumento Position del atributo Parameter se declare en el parámetro, el nombre del parámetro (o un alias o abreviatura) debe incluirse cuando se use el parámetro en una función.

El argumento Position del atributo Parameter tiene prioridad sobre el valor predeterminado de PositionalBinding. Puede usar el argumento Position para especificar un valor de posición para un parámetro. Para más información sobre el argumento Position, consulte about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).

NOTAS

El argumento SupportsTransactions no se admite en funciones avanzadas.

PALABRAS CLAVE

about_Functions_CmdletBinding_Attribute

VEA TAMBIÉN

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute