about_Functions_Advanced_Methods

  • Article

Description courte

Décrit comment les fonctions qui spécifient l’attribut CmdletBinding peuvent utiliser les méthodes et les propriétés disponibles pour les applets de commande compilées.

Description longue

Les fonctions qui spécifient l’attribut CmdletBinding peuvent accéder à des méthodes et propriétés supplémentaires via la $PSCmdlet variable. Ces méthodes incluent les méthodes suivantes :

  • Les mêmes méthodes de traitement d’entrée disponibles pour toutes les fonctions.
  • Méthodes ShouldProcess utilisées ShouldContinue pour obtenir des commentaires utilisateur avant l’exécution d’une action.
  • Méthode ThrowTerminatingError de génération d’enregistrements d’erreurs.
  • Plusieurs Write méthodes qui retournent différents types de sortie.

Toutes les méthodes et propriétés de la classe PSCmdlet sont disponibles pour les fonctions avancées. Pour plus d’informations, consultez System.Management.Automation.PSCmdlet.

Pour plus d’informations sur l’attribut CmdletBinding , consultez about_Functions_CmdletBindingAttribute. Pour la classe CmdletBindingAttribute , consultez System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Méthodes de traitement d’entrée

Les méthodes décrites dans cette section sont appelées méthodes de traitement d’entrée. Pour les fonctions, ces trois méthodes sont représentées par les blocs processend et les beginblocs de la fonction. PowerShell 7.3 ajoute une clean méthode de processus de bloc.

Vous n’êtes pas obligé d’utiliser ces blocs dans vos fonctions. Si vous n’utilisez pas de bloc nommé, PowerShell place le code dans le end bloc de la fonction. Toutefois, si vous utilisez l’un de ces blocs nommés ou définissez un dynamicparam bloc, vous devez placer tout le code dans un bloc nommé.

L’exemple suivant montre le plan d’une fonction qui contient un bloc pour le begin prétraitement unique, un process bloc pour le traitement de plusieurs enregistrements et un end bloc pour le post-traitement unique.

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

Remarque

Ces blocs s’appliquent à toutes les fonctions, pas seulement aux fonctions qui utilisent l’attribut CmdletBinding .

begin

Ce bloc est utilisé pour fournir un prétraitement unique facultatif pour la fonction. Le runtime PowerShell utilise le code de ce bloc une fois pour chaque instance de la fonction dans le pipeline.

process

Ce bloc est utilisé pour fournir un traitement d’enregistrement par enregistrement pour la fonction. Vous pouvez utiliser un process bloc sans définir les autres blocs. Le nombre d’exécutions de blocs dépend de process la façon dont vous utilisez la fonction et de l’entrée que la fonction reçoit.

Variable automatique $_ ou $PSItem contient l’objet actuel dans le pipeline à utiliser dans le process bloc. La $input variable automatique contient un énumérateur disponible uniquement pour les fonctions et les blocs de script. Pour plus d’informations, consultez about_Automatic_Variables.

  • L’appel de la fonction au début ou en dehors d’un pipeline exécute le process bloc une seule fois.
  • Dans un pipeline, le process bloc s’exécute une fois pour chaque objet d’entrée qui atteint la fonction.
  • Si l’entrée de pipeline qui atteint la fonction est vide, le process bloc n’est pas exécuté.
    • Les beginblocs et clean les blocs ends’exécutent toujours.

Important

Si un paramètre de fonction est défini pour accepter l’entrée du pipeline et qu’un bloc n’est pas défini, le process traitement d’enregistrement par enregistrement échoue. Dans ce cas, votre fonction ne s’exécute qu’une seule fois, quelle que soit l’entrée.

Lorsque vous créez une fonction qui accepte l’entrée de pipeline et utilise CmdletBinding, le process bloc doit utiliser la variable de paramètre que vous avez définie pour l’entrée de pipeline au lieu de $_ ou $PSItem. Par exemple :

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

Ce bloc est utilisé pour fournir un post-traitement unique facultatif pour la fonction.

clean

Le clean bloc a été ajouté dans PowerShell 7.3.

Le bloc clean est un moyen pratique pour les utilisateurs de nettoyer les ressources qui se trouvent dans les blocs begin, process et end. Il est sémantiquement similaire à un bloc finally qui couvre tous les autres blocs nommés d'une fonction de script ou d’une applet de commande de script. Un nettoyage des ressources est effectué dans les cas suivants :

  1. lorsque l’exécution du pipeline se termine normalement sans erreur de terminaison
  2. lorsque l’exécution du pipeline est interrompue en raison d’une erreur de terminaison
  3. lorsque le pipeline est interrompu par Select-Object -First
  4. lorsque le pipeline est arrêté par Ctrl+c ou StopProcessing()

