about_Functions_Advanced_Methods

Mis à jour: mai 2014

S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

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 DÉTAILLÉE

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

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

- Méthodes ShouldProcess et ShouldContinue qui sont utilisées pour obtenir les commentaires des utilisateurs avant d'effectuer une action.

- Méthode ThrowTerminatingError pour générer des enregistrements d'erreur.

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

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 dans MSDN (Microsoft Developer Network) Library à 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 au sein de ces blocs quand 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 un 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 dans le pipeline.

Process

Ce bloc est utilisé pour fournir un traitement enregistrement par enregistrement pour la fonction. Ce bloc peut être utilisé autant de fois que nécessaire, ou pas du tout, en fonction de l'entrée de la fonction. Par exemple, si la fonction est la première commande dans le pipeline, le bloc Process sera utilisé une seule fois. Si la fonction n'est pas la première commande dans le pipeline, le bloc Process est utilisé une fois pour chaque entrée reçue du pipeline par la fonction. S'il n'existe 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 n'aura pas les valeurs qui sont passées à la fonction via le pipeline.

En outre, quand la fonction prend en charge les demandes de confirmation (lorsque le paramètre SupportsShouldProcess de l'attribut Parameter a la valeur $True), l'appel de la méthode ShouldProcess doit être effectué à partir du bloc Process.

End

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

L'exemple suivant montre la structure d'une fonction qui contient un bloc Begin pour un prétraitement unique, un bloc Process pour le traitement de plusieurs enregistrements et un bloc End pour un 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 confirmation à l'utilisateur avant que la fonction n'effectue une action qui pourrait modifier 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. Par ailleurs, 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 dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142142.

Pour plus d'informations sur la procédure de demande de confirmation, consultez « Demande de confirmation » dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkID=136658.

ShouldContinue

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

MÉTHODES D'ERREUR

Les fonctions peuvent appeler deux méthodes différentes quand des erreurs se produisent. Quand une erreur sans fin d'exécution se produit, la fonction doit appeler la méthode WriteError, qui est décrite dans la section « Méthodes Write ». Quand 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 dans MSDN Library à 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 sorties. Notez que les sorties ne sont pas toutes envoyées à la commande suivante dans le pipeline. Vous pouvez également utiliser les 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 dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142155.

WriteDebug

Pour fournir des informations qui peuvent être utilisées pour résoudre les problèmes d'une fonction, faites en sorte que la fonction appelle la méthode WriteDebug. Celle-ci affiche des messages de débogage à l'intention de l'utilisateur. Pour plus d'informations, consultez System.Management.Automation.Cmdlet.WriteDebug dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142156.

WriteError

Les fonctions doivent appeler cette méthode quand des erreurs sans fin d'exécution se produisent et que la fonction est conçue pour continuer le traitement des enregistrements. Pour plus d'informations, consultez System.Management.Automation.Cmdlet.WriteError dans MSDN Library à 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 dans le pipeline. Dans la plupart des cas, il s'agit de la méthode à utiliser quand la fonction retourne des données. Pour plus d'informations, consultez System.Management.Automation.PSCmdlet.WriteObject dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142158.

WriteProgress

Pour les fonctions dont l'exécution des actions prend beaucoup de temps, cette méthode permet à la fonction d'appeler la méthode WriteProgress afin que les informations de progression s'affichent. Par exemple, vous pouvez afficher le pourcentage effectué. Pour plus d'informations, consultez System.Management.Automation.PSCmdlet.WriteProgress dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142160.

WriteVerbose

Pour fournir des informations détaillées sur ce que fait la fonction, faites en sorte que la fonction appelle la méthode WriteVerbose pour afficher des messages détaillés à l'intention de 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 dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142162.

WriteWarning

Pour fournir des informations sur les conditions qui peuvent provoquer des résultats inattendus, faites en sorte que la fonction appelle la méthode WriteWarning pour afficher des messages d'avertissement à l'intention de l'utilisateur. Par défaut, les messages d'avertissement sont affichés. Pour plus d'informations, consultez System.Management.Automation.PSCmdlet.WriteWarning dans MSDN Library à 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 qui sont accessibles via la variable $PSCmdlet, consultez System.Management.Automation.PSCmdlet dans MSDN Library à l'adresse https://go.microsoft.com/fwlink/?LinkId=142139.

Par exemple, la propriété ParameterSetName vous permet de voir le jeu de paramètres qui est utilisé. Les jeux de paramètres vous permettent de créer une fonction qui effectue différentes tâches basées sur les paramètres qui sont spécifiés lors de l'exécution de la fonction.

VOIR AUSSI

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute