Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier les répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer de répertoire.
Les applets de commande peuvent écrire plusieurs types de messages qui peuvent être affichés à l’utilisateur par le runtime Windows PowerShell. Ces messages incluent les types suivants :
Messages détaillés qui contiennent des informations générales sur l’utilisateur.
Déboguer les messages qui contiennent des informations de résolution des problèmes.
Messages d’avertissement qui contiennent une notification indiquant que l’applet de commande est sur le point d’effectuer une opération pouvant avoir des résultats inattendus.
Messages de rapport de progression qui contiennent des informations sur le travail effectué par l’applet de commande lors de l’exécution d’une opération qui prend beaucoup de temps.
Il n’existe aucune limite au nombre de messages que votre applet de commande peut écrire ou le type de messages que votre applet de commande écrit. Chaque message est écrit en effectuant un appel spécifique à partir de la méthode de traitement d’entrée de votre applet de commande.
Définition de l’applet de commande
La première étape de la création de l’applet de commande consiste toujours à nommer l’applet de commande et à déclarer la classe .NET qui implémente l’applet de commande. Toute sorte d’applet de commande peut écrire des notifications utilisateur à partir de ses méthodes de traitement d’entrée ; Ainsi, en général, vous pouvez nommer cette applet de commande à l’aide de n’importe quel verbe qui indique quelles modifications système l’applet de commande effectue. Pour plus d’informations sur les verbes d’applet de commande approuvés, consultez noms de verbes d’applet de commande.
L’applet de commande Stop-Proc est conçue pour modifier le système ; par conséquent, la déclaration System.Management.Automation.CmdletAttribute pour la classe .NET doit inclure le mot clé d’attribut SupportsShouldProcess et être définie sur true.
Le code suivant est la définition de cette classe d’applet de commande Stop-Proc. Pour plus d’informations sur cette définition, consultez Création d’une applet de commande qui modifie le système.
[Cmdlet(VerbsLifecycle.Stop, "proc",
SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet
Définition de paramètres pour la modification du système
L’applet de commande Stop-Proc définit trois paramètres : Name, Forceet PassThru. Pour plus d’informations sur la définition de ces paramètres, consultez Création d’une applet de commande qui modifie le système.
Voici la déclaration de paramètre de l’applet de commande Stop-Proc.
[Parameter(
Position = 0,
Mandatory = true,
ValueFromPipeline = true,
ValueFromPipelineByPropertyName = true
)]
public string[] Name
{
get { return processNames; }
set { processNames = value; }
}
private string[] processNames;
/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
get { return force; }
set { force = value; }
}
private bool force;
/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
get { return passThru; }
set { passThru = value; }
}
private bool passThru;
Substitution d’une méthode de traitement d’entrée
Votre applet de commande doit remplacer une méthode de traitement d’entrée, la plupart du temps, elle sera System.Management.Automation.Cmdlet.ProcessRecord. Cette applet de commande Stop-Proc remplace la méthode de traitement d’entrée System.Management.Automation.Cmdlet.ProcessRe cord. Dans cette implémentation de l’applet de commande Stop-Proc, les appels sont effectués pour écrire des messages détaillés, déboguer des messages et des messages d’avertissement.
Remarque
Pour plus d’informations sur la façon dont cette méthode appelle les méthodes System.Management.Automation.Cmdlet.ShouldProcess et System.Management.Automation.Cmdlet.ShouldContinue, consultez Création d’une applet de commande qui modifie le système.
Écriture d’un message détaillé
La méthode System.Management.Automation.Cmdlet.WriteVerbose est utilisée pour écrire des informations générales au niveau utilisateur qui ne sont pas liées à des conditions d’erreur spécifiques. L’administrateur système peut ensuite utiliser ces informations pour continuer à traiter d’autres commandes. En outre, toutes les informations écrites à l’aide de cette méthode doivent être localisées selon les besoins.
Le code suivant de cette applet de commande Stop-Proc montre deux appels à la méthode System.Management.Automation.Cmdlet.WriteVerbose de la méthode System.Management.Automation.Cmdlet.ProcessRecord.
message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);
message = String.Format("Stopped process \"{0}\", pid {1}.",
processName, process.Id);
WriteVerbose(message);
Écriture d’un message de débogage
La méthode System.Management.Automation.Cmdlet.WriteDebug est utilisée pour écrire des messages de débogage qui peuvent être utilisés pour résoudre les problèmes liés à l’opération de l’applet de commande. L’appel est effectué à partir d’une méthode de traitement d’entrée.
Remarque
Windows PowerShell définit également un paramètre Debug qui présente des informations détaillées et de débogage. Si votre applet de commande prend en charge ce paramètre, il n’est pas nécessaire d’appeler System.Management.Automation.Cmdlet.WriteDebug dans le même code que celui qui appelle System.Management.Automation.Cmdlet.WriteVerbose.
Les deux sections suivantes du code de l’exemple d’applet de commande Stop-Proc affichent les appels à la méthode System.Management.Automation.Cmdlet.WriteDebug de la méthode System.Management.Automation.Cmdlet.ProcessRecord.
Ce message de débogage est écrit immédiatement avant System.Management.Automation.Cmdlet.ShouldProcess est appelé.
message =
String.Format("Acquired name for pid {0} : \"{1}\"",
process.Id, processName);
WriteDebug(message);
Ce message de débogage est écrit immédiatement avant System.Management.Automation.Cmdlet.WriteObject est appelé.
message =
String.Format("Writing process \"{0}\" to pipeline",
processName);
WriteDebug(message);
WriteObject(process);
Windows PowerShell route automatiquement toutes les System.Management.Automation.Cmdlet.WriteDebug appels à l’infrastructure de suivi et aux applets de commande. Cela permet aux appels de méthode d’être suivis vers l’application d’hébergement, un fichier ou un débogueur sans avoir à effectuer de travail de développement supplémentaire dans l’applet de commande. L’entrée de ligne de commande suivante implémente une opération de suivi.
bloc-notes PS> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc
Écriture d’un message d’avertissement
La méthode System.Management.Automation.Cmdlet.WriteWarning est utilisée pour écrire un avertissement lorsque l’applet de commande est sur le point d’effectuer une opération susceptible d’avoir un résultat inattendu, par exemple, en remplaçant un fichier en lecture seule.
Le code suivant de l’exemple d’applet de commande Stop-Proc montre l’appel à la méthode System.Management.Automation.Cmdlet.WriteWarning à partir du remplacement de la méthode System.Management.Automation.Cmdlet.ProcessRecord.
if (criticalProcess)
{
message =
String.Format("Stopping the critical process \"{0}\".",
processName);
WriteWarning(message);
} // if (criticalProcess...
Écriture d’un message de progression
Le System.Management.Automation.Cmdlet.WriteProgress est utilisé pour écrire des messages de progression lorsque les opérations d’applet de commande prennent un temps étendu. Un appel à System.Management.Automation.Cmdlet.WriteProgress transmet un objet System.Management.Automation.Progressrecord envoyé à l’application d’hébergement pour le rendu à l’utilisateur.
Remarque
Cette applet de commande Stop-Proc n’inclut pas d’appel à la méthode System.Management.Automation.Cmdlet.WriteProgress.
Le code suivant est un exemple de message de progression écrit par une applet de commande qui tente de copier un élément.
int myId = 0;
string myActivity = "Copy-item: Copying *.* to C:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);
pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);
Exemple de code
Pour obtenir l’exemple de code C# complet, consultez 'exemple stopProcessSample02.
Définir les types d’objets et la mise en forme
Windows PowerShell transmet des informations entre les applets de commande à l’aide d’objets .NET. Par conséquent, une applet de commande peut avoir besoin de définir son propre type, ou l’applet de commande peut avoir besoin d’étendre un type existant fourni par une autre applet de commande. Pour plus d’informations sur la définition de nouveaux types ou l’extension de types existants, consultez Extension des types d’objets et de la mise en forme.
Génération de l’applet de commande
Après avoir implémenté une applet de commande, elle doit être inscrite auprès de Windows PowerShell via un composant logiciel enfichable Windows PowerShell. Pour plus d’informations sur l’inscription d’applets de commande, consultez Guide pratique pour inscrire des applets de commande, des fournisseurs et des applications hôtes.
Test de l’applet de commande
Lorsque votre applet de commande a été inscrite auprès de Windows PowerShell, vous pouvez la tester en l’exécutant sur la ligne de commande. Testons l’exemple d’applet de commande Stop-Proc. Pour plus d’informations sur l’utilisation d’applets de commande à partir de la ligne de commande, consultez la Prise en main de Windows PowerShell.
L’entrée de ligne de commande suivante utilise Stop-Proc pour arrêter le processus nommé « NOTEPAD », fournir des notifications détaillées et imprimer des informations de débogage.
PS> Stop-Proc -Name notepad -Verbose -DebugLa sortie suivante s’affiche.
VERBOSE: Attempting to stop process " notepad ". DEBUG: Acquired name for pid 5584 : "notepad" Confirm Continue with this operation? [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): Y Confirm Are you sure you want to perform this action? Performing operation "Stop-Proc" on Target "notepad (5584)". [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): Y VERBOSE: Stopped process "notepad", pid 5584.
Voir aussi
Créer une applet de commande qui modifie le système
Comment créer une applet de commande Windows PowerShell
extension des types d’objets et de mise en forme
Comment inscrire des applets de commande, des fournisseurs et des applications hôtes
Collaborez avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner des problèmes et des demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
