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