about_Functions_Advanced_Methods
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
TEMA
about_Functions_Advanced_Methods
DESCRIPCIÓN BREVE
Describe cómo las funciones que especifican el atributo CmdletBinding pueden usar los métodos y las propiedades que están disponibles para cmdlets compilados.
DESCRIPCIÓN LARGA
Las funciones que especifican el atributo CmdletBinding pueden acceder a una serie de métodos y propiedades a través de la variable $pscmdlet. Estos métodos son entre otros:
- Los métodos de procesamiento de entrada que usan los cmdlets compilados para hacer su trabajo.
- Los métodos ShouldProcess y ShouldContinue que se usan para obtener comentarios de los usuarios antes de realizar una acción.
- El método ThrowTerminatingError para generar registros de error.
- Varios métodos Write que devuelven diferentes tipos de salida.
Todos los métodos y las propiedades de la clase PSCmdlet están disponibles para las funciones avanzadas. Para más información sobre estos métodos y propiedades, consulte System.Management.Automation.PSCmdlet en MSDN (Microsoft Developer Network) Library, en https://go.microsoft.com/fwlink/?LinkId=142139.
MÉTODOS DE PROCESAMIENTO DE ENTRADA
Los métodos descritos en esta sección se conocen como métodos de procesamiento de entrada. Para las funciones, estos tres métodos están representados por los bloques Begin, Process y End de la función. Cada función debe incluir al menos uno de estos bloques. El tiempo de ejecución de Windows PowerShell® usa el código que contienen estos bloques cuando ejecuta una función. (Estos bloques también están disponibles para las funciones que no usan el atributo CmdletBinding).
Begin
Este bloque se usa para proporcionar el preprocesamiento único opcional para la función. El tiempo de ejecución de Windows PowerShell usa el código de este bloque una vez por cada instancia de la función en la canalización.
Process
Este bloque se usa para proporcionar el procesamiento registro por registro para la función. Este bloque se puede usar un número ilimitado de veces o ninguna, dependiendo de la entrada a la función. Por ejemplo, si la función es el primer comando en la canalización, el bloque Process se usará una vez. Si la función no es el primer comando en la canalización, el bloque Process se usará una vez por cada entrada que reciba la función de la canalización. Si no hay ninguna entrada de la canalización, el bloque Process no se usa.
Este bloque debe definirse si un parámetro de función está configurado para aceptar la entrada de la canalización. Si no se define este bloque y el parámetro acepta la entrada de la canalización, la función perderá los valores que se pasan a la función a través de la canalización.
Además, si la función acepta solicitudes de confirmación (cuando el parámetro SupportsShouldProcess del atributo Parameter se establece en $True), la llamada al método ShouldProcess debe realizarse desde el bloque Process.
End
Este bloque se utiliza para proporcionar el procesamiento posterior de un solo uso opcional para la función.
En el ejemplo siguiente se muestra el esquema de una función que contiene un bloque Begin para el preprocesamiento único, un bloque Process para el procesamiento de varios registros y un bloque End para el procesamiento posterior único.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
MÉTODOS DE CONFIRMACIÓN
ShouldProcess
Se llama a este método para solicitar confirmación al usuario antes de que la función realice una acción que provocará cambios en el sistema. La función puede continuar en función del valor booleano que devuelva el método. Solo se puede llamar a este método desde el bloque Process{} de la función. Además, el atributo CmdletBinding debe declarar que la función admite ShouldProcess (como se muestra en el ejemplo anterior).
Para más información sobre este método, consulte System.Management.Automation.Cmdlet.ShouldProcess en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142142.
Para más información sobre cómo solicitar confirmación, consulte "Solicitar confirmación" en MSDN Library, en https://go.microsoft.com/fwlink/?LinkID=136658.
ShouldContinue
Se llama a este método para solicitar un segundo mensaje de confirmación. La llamada se realiza cuando el método ShouldProcess devuelve $true. Para más información sobre este método, consulte System.Management.Automation.Cmdlet.ShouldContinue en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142143.
MÉTODOS DE ERROR
Las funciones pueden llamar a dos métodos diferentes cuando se producen errores. Cuando se produce un error de no terminación, la función debe llamar al método WriteError, que se describe en la sección "Métodos de escritura". Cuando se produce un error de terminación y la función no puede continuar, debe llamar al método ThrowTerminatingError. También puede usar la instrucción Throw para errores de terminación y el cmdlet Write-Error para errores de no terminación.
Para más información, consulte System.Management.Automation.Cmdlet. ThrowTerminatingError en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142144 MSDN.
MÉTODOS DE ESCRITURA
Una función puede llamar a los métodos siguientes para devolver distintos tipos de salida. Tenga en cuenta que no toda la salida va al siguiente comando de la canalización. También puede usar los diferentes cmdlets Write, como Write-Error.
WriteCommandDetail
Para obtener información acerca del método WriteCommandDetails, consulte System.Management.Automation.Cmdlet.WriteCommandDetail en MSDN Library en https://go.microsoft.com/fwlink/?LinkId=142155.
WriteDebug
Para proporcionar información que se puede usar para solucionar problemas de una función, haga que la función llame al método WriteDebug. De este modo se muestran mensajes de depuración al usuario. Para más información, consulte System.Management.Automation.Cmdlet.WriteDebug en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142156.
WriteError
Las funciones deben llamar a este método cuando se producen errores de no terminación y la función está diseñada para continuar el procesamiento de registros. Para más información, consulte System.Management.Automation.Cmdlet.WriteError en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142157.
Nota:
Si se produce un error de terminación, la función debe llamar al método ThrowTerminatingError.
WriteObject
Este método permite a la función enviar un objeto al siguiente comando de la canalización. En la mayoría de los casos, este es el método que se usa cuando la función devuelve datos. Para más información, consulte System.Management.Automation.PSCmdlet.WriteObject en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142158.
WriteProgress
Para las funciones cuyas acciones tardan mucho tiempo en completarse, este método permite a la función llamar al método WriteProgress para que se muestre la información de progreso. Por ejemplo, puede mostrar el porcentaje completado. Para más información, consulte System.Management.Automation.PSCmdlet.WriteProgress en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142160.
WriteVerbose
Para proporcionar información detallada acerca de qué hace la función, haga que la función llame al método WriteVerbose para mostrar mensajes detallados al usuario. De forma predeterminada, no se muestran mensajes detallados. Para más información, consulte System.Management.Automation.PSCmdlet.WriteVerbose en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142162.
WriteWarning
Para proporcionar información acerca de las condiciones que pueden producir resultados inesperados, haga que la función llame al método WriteWarning para mostrar mensajes de advertencia al usuario. De forma predeterminada, se muestran mensajes de advertencia. Para más información, consulte System.Management.Automation.PSCmdlet.WriteWarning en MSDN Library, en https://go.microsoft.com/fwlink/?LinkId=142164.
Nota:
También puede mostrar mensajes de advertencia mediante la configuración de la variable WarningPreference o mediante las opciones de línea de comandos Verbose y Debug.
OTROS MÉTODOS Y PROPIEDADES
Para obtener información acerca de los demás métodos y propiedades a los que se puede acceder a través de la variable $PSCmdlet, consulte System.Management.Automation.PSCmdlet en MSDN Library en https://go.microsoft.com/fwlink/?LinkId=142139.
Por ejemplo, la propiedad ParameterSetName le permite ver qué conjunto de parámetros se está empleando. Los conjuntos de parámetros le permiten crear una función que realiza diferentes tareas según los parámetros que se especifican cuando se ejecuta la función.
VEA TAMBIÉN
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute