À propos des méthodes avancées Functions
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 à un certain nombre de méthodes et de propriétés via la $PSCmdlet
variable. Ces méthodes incluent les méthodes suivantes :
- Méthodes de traitement d’entrée utilisées par les applets de commande compilées pour effectuer leur travail.
- Les
ShouldProcess
méthodes utiliséesShouldContinue
pour obtenir des commentaires utilisateur avant qu’une action soit effectuée. - Méthode
ThrowTerminatingError
pour générer des enregistrements d’erreur. - Plusieurs méthodes qui retournent différents
Write
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 et les Begin
Process
End
blocs de la fonction. Vous n’êtes pas obligé d’utiliser l’un de ces blocs dans vos fonctions.
Notes
Ces blocs sont également disponibles pour les fonctions qui n’utilisent pas l’attribut CmdletBinding
.
Début
Ce bloc est utilisé pour fournir un prétraitement unique facultatif pour la fonction. Le runtime PowerShell utilise le code dans ce bloc une fois pour chaque instance de la fonction dans le pipeline.
Processus
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 ne s’exécute pas .- Les blocs et
End
lesBegin
blocs s’exécutent toujours.
- Les blocs et
Important
Si un paramètre de fonction est défini pour accepter l’entrée de pipeline et qu’un Process
bloc n’est pas défini, le 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.
End
Ce bloc est utilisé pour fournir un post-traitement unique facultatif pour la fonction.
L’exemple suivant montre le contour d’une fonction qui contient un Begin
bloc pour le prétraitement unique, un Process
bloc pour le traitement de plusieurs enregistrements et un End
bloc pour un post-traitement unique.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
Notes
L’utilisation d’un ou End
d’un Begin
bloc nécessite que vous définissez les trois blocs. Lorsque vous utilisez les trois blocs, tout le code PowerShell doit se trouver à l’intérieur de l’un des blocs.
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 bloc de la Process{}
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 une 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 non terminée se produit, 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 non-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 la sortie n’est pas toutes envoyée à 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 les 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.
Notes
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 à se terminer, 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.
Notes
Vous pouvez également afficher des messages d’avertissement en configurant la $WarningPreference
variable ou en utilisant les Verbose
options de ligne de commande.Debug
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
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute