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  




Tabla de contenido