Udostępnij za pomocą

Dodawanie wiadomości użytkownika do polecenia cmdlet

Polecenia cmdlet mogą zapisywać kilka rodzajów komunikatów, które mogą być wyświetlane użytkownikowi przez środowisko uruchomieniowe programu Windows PowerShell. Te komunikaty 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 ma wykonać operację, która może mieć nieoczekiwane wyniki.

  • Komunikaty raportu postępu zawierające informacje o tym, ile pracy wykonano polecenie cmdlet podczas wykonywania operacji, która zajmuje dużo czasu.

Nie ma żadnych ograniczeń dotyczących liczby komunikatów, które polecenie cmdlet może zapisywać lub typ komunikatów zapisywanych przez polecenie cmdlet. Każdy komunikat jest zapisywany przez wykonanie określonego wywołania z poziomu metody przetwarzania wejściowego polecenia cmdlet.

Definiowanie polecenia cmdlet

Pierwszym krokiem tworzenia polecenia cmdlet jest zawsze nazewnictwo polecenia cmdlet i deklarowanie klasy .NET, która implementuje polecenie cmdlet. Dowolne polecenie cmdlet może zapisywać powiadomienia użytkownika z metod przetwarzania danych wejściowych; Dlatego ogólnie rzecz biorąc, można nazwać to polecenie cmdlet przy użyciu dowolnego zlecenia wskazującego, jakie modyfikacje systemowe wykonuje polecenie cmdlet. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników poleceń cmdlet, zobacz Cmdlet Verb Names.

Polecenie cmdlet Stop-Proc jest przeznaczone do modyfikowania systemu; w związku z tym deklarację System.Management.Automation.CmdletAttribute dla klasy .NET musi zawierać słowo kluczowe atrybutu SupportsShouldProcess i być ustawione na wartość true.

Poniższy kod to definicja tej klasy poleceń cmdlet Stop-Proc. 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, Forcei PassThru. Aby uzyskać więcej informacji na temat definiowania tych parametrów, zobacz Creating a Cmdlet that Modifies the System.

Oto deklaracja parametru dla polecenia cmdlet 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;

Zastępowanie metody przetwarzania wejściowego

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

Uwaga

Aby uzyskać więcej informacji o tym, jak ta metoda wywołuje metody System.Management.Automation.Cmdlet.ShouldProcess i System.Management.Automation.Cmdlet.ShouldContinue, zobacz Creating a Cmdlet that Modifies the 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ą powią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 napisane przy użyciu tej metody powinny być zlokalizowane zgodnie z potrzebami.

Poniższy kod z tego polecenia cmdlet Stop-Proc przedstawia dwa wywołania metody System.Management.Automation.Cmdlet.WriteVerbose z zastąpienia 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 operacją polecenia cmdlet. Wywołanie jest wykonywane z metody przetwarzania danych wejściowych.

Uwaga

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

W poniższych dwóch sekcjach kodu z przykładowego polecenia cmdlet Stop-Proc przedstawiono wywołania metody System.Management.Automation.Automation.Cmdlet.WriteDebug z zastąpienia metody System.Management.Automation.Cmdlet.ProcessRecord.

Ten komunikat debugowania jest zapisywany bezpośrednio przed wywołaniem 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łaniem System.Management.Automation.Cmdlet.WriteObject.

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

Program Windows PowerShell automatycznie kieruje wszystkie wywołania System.Management.Automation.Cmdlet.WriteDebug wywołania infrastruktury śledzenia i poleceń cmdlet. Umożliwia to śledzenie wywołań metody do aplikacji hostingowej, pliku lub debugera bez konieczności wykonywania dodatkowych prac programistycznych w ramach polecenia cmdlet. Poniższy wpis wiersza polecenia implementuje operację śledzenia.

notatnik> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc PS

Pisanie komunikatu ostrzegawczego

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

Poniższy kod z przykładowego polecenia cmdlet Stop-Proc pokazuje wywołanie metody System.Management.Automation.Automation.WriteWarning z zastąpienia 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 zapisywania komunikatów postępu, gdy operacje poleceń cmdlet zajmują dłuższy czas. Wywołanie System.Management.Automation.Cmdlet.WriteProgress przekazuje obiekt System.Management.Automation.Progressrec ord, który jest wysyłany do aplikacji hostingowej na potrzeby renderowania użytkownikowi.

Uwaga

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

Poniższy kod to przykład komunikatu o postępie napisanym 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ładowy kod

Aby uzyskać pełny przykładowy kod języka C#, zobacz StopProcessSample02 Sample.

Definiowanie typów obiektów i formatowanie

Program Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym może być konieczne zdefiniowanie własnego typu polecenia cmdlet lub może być konieczne rozszerzenie istniejącego typu dostarczonego 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.

Kompilowanie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy go zarejestrować w programie Windows PowerShell za pomocą przystawki programu Windows PowerShell. Aby uzyskać więcej informacji na temat rejestrowania poleceń cmdlet, zobacz Jak rejestrować polecenia cmdlet, dostawcy i aplikacje hosta.

Testowanie polecenia cmdlet

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

  • Poniższy wpis wiersza polecenia używa Stop-Proc, aby zatrzymać proces o nazwie "NOTATNIK", udostępnić pełne powiadomienia i wydrukować informacje debugowania.

    PS> Stop-Proc -Name notepad -Verbose -Debug

    Zostanie wyświetlone 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.

Zobacz też

utwórz polecenie cmdlet modyfikujące systemu

Jak utworzyć polecenie cmdlet programu Windows PowerShell

rozszerzanie typów obiektów i formatowanie

Jak rejestrować polecenia cmdlet, dostawcy i aplikacje hosta

zestaw SDK programu Windows PowerShell

  • Last updated on