about_Functions_CmdletBindingAttribute
Descripción breve
Describe el atributo que hace que una función funcione como un cmdlet compilado.
Descripción larga
El CmdletBinding atributo es un atributo de funciones que hace que funcionen como cmdlets compilados escritos en C#. Proporciona acceso a las características de los cmdlets.
Cuando se usa el CmdletBinding atributo , PowerShell agrega automáticamente los parámetros comunes. No se pueden crear parámetros que usen los mismos nombres que los parámetros comunes. Para obtener más información, consulta about_CommonParameters.
PowerShell enlaza los parámetros de las funciones que tienen el CmdletBinding atributo de la misma manera que enlaza los parámetros de los cmdlets compilados. La $PSCmdlet variable automática está disponible para las funciones con el CmdletBinding atributo , pero la $Args variable no está disponible.
En las funciones que tienen el CmdletBinding atributo , los parámetros desconocidos y los argumentos posicionales que no tienen parámetros posicionales coincidentes hacen que se produzca un error en el enlace de parámetros.
Nota:
Los cmdlets compilados usan el atributo necesario Cmdlet , que es similar al CmdletBinding atributo 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 CmdletBinding atributo. Una breve descripción de cada argumento sigue este ejemplo.
{
[CmdletBinding(ConfirmImpact=<String>,
DefaultParameterSetName=<String>,
HelpURI=<URI>,
SupportsPaging=<Boolean>,
SupportsShouldProcess=<Boolean>,
PositionalBinding=<Boolean>)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Los tipos de argumento booleano del atributo CmdletBinding son False cuando se omiten del atributo CmdletBinding . Establezca el valor $true del argumento en o simplemente enumere el argumento por nombre. Por ejemplo, los siguientes atributos CmdletBinding son equivalentes.
{
[CmdletBinding(SupportsPaging=$true)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
# Boolean arguments can be defined using this shorthand syntax
{
[CmdletBinding(SupportsPaging)]
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 $ConfirmPreference variable de preferencia. (El valor predeterminado del argumento es Medium.) Especifique este argumento solo cuando también se especifique el argumento SupportsShouldProcess .
Para obtener más información sobre las solicitudes de confirmación, vea Solicitar confirmación.
DefaultParameterSetName
El argumento DefaultParameterSetName especifica el nombre del conjunto de parámetros que PowerShell intentará usar cuando no pueda determinar qué parámetro se va a usar. Puede evitar este problema haciendo que el parámetro único de cada parámetro establezca un parámetro obligatorio.
HelpURI
El argumento HelpURI especifica la dirección de Internet de la versión en línea del tema de ayuda que describe la función. El valor del argumento HelpURI debe comenzar por "http" o "https".
El valor del argumento HelpURI se usa para el valor de la propiedad HelpURI del objeto CommandInfo que Get-Command devuelve para la función.
Sin embargo, cuando los archivos de ayuda se instalan en el equipo y el valor del primer vínculo de la sección RelatedLinks del archivo de ayuda es un URI o el valor de la primera .Link directiva de la ayuda basada en comentarios es un URI, el URI del archivo de ayuda se usa como valor de la propiedad HelpUri de la función.
El Get-Help cmdlet 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 grandes que admiten la selección de datos, como una base de datos SQL.
Este argumento se introdujo en Windows PowerShell 3.0.
- Primero: obtiene solo los primeros objetos 'n'.
- Omitir: omite los primeros objetos 'n' 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".
PowerShell incluye NewTotalCount, un método auxiliar que obtiene el valor de recuento total que se va a devolver e incluye una estimación de la precisión del valor de recuento total.
La siguiente función de ejemplo muestra cómo agregar compatibilidad con los parámetros de paginación a una función avanzada.
function Get-Numbers {
[CmdletBinding(SupportsPaging)]
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 parámetros Confirm y WhatIf a la función . El parámetro Confirm solicita al usuario antes de ejecutar el comando en cada objeto de la canalización. El parámetro WhatIf enumera los cambios que realizaría 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 de $False para deshabilitar el enlace posicional.
El argumento PositionalBinding se presenta en Windows PowerShell 3.0.
Cuando los parámetros son posicionales, el nombre del parámetro es opcional. PowerShell asocia valores de parámetro sin nombre a los parámetros de función según el orden o la posición de los valores de parámetro sin nombre en el comando de función.
Cuando los parámetros no son posicionales (se denominan), el nombre del parámetro (o una abreviatura o alias del nombre) es necesario en el comando .
Cuando PositionalBinding es $True, los parámetros de función son posicionales de forma predeterminada. PowerShell asigna el número de posición a los parámetros en el orden en que se declaran en la función.
Cuando PositionalBinding es $False, los parámetros de 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 una abreviatura) debe incluirse cuando se usa el parámetro en una función.
El argumento Position del atributo Parameter tiene prioridad sobre el valor predeterminado PositionalBinding . Puede usar el argumento Position para especificar un valor de posición para un parámetro. Para obtener más información sobre el argumento Position , vea about_Functions_Advanced_Parameters.
Notas
El argumento SupportsTransactions no se admite en funciones avanzadas .
Palabras clave
about_Functions_CmdletBinding_Attribute
