RUBRIQUE
    about_Functions_Advanced_Methods

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

DESCRIPTION LONGUE
    Les fonctions qui spécifient l'attribut CmdletBinding peuvent 
    accéder à plusieurs méthodes et propriétés à travers la variable 
    $pscmdlet. Ces méthodes incluent les suivantes :


        - Méthodes de traitement d'entrée que les applets de commande 
          compilées utilisent pour travailler.

        - Méthodes ShouldProcess et ShouldContinue utilisées pour 
          obtenir les commentaires de l'utilisateur avant l'exécution 
          d'une action.

        - Méthode ThrowTerminatingError pour la génération 
          d'enregistrements d'erreur.

        - Plusieurs méthodes Write qui retournent différents types de 
          sortie.

        - Plusieurs méthodes Write 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 
    sur ces méthodes et propriétés, consultez 
    System.Management.Automation.PSCmdlet (en anglais) dans la 
    bibliothèque MSDN (Microsoft Developer Network) à l'adresse : 
    https://go.microsoft.com/fwlink/?LinkId=142139.


  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 Begin, Process et End de la fonction. 
      Chaque fonction doit inclure un ou plusieurs de ces blocs. 
      Le runtime Windows PowerShell utilise le code de ces blocs 
      lorsqu'il exécute une fonction. (Ces blocs sont également 
      disponibles pour les fonctions qui n'utilisent pas l'attribut 
      CmdletBinding.)

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


    Process
      Ce bloc est utilisé pour fournir le traitement enregistrement par 
      enregistrement pour la fonction. Ce bloc peut être utilisé autant 
      de fois que nécessaire ou pas du tout, selon l'entrée à la fonction. 
      Par exemple, si la fonction est la première commande du pipeline, 
      le bloc Process sera utilisé une fois. Si la fonction n'est pas la 
      première commande du pipeline, le bloc Process sera utilisé une 
      fois pour chaque entrée que la fonction reçoit du pipeline. 
      S'il n'y a aucune entrée de pipeline, le bloc Process n'est pas utilisé.

      Ce bloc doit être défini si un paramètre de fonction est 
      configuré pour accepter l'entrée de pipeline. Si ce bloc n'est 
      pas défini et que le paramètre accepte l'entrée du pipeline, la 
      fonction manquera les valeurs qui lui sont passées à travers le 
      pipeline. 

      De même, lorsque la fonction prend en charge des demandes de 
      confirmation (lorsque le paramètre SupportsShouldProcess de 
      l'attribut Parameter est défini sur $True), l'appel à la méthode 
      ShouldProcess doit être passé à partir du bloc Process.

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

      L'exemple suivant affiche le plan d'une fonction qui contient 
      un bloc Begin pour le prétraitement unique, un bloc Process pour 
      le traitement de plusieurs enregistrements et un bloc End pour 
      le post-traitement unique.

          Function Test-ScriptCmdlet
          {
            [CmdletBinding(SupportsShouldProcess=$True)] Param 
            ($Parameter1)
            Begin{}
            Process{}
            End{}
          }


  Méthodes de confirmation

    ShouldProcess
      Cette méthode est appelée pour demander la confirmation de 
      l'utilisateur avant que la fonction n'exécute une action qui 
      modifierait le système. La fonction peut continuer selon la valeur 
      booléenne retournée par la méthode. Cette méthode peut être appelée 
      uniquement à partir du bloc Process{} de la fonction. De plus, 
      l'attribut CmdletBinding doit 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 (en anglais) dans 
      la bibliothèque MSDN, à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142142.

      Pour plus d'informations sur la façon de demander confirmation, 
      consultez " Requesting Confirmation " (en anglais) dans la 
      bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkID=136658.


    ShouldContinue
      Cette méthode est appelée pour demander un second message de 
      confirmation. Elle doit être appelée lorsque la méthode 
      ShouldProcess retourne $true. Pour plus d'informations sur 
      cette méthode, consultez 
      System.Management.Automation.Cmdlet.ShouldContinue (en anglais) 
      dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142143.


  Méthodes d'erreur

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

    Pour plus d'informations, consultez System.Management.Automation.Cmdlet.
    ThrowTerminatingError (en anglais) dans la bibliothèque MSDN à 
    l'adresse https://go.microsoft.com/fwlink/?LinkId=142144.


  Méthodes Write

      Une fonction peut appeler les méthodes suivantes pour retourner 
      différents types de sortie. Notez que toute la sortie ne passe 
      pas à la commande suivante du pipeline. Vous pouvez également 
      utiliser diverses applets de commande Write, telles que Write-Error.


    WriteCommandDetail
      Pour plus d'informations sur la méthode WriteCommandDetails, 
      consultez System.Management.Automation.Cmdlet.WriteCommandDetail 
      (en anglais) dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142155.


    WriteDebug
      Pour fournir des informations pouvant être utilisées pour 
      dépanner une fonction, faites en sorte que la fonction appelle 
      la méthode WriteDebug. Ainsi, des messages de débogage s'affichent 
      à l'utilisateur. Pour plus d'informations, consultez 
      System.Management.Automation.Cmdlet.WriteDebug (en anglais) 
      dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142156.


    WriteError
      Les fonctions doivent appeler cette méthode lorsque des erreurs 
      sans fin d'exécution se produisent et que la fonction est 
      conçue pour continuer à traiter les enregistrements. Pour plus 
      d'informations, consultez System.Management.Automation.Cmdlet.WriteErr
      or (en anglais) dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142157.

      Remarque : si une erreur avec fin d'exécution se produit, 
                 la fonction doit appeler la méthode ThrowTerminatingError. 


    WriteObject
      Cette méthode permet à la fonction d'envoyer un objet à la commande 
      suivante du pipeline. Dans la plupart des cas, il s'agit de la méthode à 
      utiliser lorsque la fonction retourne des données. Pour plus 
      d'informations, consultez 
      System.Management.Automation.PSCmdlet.WriteObject (en anglais) 
      dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142158.


    WriteProgress
      Pour les fonctions dont les actions prennent du temps, cette méthode 
      permet d'appeler la méthode WriteProgress pour que les informations 
      de progression s'affichent. Par exemple, vous pouvez afficher 
      le pourcentage terminé. Pour plus d'informations, consultez 
      System.Management.Automation.PSCmdlet.WriteProgress 
      (en anglais) dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142160.


    WriteVerbose
      Pour fournir des informations détaillées sur ce que fait la 
      fonction, faites-lui appeler la méthode WriteVerbose afin 
      d'afficher des messages de commentaires à l'utilisateur. Par 
      défaut, les messages de commentaires ne s'affichent pas. Pour plus 
      d'informations, consultez System.Management.Automation.PSCmdlet.WriteV
      erbose (en anglais) dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142162.

    WriteWarning
      Pour fournir des informations sur les conditions susceptibles 
      de provoquer des résultats inattendus, faites en sorte que la 
      fonction appelle la méthode WriteWarning pour afficher des messages 
      d'avertissement à l'utilisateur. Par défaut, les messages 
      d'avertissement ne s'affichent pas.
      Pour plus d'informations, consultez 
      System.Management.Automation.PSCmdlet.WriteWarning (en anglais) 
      dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142164.

      Remarque : vous pouvez également afficher les messages 
      d'avertissement en configurant la variable WarningPreference ou en 
      utilisant les options de ligne de commande Verbose et Debug.


  Autres méthodes et propriétés

      Pour plus d'informations sur les autres méthodes et propriétés 
      accessibles à travers la variable $PSCmdlet, consultez 
      System.Management.Automation.PSCmdlet (en anglais) 
      dans la bibliothèque MSDN à l'adresse 
      https://go.microsoft.com/fwlink/?LinkId=142139. 

      Par exemple, la propriété ParameterSetName vous permet de 
      consulter le jeu de paramètres utilisé. Les jeux de paramètres 
      vous permettent de créer une fonction qui effectue différentes 
      tâches selon les paramètres spécifiés quand la fonction est exécutée.


VOIR AUSSI
    about_Functions_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters  




Table des matières