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