Compartir a través de

about_Functions_Advanced_Methods

Descripción breve

Describe cómo las funciones que especifican el atributo CmdletBinding pueden usar los métodos y propiedades que están disponibles para los cmdlets compilados.

Descripción larga

Las funciones que especifican el atributo CmdletBinding pueden tener acceso a métodos y propiedades adicionales a través de la variable $PSCmdlet. Estos métodos incluyen los métodos siguientes:

  • Los mismos métodos de procesamiento de entrada disponibles para todas las funciones.
  • Los métodos ShouldProcess y ShouldContinue que se usan para obtener comentarios de los usuarios antes de realizar una acción.
  • Método ThrowTerminatingError para generar registros de error.
  • Varios métodos Write que devuelven diferentes tipos de salida.

Todos los métodos y propiedades de la clase PSCmdlet de están disponibles para funciones avanzadas. Para obtener más información, vea System.Management.Automation.PSCmdlet.

Para obtener más información sobre el atributo CmdletBinding, vea about_Functions_CmdletBindingAttribute. Para obtener la clase cmdletBindingAttribute de, consulte System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Métodos de procesamiento de entrada

Los métodos descritos en esta sección se conocen como métodos de procesamiento de entrada. En el caso de las funciones, estos tres métodos se representan mediante los bloques begin, processy end de la función. PowerShell 7.3 agrega un método de proceso de bloque clean.

No es necesario usar ninguno de estos bloques en las funciones. Si no usa un bloque con nombre, PowerShell coloca el código en el bloque end de la función. Sin embargo, si usa cualquiera de estos bloques con nombre o define un bloque dynamicparam, debe colocar todo el código en un bloque con nombre.

En el ejemplo siguiente se muestra el esquema de una función que contiene un bloque de begin para el preprocesamiento único, un bloque de process para varios procesamientos de registros y un bloque de end para el procesamiento posterior de un solo uso.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Nota

Estos bloques se aplican a todas las funciones, no solo a las funciones que usan el atributo CmdletBinding.

begin

Este bloque se usa para proporcionar preprocesamiento opcional de un solo uso para la función. El tiempo de ejecución de PowerShell usa el código de este bloque una vez para cada instancia de la función de la canalización.

process

Este bloque se usa para proporcionar procesamiento de registros por registro para la función. Puede usar un bloque process sin definir los demás bloques. El número de ejecuciones de bloques de process depende de cómo use la función y de qué entrada recibe la función.

La variable automática $_ o $PSItem contiene el objeto actual de la canalización para su uso en el bloque process. La $input variable automática contiene un enumerador que solo está disponible para funciones y bloques de scripts. Para obtener más información, vea about_Automatic_Variables.

  • Al llamar a la función al principio o fuera de una canalización, se ejecuta el bloque process una vez.
  • Dentro de una canalización, el bloque process se ejecuta una vez para cada objeto de entrada que alcanza la función.
  • Si la entrada de canalización que alcanza la función está vacía, el bloque processno ejecutar.
    • Los bloques begin, endy clean se siguen ejecutando.

Importante

Si se establece un parámetro de función para aceptar la entrada de canalización y no se define un bloque de process, se producirá un error en el procesamiento de registros por registro. En este caso, la función solo se ejecutará una vez, independientemente de la entrada.

Al crear una función que acepte la entrada de canalización y use CmdletBinding, el bloque process debe usar la variable de parámetro que definió para la entrada de canalización en lugar de $_ o $PSItem. Por ejemplo:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

Este bloque se usa para proporcionar el procesamiento posterior opcional de una sola vez para la función.

clean

El bloque clean se agregó en PowerShell 7.3.

El bloque clean es una manera cómoda de limpiar los recursos que abarcan los bloques begin, processy end. Es semánticamente similar a un bloque de finally que cubre todos los demás bloques con nombre de una función de script o un cmdlet de script. La limpieza de recursos se aplica para los siguientes escenarios:

  1. cuando la ejecución de la canalización finaliza normalmente sin errores de terminación
  2. cuando se interrumpe la ejecución de la canalización debido a un error de terminación
  3. cuando la canalización se detiene Select-Object -First
  4. cuando se detiene la canalización ctrl+c o StopProcessing()

El bloque limpio descarta cualquier salida escrita en el flujo de Correcto.

Cautela

Agregar el bloque clean es un cambio importante. Dado clean que se analiza como palabra clave, impide que los usuarios llamen directamente a un comando denominado clean como la primera instrucción de un scriptblock. Sin embargo, es probable que no sea un problema. El comando todavía se puede invocar mediante el operador de llamada (& clean).

Métodos de confirmación

ShouldProcess

Se llama a este método para solicitar confirmación del usuario antes de que la función realice una acción que cambiaría el sistema. La función puede continuar en función del valor booleano devuelto por el método . Solo se puede llamar a este método desde dentro del bloque process {} de la función. El atributo CmdletBinding también 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.

Para obtener más información sobre cómo solicitar confirmación, vea Solicitud de confirmación.

ShouldContinue

Se llama a este método para solicitar un segundo mensaje de confirmación. Se 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.

Métodos de error

Functions puede 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 Write. 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 terminar los errores y el cmdlet write-Error para errores de no terminación.

Para obtener más información, vea System.Management.Automation.Cmdlet.ThrowTerminatingError.

Métodos de escritura

Una función puede llamar a los métodos siguientes para devolver diferentes tipos de salida. Observe que no toda la salida va al siguiente comando de la canalización. También puede usar los distintos cmdlets de Write, como Write-Error.

WriteCommandDetail

Para obtener información sobre el método WriteCommandDetails, vea System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Para proporcionar información que se puede usar para solucionar problemas de una función, realice la llamada a la función al método WriteDebug. El método WriteDebug muestra los mensajes de depuración al usuario. Para obtener más información, vea System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Functions debe llamar a este método cuando se producen errores de no terminación y la función está diseñada para continuar procesando registros. Para obtener más información, vea System.Management.Automation.Cmdlet.WriteError.

Nota

Si se produce un error de terminación, la función debe llamar al método ThrowTerminatingError.

WriteObject

El método WriteObject permite que la función envíe un objeto al siguiente comando de la canalización. En la mayoría de los casos, WriteObject es el método que se usará cuando la función devuelve datos. Para obtener más información, vea System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Para las funciones con acciones que 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, puede mostrar el porcentaje completado. Para obtener más información, vea System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Para proporcionar información detallada sobre lo que 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 los mensajes detallados. Para obtener más información, vea System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Para proporcionar información sobre las condiciones que pueden provocar resultados inesperados, haga que la función llame al método WriteWarning para mostrar mensajes de advertencia al usuario. De forma predeterminada, se muestran los mensajes de advertencia. Para obtener más información, vea System.Management.Automation.PSCmdlet.WriteWarning.

Nota

También puede mostrar mensajes de advertencia configurando la variable $WarningPreference o usando las opciones de línea de comandos Verbose y Debug. para obtener más información sobre la variable $WarningPreference, vea about_Preference_Variables.

Otros métodos y propiedades

Para obtener información sobre los otros métodos y propiedades a los que se puede acceder a través de la variable $PSCmdlet, consulte System.Management.Automation.PSCmdlet.

Por ejemplo, la propiedad ParameterSetName permite ver el conjunto de parámetros que se usa. Los conjuntos de parámetros permiten crear una función que realice diferentes tareas en función de los parámetros especificados cuando se ejecuta la función.

Consulte también

  • Last updated on