TEMA

about_Functions_Advanced_Methods
DESCRIPCIN BREVE
Describe cmo las funciones que especifican el atributo
CmdletBinding pueden utilizar los mtodos y las propiedades que estn
disponibles para los cmdlets compilados.
DESCRIPCIN DETALLADA
Las funciones que especifican el atributo CmdletBinding pueden
tener acceso a varios mtodos y propiedades a travs de la variable
$pscmdlet. Estos mtodos incluyen los siguientes:
- Los mtodos de procesamiento de la entrada que los cmdlets
compilados utilizan para hacer su trabajo.
- Los mtodos ShouldContinue y ShouldProcess que se utilizan para
obtener interaccin del usuario antes de realizar una accin.
- El mtodo ThrowTerminatingError para generar los registros
de errores.
- Varios mtodos Write que devuelven diversos tipos de salida.
- Varios mtodos Write que devuelven diversos tipos de salida.
Todos los mtodos y las propiedades de la clase PSCmdlet estn
disponibles para las funciones avanzadas. Para obtener ms
informacin sobre estos mtodos y propiedades, vea
System.Management.Automation.PSCmdlet en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkId=142139.
Mtodos de procesamiento de la entrada
Los mtodos descritos en esta seccin se denominan mtodos de
procesamiento de entrada. Para las funciones, estos tres mtodos se
representan mediante los bloques Begin, Process y End de la funcin.
Cada funcin debe incluir uno o ms de estos bloques. El motor de tiempo
de ejecucin de Windows PowerShell utiliza el cdigo contenido en
estos bloques cuando est ejecutando una funcin. (Estos bloques
tambin estn disponibles para las funciones que no utilizan el
atributo CmdletBinding.)

Begin
Este bloque se utiliza para proporcionar el preprocesamiento nico
opcional para la funcin. El motor de tiempo de ejecucin de Windows
PowerShell utiliza el cdigo de este bloque una sola vez para cada
instancia de la funcin que haya en la canalizacin.
Process
Este bloque se utiliza para proporcionar el procesamiento registro a
registro para la funcin. Este bloque se puede utilizar cualquier
nmero de veces o ninguna en absoluto, dependiendo de la entrada a la
funcin. Por ejemplo, si la funcin es el primer comando de la
canalizacin, el bloque Process se utilizar una vez. Si la funcin
no es el primer comando de la canalizacin, el bloque Process se
utilizar una vez por cada entrada que la funcin reciba de la
canalizacin. Si no hay ninguna entrada de la canalizacin, el bloque
Process no se utiliza.
Se debe definir este bloque si un parmetro de funcin se
establece para que acepte la entrada de la canalizacin. Si
este bloque no se define y el parmetro acepta la entrada de la
canalizacin, la funcin no utilizar los valores que le pasen a
travs de la canalizacin.
Adems, si la funcin admite las solicitudes de confirmacin
(cuando el parmetro SupportsShouldProcess del atributo
Parameter est establecido en $True), la llamada al mtodo
ShouldProcess se debe realizar desde dentro del bloque Process.
End
Este bloque se utiliza para proporcionar el postprocesamiento nico
opcional para la funcin.
En el ejemplo siguiente se muestra el esquema de una funcin
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{}
}
Mtodos de confirmacin
ShouldProcess
Se llama a este mtodo para solicitar la confirmacin del
usuario antes de que la funcin realice una accin que va a
modificar el sistema. La funcin puede continuar dependiendo
del valor de tipo Boolean devuelto por el mtodo. Solamente se puede
llamar a este mtodo desde dentro del bloque Process{} de la funcin.
Adems, el atributo CmdletBinding debe declarar que la funcin admite
ShouldProcess (como se muestra en el ejemplo anterior).
Para obtener ms informacin sobre este mtodo, vea
System.Management.Automation.Cmdlet.ShouldProcess en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkId=142142.
Para obtener ms informacin sobre cmo solicitar la
confirmacin, vea "Requesting Confirmation" en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkID=136658.
ShouldContinue
Se llama a este mtodo para solicitar un segundo mensaje de
confirmacin. Se le debe llamar cuando el mtodo ShouldProcess
devuelve $true. Para obtener ms informacin sobre este mtodo,
vea System.Management.Automation.Cmdlet.ShouldContinue en MSDN
Library, en http://go.microsoft.com/fwlink/?LinkId=142143.
Mtodos de error
Las funciones pueden llamar a dos mtodos diferentes cuando se
produce un error. Si se produce un error que no es de terminacin,
la funcin debe llamar al mtodo WriteError, que se describe en la
seccin "Mtodos de escritura". Cuando se produce un error de
terminacin y la funcin no puede continuar, debe llamar al mtodo
ThrowTerminatingError. Tambin se puede utilizar la instruccin Throw
para los errores de terminacin y el cmdlet Write-Error para los
errores que no son de terminacin.
Para obtener ms informacin, vea System.Management.Automation.Cmdlet.
ThrowTerminatingError en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkId=142144.
Mtodos de escritura
Una funcin puede llamar a los mtodos siguientes para devolver
diversos tipos de salida. Tenga en cuenta que no toda la salida
va al comando siguiente de la canalizacin. Tambin puede
utilizar los distintos cmdlets Write, como Write-Error.
WriteCommandDetail
Para obtener ms informacin sobre el mtodo WriteCommandDetails,
vea System.Management.Automation.Cmdlet.WriteCommandDetail en MSDN
Library, en http://go.microsoft.com/fwlink/?LinkId=142155.
WriteDebug
Para proporcionar informacin que se puede utilizar para solucionar
problemas de una funcin, la funcin debe llamar al mtodo
WriteDebug. De este modo se muestran mensajes de depuracin al
usuario. Para obtener ms informacin, vea System.Management.
Automation.Cmdlet.WriteDebug en MSDN Library,
en http://go.microsoft.com/fwlink/?LinkId=142156.
WriteError
Las funciones deben llamar a este mtodo cuando se produce
algn error que no es de terminacin y la funcin se ha
diseado para seguir procesando registros. Para obtener ms
informacin, vea System.Management.Automation.Cmdlet.WriteError
en MSDN Library, en http://go.microsoft.com/fwlink/?LinkId=142157.
Nota: si se produce un error de terminacin, la funcin debe
llamar al mtodo ThrowTerminatingError.
WriteObject
Este mtodo permite que la funcin enve un objeto al prximo
comando de la canalizacin. En la mayora de los casos, este es
el mtodo que debe utilizarse cuando la funcin devuelve datos. Para
obtener ms informacin, vea System.Management.Automation.PSCmdlet.
WriteObject en MSDN Library, en http://go.microsoft.com/fwlink/?LinkId=142
158.
WriteProgress
Para las funciones cuyas acciones tardan mucho tiempo en
completarse, este mtodo permite que la funcin llame al mtodo
WriteProgress para que se muestre la informacin de progreso.
Por ejemplo, se puede mostrar el porcentaje completado. Para obtener ms
informacin, vea System.Management.Automation.PSCmdlet.WriteProgress en MSDN

