Hinzufügen von Benutzermeldungen zum Cmdlet

Artikel
09/24/2021

Cmdlets können verschiedene Arten von Nachrichten schreiben, die dem Benutzer von der Laufzeit Windows PowerShell werden können. Diese Nachrichten enthalten die folgenden Typen:

Ausführliche Meldungen, die allgemeine Benutzerinformationen enthalten.
Debugmeldungen, die Informationen zur Problembehandlung enthalten.
Warnmeldungen, die eine Benachrichtigung enthalten, dass das Cmdlet einen Vorgang ausführen wird, der zu unerwarteten Ergebnissen führen kann.
Statusberichtsmeldungen, die Informationen darüber enthalten, wie viel Arbeit das Cmdlet abgeschlossen hat, wenn ein Vorgang ausgeführt wird, der lange dauert.

Es gibt keine Grenzwerte für die Anzahl von Nachrichten, die Ihr Cmdlet schreiben kann, oder den Typ der Nachrichten, die Ihr Cmdlet schreibt. Jede Nachricht wird geschrieben, indem ein bestimmter Aufruf innerhalb der Eingabeverarbeitungsmethode Ihres Cmdlets erfolgt.

Definieren des Cmdlets

Der erste Schritt bei der Cmdlet-Erstellung besteht immer im Benennen des Cmdlets und deklarieren der .NET-Klasse, die das Cmdlet implementiert. Jede Art von Cmdlet kann Benutzerbenachrichtigungen aus den Eingabeverarbeitungsmethoden schreiben. Im Allgemeinen können Sie dieses Cmdlet also mit einem beliebigen Verb benennen, das angibt, welche Systemänderungen das Cmdlet ausführt. Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet-Verbnamen.

Das Stop-Proc-Cmdlet wurde entwickelt, um das System zu ändern. Daher muss die System.Management.Automation.CmdletAttribute-Deklaration für die .NET-Klasse das Attributschlüsselwort enthalten SupportsShouldProcess und auf festgelegt true werden.

Der folgende Code ist die Definition für diese Stop-Proc Cmdlet-Klasse. Weitere Informationen zu dieser Definition finden Sie unter Erstellen eines Cmdlets, das das System ändert.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Definieren von Parametern für die Systemänderung

Das Stop-Proc-Cmdlet definiert drei Parameter: Name Force , und PassThru . Weitere Informationen zum Definieren dieser Parameter finden Sie unter Erstellen eines Cmdlets, das das System ändert.

Dies ist die Parameterdeklaration für das Stop-Proc Cmdlet.

[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;

Überschreiben einer Eingabeverarbeitungsmethode

Ihr Cmdlet muss eine Eingabeverarbeitungsmethode überschreiben. In den meisten Jahren ist dies System.Management.Automation.Cmdlet.ProcessRecord. Dieses Stop-Proc-Cmdlet überschreibt die Eingabeverarbeitungsmethode System.Management.Automation.Cmdlet.ProcessRecord. In dieser Implementierung des Cmdlets Stop-Proc werden Aufrufe zum Schreiben ausführlicher Meldungen, Debugmeldungen und Warnmeldungen ausgeführt.

Hinweis

Weitere Informationen dazu, wie diese Methode die Methoden System.Management.Automation.Cmdlet.ShouldProcess und System.Management.Automation.Cmdlet.ShouldContinue aufruft, finden Sie unter Erstellen eines Cmdlets,das das System ändert.

Schreiben einer ausführlichen Nachricht

Die System.Management.Automation.Cmdlet.WriteVerbose-Methode wird verwendet, um allgemeine Informationen auf Benutzerebene zu schreiben, die nicht mit bestimmten Fehlerbedingungen in Zusammenhang stehen. Der Systemadministrator kann diese Informationen dann verwenden, um die Verarbeitung anderer Befehle fortzufahren. Darüber hinaus sollten alle Informationen, die mit dieser Methode geschrieben wurden, nach Bedarf lokalisiert werden.

Der folgende Code aus diesem Stop-Proc-Cmdlet zeigt zwei Aufrufe der System.Management.Automation.Cmdlet.WriteVerbose-Methode aus der Überschreibung der System.Management.Automation.Cmdlet.ProcessRecord-Methode.

message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);

message = String.Format("Stopped process \"{0}\", pid {1}.",
                        processName, process.Id);

WriteVerbose(message);

Schreiben einer Debugmeldung

Die System.Management.Automation.Cmdlet.WriteDebug-Methode wird verwendet, um Debugmeldungen zu schreiben, die zur Problembehandlung des Vorgangs des Cmdlets verwendet werden können. Der Aufruf erfolgt über eine Eingabeverarbeitungsmethode.

