about_Functions_Advanced_Methods

  • Artículo

Descripción breve

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

Descripción larga

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

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

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

Para obtener más información sobre el CmdletBinding atributo, consulte about_Functions_CmdletBindingAttribute. Para la clase CmdletBindingAttribute , 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 beginbloques , processy end de la función . PowerShell 7.3 agrega un clean método de proceso de bloque.

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 end bloque de la función. Sin embargo, si usa cualquiera de estos bloques con nombre o define un dynamicparam bloque, 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 para el preprocesamiento único, un process bloque para el procesamiento de varios registros y un end bloque para el procesamiento posterior de un begin solo uso.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Nota:

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

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 process bloque sin definir los demás bloques. El número de ejecuciones de process bloques 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 process bloque . La $input variable automática contiene un enumerador que solo está disponible para funciones y bloques de script. 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 process bloque una vez.
  • Dentro de una canalización, el process bloque se ejecuta una vez para cada objeto de entrada que alcanza la función.
  • Si la entrada de canalización que llega a la función está vacía, el process bloque no se ejecuta.
    • Los beginbloques , 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 process bloque, 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 process bloque 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 clean bloque se agregó en PowerShell 7.3.

El bloque clean es una manera cómoda para que los usuarios limpien los recursos que abarcan los bloques begin, process y end. Es semánticamente similar a un bloque 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 en los escenarios siguientes:

  1. cuando la ejecución de la canalización finaliza normalmente sin error 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 está detenida por Select-Object -First
  4. cuando la canalización está detenida por Ctrl+c o StopProcessing()

Precaución

Agregar el bloque clean es un cambio importante. Dado que clean se analiza como una palabra clave, impide que los usuarios llamen directamente a un comando denominado clean como la primera instrucción de un bloque de script. 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 . Este método solo se puede llamar desde dentro del Process{} bloque de la función. El CmdletBinding atributo 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 Solicitar confirmación.

ShouldContinue

Se llama a este método para solicitar un segundo mensaje de confirmación. Se debe llamar cuando el ShouldProcess método 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 WriteError método , que se describe en la Write sección de métodos. Cuando se produce un error de terminación y la función no puede continuar, debe llamar al ThrowTerminatingError método . También puede usar la Throw instrucción para finalizar errores y el cmdlet Write-Error para errores que no terminan.

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 Write cmdlets, como Write-Error.

WriteCommandDetail

Para obtener información sobre el WriteCommandDetails método, 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 WriteDebug método . El WriteDebug método muestra mensajes de depuración al usuario. Para obtener más información, consulte 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 WriteObject método 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 va a 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 WriteProgress método 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 WriteVerbose método 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 $WarningPreference variable o usando las Verbose opciones de línea de comandos y Debug . para obtener más información sobre la $WarningPreference variable, 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 $PSCmdlet variable, 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