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