Hinweis

Windows PowerShell definiert auch einen Debug Parameter, der sowohl ausführliche als auch Debuginformationen enthält. Wenn Ihr Cmdlet diesen Parameter unterstützt, muss es System.Management.Automation.Cmdlet.WriteDebug nicht in demselben Code aufrufen, der System.Management.Automation.Cmdlet.WriteVerbose aufruft.

Die folgenden beiden Codeabschnitte des Stop-Proc-Beispiel-Cmdlets zeigen Aufrufe der System.Management.Automation.Cmdlet.WriteDebug-Methode aus der Überschreibung der System.Management.Automation.Cmdlet.ProcessRecord-Methode.

Diese Debugmeldung wird unmittelbar vor dem System.Management.Automation.Cmdlet.ShouldProcess-Namen geschrieben.

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

Diese Debugmeldung wird unmittelbar vor dem System.Management.Automation.Cmdlet.WriteObject-Namen geschrieben.

message =
         String.Format("Writing process \"{0}\" to pipeline",
         processName);
WriteDebug(message);
WriteObject(process);

Windows PowerShell alle System.Management.Automation.Cmdlet.WriteDebug-Aufrufe automatisch an die Ablaufverfolgungsinfrastruktur und cmdlets weiter. Dadurch können die Methodenaufrufe an die Hostanwendung, eine Datei oder einen Debugger verfolgt werden, ohne dass Sie zusätzliche Entwicklungsarbeit innerhalb des Cmdlets ausführen müssen. Der folgende Befehlszeileneintrag implementiert einen Ablaufverfolgungsvorgang.

PS> trace-expression stop-proc -file proc.log -command stop-proc editor

Schreiben einer Warnmeldung

Die System.Management.Automation.Cmdlet.WriteWarning-Methode wird verwendet, um eine Warnung zu schreiben, wenn das Cmdlet einen Vorgang ausführen wird, der ein unerwartetes Ergebnis haben kann, z. B. das Überschreiben einer schreibgeschützten Datei.

Der folgende Code aus dem Stop-Proc-Beispiel-Cmdlet zeigt den Aufruf der System.Management.Automation.Cmdlet.WriteWarning-Methode aus der Überschreibung der System.Management.Automation.Cmdlet.ProcessRecord-Methode.

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

Schreiben einer Statusmeldung

Das System.Management.Automation.Cmdlet.WriteProgress wird verwendet, um Statusmeldungen zu schreiben, wenn cmdlet-Vorgänge einen längeren Zeitraum dauern. Ein Aufruf von System.Management.Automation.Cmdlet.WriteProgress übergibt ein System.Management.Automation.Progressrecord-Objekt, das zum Rendern an den Benutzer an die Hostanwendung gesendet wird.

Hinweis

Dieses Stop-Proc-Cmdlet enthält keinen Aufruf der System.Management.Automation.Cmdlet.WriteProgress-Methode.

Der folgende Code ist ein Beispiel für eine Statusmeldung, die von einem Cmdlet geschrieben wurde, das versucht, ein Element zu kopieren.

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);

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie unter StopProcessSample02-Beispiel.

Definieren von Objekttypen und Formatierungen

Windows PowerShell übergibt Informationen zwischen Cmdlets mithilfe von .NET-Objekten. Folglich muss ein Cmdlet möglicherweise seinen eigenen Typ definieren, oder das Cmdlet muss möglicherweise einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder zum Erweitern vorhandener Typen finden Sie unter Erweitern von Objekttypen und Formatieren von.

Erstellen des Cmdlets

Nach der Implementierung eines Cmdlets muss es über ein Windows PowerShell über ein Windows PowerShell-Snap-In registriert werden. Weitere Informationen zum Registrieren von Cmdlets finden Sie unter Registrieren von Cmdlets, Anbietern und Hostanwendungen.

Testen des Cmdlets

Wenn Ihr Cmdlet bei Windows PowerShell wurde, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Testen Sie das Beispiel für das Stop-Proc Cmdlet. Weitere Informationen zur Verwendung von Cmdlets über die Befehlszeile finden Sie unter Erste Schritte mit Windows PowerShell.

Der folgende Befehlszeileneintrag verwendet Stop-Proc, um den Prozess mit dem Namen "NOTEPAD" zu beenden, ausführliche Benachrichtigungen zu senden und Debuginformationen zu drucken.

PS> stop-proc -Name notepad -Verbose -Debug

Die folgende Ausgabe wird angezeigt.

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.