Attention

L’ajout du bloc clean est un changement cassant. Étant donné que clean est analysé comme un mot clé, il empêche les utilisateurs d’appeler directement une commande nommée clean comme première déclaration dans un bloc de script. Toutefois, il n’est pas probable qu’il s’agit d’un problème. La commande peut toujours être appelée à l’aide de l’opérateur d’appel (& clean).

Méthodes de confirmation

ShouldProcess

Cette méthode est appelée pour demander la confirmation de l’utilisateur avant que la fonction effectue une action qui modifie le système. La fonction peut continuer en fonction de la valeur booléenne retournée par la méthode. Cette méthode ne peut être appelée qu’à partir du Process{} bloc de la fonction. L’attribut CmdletBinding doit également déclarer que la fonction prend en charge ShouldProcess (comme indiqué dans l’exemple précédent).

Pour plus d’informations sur cette méthode, consultez System.Management.Automation.Cmdlet.ShouldProcess.

Pour plus d’informations sur la façon de demander la confirmation, consultez Demande de confirmation.

ShouldContinue

Cette méthode est appelée pour demander un deuxième message de confirmation. Elle doit être appelée lorsque la ShouldProcess méthode retourne $true. Pour plus d’informations sur cette méthode, consultez System.Management.Automation.Cmdlet.ShouldContinue.

Méthodes d’erreur

Les fonctions peuvent appeler deux méthodes différentes lorsque des erreurs se produisent. Lorsqu’une erreur ne se termine pas, la fonction doit appeler la WriteError méthode, qui est décrite dans la Write section méthodes. Lorsqu’une erreur de fin se produit et que la fonction ne peut pas continuer, elle doit appeler la ThrowTerminatingError méthode. Vous pouvez également utiliser l’instruction Throw pour terminer les erreurs et l’applet de commande Write-Error pour les erreurs sans fin.

Pour plus d’informations, consultez System.Management.Automation.Cmdlet.ThrowTerminatingError.

Méthodes d’écriture

Une fonction peut appeler les méthodes suivantes pour retourner différents types de sortie. Notez que toutes les sorties ne sont pas envoyées à la commande suivante dans le pipeline. Vous pouvez également utiliser les différentes Write applets de commande, telles que Write-Error.

WriteCommandDetail

Pour plus d’informations sur la WriteCommandDetails méthode, consultez System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Pour fournir des informations qui peuvent être utilisées pour résoudre les problèmes d’une fonction, appelez la WriteDebug méthode. La WriteDebug méthode affiche des messages de débogage à l’utilisateur. Pour plus d’informations, consultez System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Les fonctions doivent appeler cette méthode lorsque des erreurs non terminées se produisent et que la fonction est conçue pour continuer à traiter les enregistrements. Pour plus d’informations, consultez System.Management.Automation.Cmdlet.WriteError.

Remarque

Si une erreur de fin se produit, la fonction doit appeler la méthode ThrowTerminatingError .

WriteObject

La WriteObject méthode permet à la fonction d’envoyer un objet à la commande suivante dans le pipeline. Dans la plupart des cas, WriteObject est la méthode à utiliser lorsque la fonction retourne des données. Pour plus d’informations, consultez System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Pour les fonctions avec des actions qui prennent beaucoup de temps, cette méthode permet à la fonction d’appeler la WriteProgress méthode afin que les informations de progression soient affichées. Par exemple, vous pouvez afficher le pourcentage terminé. Pour plus d’informations, consultez System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Pour fournir des informations détaillées sur ce que fait la fonction, appelez la WriteVerbose méthode pour afficher des messages détaillés à l’utilisateur. Par défaut, les messages détaillés ne sont pas affichés. Pour plus d’informations, consultez System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Pour fournir des informations sur les conditions susceptibles d’entraîner des résultats inattendus, appelez la méthode WriteWarning pour afficher les messages d’avertissement à l’utilisateur. Par défaut, les messages d’avertissement sont affichés. Pour plus d’informations, consultez System.Management.Automation.PSCmdlet.WriteWarning.

Remarque

Vous pouvez également afficher des messages d’avertissement en configurant la $WarningPreference variable ou en utilisant les options de ligne de commande et Debug de Verbose ligne de commande. pour plus d’informations sur la $WarningPreference variable, consultez about_Preference_Variables.

Autres méthodes et propriétés

Pour plus d’informations sur les autres méthodes et propriétés accessibles via la $PSCmdlet variable, consultez System.Management.Automation.PSCmdlet.

Par exemple, la propriété ParameterSetName vous permet de voir le jeu de paramètres utilisé. Les jeux de paramètres vous permettent de créer une fonction qui effectue différentes tâches en fonction des paramètres spécifiés lors de l’exécution de la fonction.

Voir aussi