Dodawanie wiadomości użytkownika do polecenia cmdlet

Artykuł
09/24/2021

Polecenia cmdlet mogą zapisywać kilka rodzajów komunikatów, które mogą być wyświetlane użytkownikowi przez Windows PowerShell uruchomieniowe. Komunikaty te obejmują następujące typy:

Pełne komunikaty zawierające ogólne informacje o użytkowniku.
Debugowanie komunikatów zawierających informacje dotyczące rozwiązywania problemów.
Komunikaty ostrzegawcze zawierające powiadomienie, że polecenie cmdlet będzie wykonywać operację, która może mieć nieoczekiwane wyniki.
Komunikaty raportu postępu zawierające informacje o tym, ile pracy zostało wykonane przez polecenie cmdlet podczas wykonywania operacji, która zajmuje dużo czasu.

Nie ma żadnych ograniczeń liczby komunikatów, które polecenie cmdlet może zapisywać, ani typu komunikatów zapisywanych przez polecenie cmdlet. Każdy komunikat jest zapisywany przez wykonanie określonego wywołania z metody przetwarzania danych wejściowych polecenia cmdlet.

Definiowanie polecenia cmdlet

Pierwszym krokiem podczas tworzenia polecenia cmdlet jest zawsze nazewnictwo polecenia cmdlet i deklarowanie klasy .NET, która implementuje polecenie cmdlet. Dowolny rodzaj polecenia cmdlet może zapisywać powiadomienia użytkownika z jego metod przetwarzania danych wejściowych; Dlatego ogólnie rzecz biorąc, to polecenie cmdlet można nazwać za pomocą dowolnego czasownika, który wskazuje, jakie modyfikacje systemu wykonuje polecenie cmdlet. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników cmdlet, zobacz Nazwy czasowników polecenia cmdlet.

Polecenie Stop-Proc jest przeznaczone do modyfikowania systemu; dlatego deklaracja System.Management.Automation.CmdletAttribute dla klasy .NET musi zawierać słowo kluczowe attribute i być SupportsShouldProcess ustawiona na true .

Poniższy kod jest definicją tej klasy Stop-Proc polecenia cmdlet. Aby uzyskać więcej informacji na temat tej definicji, zobacz Tworzenie polecenia cmdlet modyfikujące system.

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

Definiowanie parametrów modyfikacji systemu

Polecenie cmdlet Stop-Proc definiuje trzy parametry: Name Force , i PassThru . Aby uzyskać więcej informacji na temat definiowania tych parametrów, zobacz Tworzenie polecenia cmdlet modyfikujące system.

Poniżej znajduje się deklaracja parametru dla 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;

Zastępowanie metody przetwarzania danych wejściowych

Polecenie cmdlet musi zastąpić metodę przetwarzania danych wejściowych, najczęściej będzie to System.Management.Automation.Cmdlet.ProcessRecord. To Stop-Proc polecenie cmdlet zastępuje metodę przetwarzania danych wejściowych System.Management.Automation.Cmdlet.ProcessRecord. W tej implementacji polecenia cmdlet Stop-Proc wywołania są wysyłane do pisania pełnych komunikatów, komunikatów debugowania i komunikatów ostrzegawczych.

Uwaga

Aby uzyskać więcej informacji na temat sposobu, w jaki ta metoda wywołuje metody System.Management.Automation.Cmdlet.ShouldProcess i System.Management.Automation.Cmdlet.ShouldContinue, zobacz Creating a Cmdlet that Modyfikuje system.

Pisanie pełnej wiadomości

Metoda System.Management.Automation.Cmdlet.WriteVerbose służy do pisania ogólnych informacji na poziomie użytkownika, które nie są związane z określonymi warunkami błędu. Administrator systemu może następnie użyć tych informacji, aby kontynuować przetwarzanie innych poleceń. Ponadto wszelkie informacje zapisane przy użyciu tej metody powinny być zlokalizowane zgodnie z potrzebami.

Poniższy kod z tego polecenia cmdlet Stop-Proc pokazuje dwa wywołania metody System.Management.Automation.Cmdlet.WriteVerbose z przesłonięcia metody 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);

Pisanie komunikatu debugowania

Metoda System.Management.Automation.Cmdlet.WriteDebug służy do pisania komunikatów debugowania, których można użyć do rozwiązywania problemów z działaniem polecenia cmdlet. Wywołanie jest wykonane z metody przetwarzania danych wejściowych.

Uwaga

Windows PowerShell definiuje również parametr, który przedstawia zarówno pełne informacje, jak Debug i informacje debugowania. Jeśli polecenie cmdlet obsługuje ten parametr, nie musi ono wywołać funkcji System.Management.Automation.Cmdlet.WriteDebug w tym samym kodzie, który wywołuje system.Management.Automation.Cmdlet.WriteVerbose.

Następujące dwie sekcje kodu z przykładowego polecenia cmdlet programu Stop-Proc pokazują wywołania metody System.Management.Automation.Cmdlet.WriteDebug z zastąpienia metody System.Management.Automation.Cmdlet.ProcessRecord.

Ten komunikat debugowania jest zapisywany bezpośrednio przed wywoływaniem polecenia System.Management.Automation.Cmdlet.ShouldProcess.

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

Ten komunikat debugowania jest zapisywany bezpośrednio przed wywoływaniem polecenia System.Management.Automation.Cmdlet.WriteObject.

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

Windows PowerShell automatycznie kieruje wszelkie wywołania System.Management.Automation.Cmdlet.WriteDebug do infrastruktury śledzenia i polecenia cmdlet. Dzięki temu wywołania metody mogą być śledzone do aplikacji hostingowej, pliku lub debugera bez konieczności dodatkowej pracy dewelopera w ramach polecenia cmdlet . Poniższy wpis wiersza polecenia implementuje operację śledzenia.

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

Pisanie komunikatu ostrzegawczego

Metoda System.Management.Automation.Cmdlet.WriteWarning służy do pisania ostrzeżenia, gdy polecenie cmdlet ma wykonać operację, która może mieć nieoczekiwany wynik, na przykład przez nadpisanie pliku tylko do odczytu.

Poniższy kod z przykładowego polecenia cmdlet Stop-Proc pokazuje wywołanie metody System.Management.Automation.Cmdlet.WriteWarning z przesłonięcia metody System.Management.Automation.Cmdlet.ProcessRecord.

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

Pisanie komunikatu o postępie

System.Management.Automation.Cmdlet.WriteProgress służy do zapisu komunikatów o postępie, gdy operacje polecenia cmdlet trwają dłuższy czas. Wywołanie obiektu System.Management.Automation.Cmdlet.WriteProgress przekazuje obiekt System.Management.Automation.Progressrecord, który jest wysyłany do aplikacji hostingowej w celu renderowania użytkownikowi.

Uwaga

To Stop-Proc cmdlet nie zawiera wywołania metody System.Management.Automation.Cmdlet.WriteProgress.

Poniższy kod jest przykładem komunikatu o postępie zapisanego przez polecenie cmdlet, które próbuje skopiować element.

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

Przykład kodu

Aby uzyskać kompletny przykładowy kod w języku C#, zobacz StopProcessSample02 Sample (Przykład StopProcessSample02).

Definiowanie typów obiektów i formatowania

Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym polecenie cmdlet może wymagać zdefiniowania własnego typu lub może być konieczne rozszerzenie istniejącego typu udostępnianego przez inne polecenie cmdlet. Aby uzyskać więcej informacji na temat definiowania nowych typów lub rozszerzania istniejących typów, zobacz Rozszerzanie typów obiektów i formatowanie.

Tworzenie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy je zarejestrować w Windows PowerShell za pośrednictwem Windows PowerShell przystawki. Aby uzyskać więcej informacji na temat rejestrowania cmdlet, zobacz Jak rejestrować polecenia cmdlet,dostawców i aplikacje hosta .

Testowanie polecenia cmdlet

Po zarejestrowaniu polecenia cmdlet w Windows PowerShell można je przetestować, uruchamiając je w wierszu polecenia. Przetestujmy przykładowe polecenie cmdlet Stop-Proc cmdlet. Aby uzyskać więcej informacji na temat używania poleceń cmdlet z wiersza polecenia, zobacz Wprowadzenie z Windows PowerShell.

Poniższy wpis wiersza polecenia używa polecenia Stop-Proc do zatrzymania procesu o nazwie "NOTEPAD", zapewnienia pełnych powiadomień i drukowania informacji debugowania.

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

Wyświetlone są następujące dane wyjściowe.

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.