Library, en http://go.microsoft.com/fwlink/?LinkId=142160.
WriteVerbose
Para proporcionar informacin detallada sobre lo que la funcin est
haciendo, sta debe llamar al mtodo WriteVerbose a fin de mostrar
mensajes detallados al usuario. De forma predeterminada, no se
muestran mensajes detallados. Para obtener ms informacin, vea System.
Management.Automation.PSCmdlet.WriteVerbose en MSDN Library,
en http://go.microsoft.com/fwlink/?LinkId=142162.
WriteWarning
Para proporcionar informacin sobre las condiciones que pueden
provocar resultados inesperados, la funcin debe llamar al mtodo
WriteWarning, a fin de mostrar mensajes de advertencia al usuario.
De forma predeterminada, se muestran mensajes de advertencia.
Para obtener ms informacin, vea System.Management.Automation.
PSCmdlet.WriteWarning en MSDN Library,
en http://go.microsoft.com/fwlink/?LinkId=142164.
Nota: tambin se pueden mostrar los mensajes de advertencia
configurando la variable WarningPreference o utilizando las opciones
Verbose y Debug de la lnea de comandos.
Otros mtodos y propiedades
Para obtener informacin sobre otros mtodos y propiedades a
las que se puede tener acceso mediante la variable $PSCmdlet, vea
System.Management.Automation.PSCmdlet en MSDN Library, en
http://go.microsoft.com/fwlink/?LinkId=142139.
Por ejemplo, la propiedad ParameterSetName permite ver el
conjunto de parmetros que se est utilizando. Los conjuntos de
parmetros permiten crear una funcin que realiza distintas
tareas segn los parmetros que se especifican al ejecutarla.
VEA TAMBIN
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters