TEMA
about_Functions_Advanced_Methods
DESCRIPCIÓN BREVE
Describe cómo las funciones que especifican el atributo
CmdletBinding pueden utilizar los métodos y las propiedades que están
disponibles para los cmdlets compilados.
DESCRIPCIÓN DETALLADA
Las funciones que especifican el atributo CmdletBinding pueden
tener acceso a varios métodos y propiedades a través de la variable
$pscmdlet. Estos métodos incluyen los siguientes:
- Los métodos de procesamiento de la entrada que los cmdlets
compilados utilizan para hacer su trabajo.
- Los métodos ShouldContinue y ShouldProcess que se utilizan para
obtener interacción del usuario antes de realizar una acción.
- El método ThrowTerminatingError para generar los registros
de errores.
- Varios métodos Write que devuelven diversos tipos de salida.
- Varios métodos Write que devuelven diversos tipos de salida.
Todos los métodos y las propiedades de la clase PSCmdlet están
disponibles para las funciones avanzadas. Para obtener más
información sobre estos métodos y propiedades, vea
System.Management.Automation.PSCmdlet en MSDN Library, en
https://go.microsoft.com/fwlink/?LinkId=142139.
Métodos de procesamiento de la entrada
Los métodos descritos en esta sección se denominan métodos de
procesamiento de entrada. Para las funciones, estos tres métodos se
representan mediante los bloques Begin, Process y End de la función.
Cada función debe incluir uno o más de estos bloques. El motor de tiempo
de ejecución de Windows PowerShell utiliza el código contenido en
estos bloques cuando está ejecutando una función. (Estos bloques
también están disponibles para las funciones que no utilizan el
atributo CmdletBinding.)
Begin
Este bloque se utiliza para proporcionar el preprocesamiento único
opcional para la función. El motor de tiempo de ejecución de Windows
PowerShell utiliza el código de este bloque una sola vez para cada
instancia de la función que haya en la canalización.
Process
Este bloque se utiliza para proporcionar el procesamiento registro a
registro para la función. Este bloque se puede utilizar cualquier
número de veces o ninguna en absoluto, dependiendo de la entrada a la
función. Por ejemplo, si la función es el primer comando de la
canalización, el bloque Process se utilizará una vez. Si la función
no es el primer comando de la canalización, el bloque Process se
utilizará una vez por cada entrada que la función reciba de la
canalización. Si no hay ninguna entrada de la canalización, el bloque
Process no se utiliza.
Se debe definir este bloque si un parámetro de función se
establece para que acepte la entrada de la canalización. Si
este bloque no se define y el parámetro acepta la entrada de la
canalización, la función no utilizará los valores que le pasen a
través de la canalización.
Además, si la función admite las solicitudes de confirmación
(cuando el parámetro SupportsShouldProcess del atributo
Parameter está establecido en $True), la llamada al método
ShouldProcess se debe realizar desde dentro del bloque Process.
End
Este bloque se utiliza para proporcionar el postprocesamiento único
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 procesar varios registros y un bloque End
para el postprocesamiento ú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 la confirmación del
usuario antes de que la función realice una acción que va a
modificar el sistema. La función puede continuar dependiendo
del valor de tipo Boolean devuelto por el método. Solamente se puede
llamar a este método desde dentro del 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 obtener más información sobre este método, vea
System.Management.Automation.Cmdlet.ShouldProcess en MSDN Library, en
https://go.microsoft.com/fwlink/?LinkId=142142.
Para obtener más información sobre cómo solicitar la
confirmación, vea "Requesting Confirmation" 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. Se le debe llamar cuando el método ShouldProcess
devuelve $true. Para obtener más información sobre este método,
vea 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
produce un error. Si se produce un error que no es de 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 se puede utilizar la instrucción Throw
para los errores de terminación y el cmdlet Write-Error para los
errores que no son de terminación.
Para obtener más información, vea System.Management.Automation.Cmdlet.
ThrowTerminatingError en MSDN Library, en
https://go.microsoft.com/fwlink/?LinkId=142144.
Métodos de escritura
Una función puede llamar a los métodos siguientes para devolver
diversos tipos de salida. Tenga en cuenta que no toda la salida
va al comando siguiente de la canalización. También puede
utilizar los distintos cmdlets Write, como Write-Error.
WriteCommandDetail
Para obtener más información sobre el método WriteCommandDetails,
vea System.Management.Automation.Cmdlet.WriteCommandDetail en MSDN
Library, en https://go.microsoft.com/fwlink/?LinkId=142155.
WriteDebug
Para proporcionar información que se puede utilizar para solucionar
problemas de una función, la función debe llamar al método
WriteDebug. De este modo se muestran mensajes de depuración al
usuario. Para obtener más información, vea 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 produce
algún error que no es de terminación y la función se ha
diseñado para seguir procesando registros. Para obtener más
información, vea 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 que la función envíe un objeto al próximo
comando de la canalización. En la mayoría de los casos, este es
el método que debe utilizarse cuando la función devuelve datos. Para
obtener más información, vea 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 que la función llame al método
WriteProgress para que se muestre la información de progreso.
Por ejemplo, se puede mostrar el porcentaje completado. Para obtener más
información, vea System.Management.Automation.PSCmdlet.WriteProgress en MSDN
Library, en https://go.microsoft.com/fwlink/?LinkId=142160.
WriteVerbose
Para proporcionar información detallada sobre lo que la función está
haciendo, ésta debe llamar al método WriteVerbose a fin de mostrar
mensajes detallados al usuario. De forma predeterminada, no se
muestran mensajes detallados. Para obtener más información, vea System.
Management.Automation.PSCmdlet.WriteVerbose en MSDN Library,
en https://go.microsoft.com/fwlink/?LinkId=142162.
WriteWarning
Para proporcionar información sobre las condiciones que pueden
provocar resultados inesperados, la función debe llamar al método
WriteWarning, a fin de mostrar mensajes de advertencia al usuario.
De forma predeterminada, se muestran mensajes de advertencia.
Para obtener más información, vea System.Management.Automation.
PSCmdlet.WriteWarning en MSDN Library,
en https://go.microsoft.com/fwlink/?LinkId=142164.
Nota: también se pueden mostrar los mensajes de advertencia
configurando la variable WarningPreference o utilizando las opciones
Verbose y Debug de la línea de comandos.
Otros métodos y propiedades
Para obtener información sobre otros métodos y propiedades a
las que se puede tener acceso mediante la variable $PSCmdlet, vea
System.Management.Automation.PSCmdlet en MSDN Library, en
https://go.microsoft.com/fwlink/?LinkId=142139.
Por ejemplo, la propiedad ParameterSetName permite ver el
conjunto de parámetros que se está utilizando. Los conjuntos de
parámetros permiten crear una función que realiza distintas
tareas según los parámetros que se especifican al ejecutarla.
VEA TAMBIÉN
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters