Dodawanie aliasów, rozszerzenia symboli wieloznacznych i pomocy do parametrów polecenia cmdlet

  • Artykuł

W tej sekcji opisano sposób dodawania aliasów, rozszerzania symboli wieloznacznych i komunikatów Pomocy do parametrów Stop-Proc polecenia cmdlet (opisanego w temacie Tworzenie polecenia cmdlet modyfikujące system).

To Stop-Proc polecenie cmdlet próbuje zatrzymać procesy, które są pobierane przy użyciu Get-Proc polecenia cmdlet (opisane w tworzenie pierwszego polecenia cmdlet).

Definiowanie polecenia cmdlet

Pierwszym krokiem tworzenia polecenia cmdlet jest zawsze nazywanie polecenia cmdlet i deklarowanie klasy .NET, która implementuje polecenie cmdlet. Ponieważ piszesz polecenie cmdlet w celu zmiany systemu, powinien on mieć odpowiednio nazwę. Ponieważ to polecenie cmdlet zatrzymuje procesy systemowe, używa czasownika Stop zdefiniowanego przez klasę System.Management.Automation.Verbslifecycle z nounem Proc w celu wskazania procesu. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników poleceń cmdlet, zobacz Cmdlet Verb Names (Nazwy poleceń cmdlet).

Poniższy kod jest definicją klasy dla tego Stop-Proc polecenia cmdlet.

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

Definiowanie parametrów modyfikacji systemu

Polecenie cmdlet musi definiować parametry, które obsługują modyfikacje systemu i opinie użytkowników. Polecenie cmdlet powinno zdefiniować parametr Name lub równoważny, aby polecenie cmdlet mogło modyfikować system według pewnego rodzaju identyfikatora. Ponadto polecenie cmdlet powinno definiować parametry Force i PassThru . Aby uzyskać więcej informacji na temat tych parametrów, zobacz Tworzenie polecenia cmdlet modyfikujące system.

Definiowanie aliasu parametru

Alias parametru może być alternatywną nazwą lub dobrze zdefiniowaną 1-literową lub dwuliterową krótką nazwą parametru polecenia cmdlet. W obu przypadkach celem korzystania z aliasów jest uproszczenie wprowadzania użytkownika z wiersza polecenia. Windows PowerShell obsługuje aliasy parametrów za pomocą atrybutu System.Management.Automation.Aliasattribute, który używa składni deklaracji [Alias()].

Poniższy kod pokazuje, jak alias jest dodawany do parametru Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Oprócz używania atrybutu System.Management.Automation.Aliasattribute środowisko uruchomieniowe Windows PowerShell wykonuje częściowe dopasowywanie nazw, nawet jeśli nie określono aliasów. Jeśli na przykład polecenie cmdlet ma parametr FileName i jest to jedyny parametr rozpoczynający się od F, użytkownik może wprowadzić Filename, , Filenam``Fi``Filelub F i nadal rozpoznać wpis jako parametr FileName.

Tworzenie pomocy dotyczącej parametrów

Windows PowerShell umożliwia utworzenie Pomocy dla parametrów polecenia cmdlet. Zrób to dla dowolnego parametru używanego do modyfikacji systemu i opinii użytkowników. Dla każdego parametru do obsługi Pomocy można ustawić słowo kluczowe atrybutu HelpMessage w deklaracji atrybutu System.Management.Automation.Parameterattribute. To słowo kluczowe definiuje tekst wyświetlany użytkownikowi w celu uzyskania pomocy w korzystaniu z parametru . Możesz również ustawić słowo kluczowe HelpMessageBaseName , aby zidentyfikować nazwę podstawową zasobu do użycia dla komunikatu. Jeśli ustawisz to słowo kluczowe, musisz również ustawić słowo kluczowe HelpMessageResourceId , aby określić identyfikator zasobu.

Poniższy kod z tego Stop-Proc polecenia cmdlet definiuje słowo kluczowe atrybutu HelpMessage dla parametru Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

Zastępowanie metody przetwarzania danych wejściowych

Polecenie cmdlet musi zastąpić metodę przetwarzania danych wejściowych. Najczęściej jest to System.Management.Automation.Cmdlet.ProcessRecord. Podczas modyfikowania systemu polecenie cmdlet powinno wywołać metody System.Management.Automation.Cmdlet.ShouldProcess i System.Management.Automation.Cmdlet.ShouldContinue, aby umożliwić użytkownikowi przekazywanie opinii przed dokonaniem zmiany. Aby uzyskać więcej informacji na temat tych metod, zobacz Tworzenie polecenia cmdlet modyfikujące system.

Obsługa rozszerzania symboli wieloznacznych

Aby zezwolić na wybór wielu obiektów, polecenie cmdlet może używać klas System.Management.Automation.WildcardPattern i System.Management.Automation.WildcardOptions, aby zapewnić obsługę rozszerzania symboli wieloznacznych dla danych wejściowych parametrów. Przykłady wzorców wieloznacznych to lsa*, *.txti [a-c]*. Użyj znaku cudzysłowu zwrotnego (`) jako znaku ucieczki, gdy wzorzec zawiera znak, który powinien być używany dosłownie.

Rozszerzenia symboli wieloznacznych nazw plików i ścieżek to przykłady typowych scenariuszy, w których polecenie cmdlet może chcieć zezwolić na obsługę danych wejściowych ścieżki, gdy jest wymagany wybór wielu obiektów. Typowy przypadek występuje w systemie plików, w którym użytkownik chce zobaczyć wszystkie pliki znajdujące się w bieżącym folderze.

Należy rzadko wymagać dostosowanego wzorca z symbolami wieloznacznymi pasującego do implementacji. W takim przypadku polecenie cmdlet powinno obsługiwać pełną specyfikację POSIX 1003.2, 3.13 dla rozszerzania symboli wieloznacznych lub następujący uproszczony podzestaw:

  • Znak zapytania (?). Dopasuje dowolny znak w określonej lokalizacji.
  • Gwiazdka (*). Dopasuje zero lub więcej znaków rozpoczynających się w określonej lokalizacji.
  • Nawias otwierający ([). Wprowadza wyrażenie w nawiasie deseń, które może zawierać znaki lub zakres znaków. Jeśli zakres jest wymagany, łącznik (-) jest używany do wskazania zakresu.
  • Nawias zamykający (]). Kończy wyrażenie w nawiasie kwadratowym.
  • Znak ucieczki cudzysłowu wstecznego (`). Wskazuje, że następny znak powinien być traktowany dosłownie. Należy pamiętać, że podczas określania znaku cudzysłowu wstecznego z wiersza polecenia (w przeciwieństwie do określania go programowo) znak ucieczki cudzysłowu wstecznego musi być określony dwa razy.

Uwaga

Aby uzyskać więcej informacji na temat wzorców wieloznacznych, zobacz Obsługa symboli wieloznacznych w parametrach polecenia cmdlet.

Poniższy kod pokazuje, jak ustawić opcje symboli wieloznacznych i zdefiniować wzorzec symboli wieloznacznych używany do rozpoznawania parametru Name dla tego polecenia cmdlet.

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

Poniższy kod pokazuje, jak sprawdzić, czy nazwa procesu jest zgodna ze zdefiniowanym wzorcem symboli wieloznacznych. Zwróć uwagę, że w tym przypadku, jeśli nazwa procesu nie jest zgodna ze wzorcem, polecenie cmdlet kontynuuje pobieranie nazwy następnego procesu.

if (!wildcard.IsMatch(processName))
{
  continue;
}

Przykład kodu

Aby uzyskać kompletny przykładowy kod w języku C#, zobacz Przykład StopProcessSample03.

Definiowanie typów obiektów i formatowanie

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 polecenie cmdlet może wymagać rozszerzenia 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ć za pomocą Windows PowerShell za pomocą przystawki 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 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 z Windows PowerShell.

  • Uruchom Windows PowerShell i użyj polecenia Stop-Proc , aby zatrzymać proces przy użyciu aliasu ProcessName dla parametru Name.

    PS> Stop-Proc -ProcessName notepad

    Zostanie wyświetlone następujące dane wyjściowe.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (3496)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • Wprowadź następujący wpis w wierszu polecenia. Ponieważ parametr Name jest obowiązkowy, zostanie wyświetlony monit. Wprowadzenie !? powoduje wyświetlenie tekstu pomocy skojarzonego z parametrem .

    PS> Stop-Proc

    Zostanie wyświetlone następujące dane wyjściowe.

    Cmdlet Stop-Proc at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name[0]: !?
The name of one or more processes to stop. Wildcards are permitted.
Name[0]: notepad

  • Teraz wprowadź następujący wpis, aby zatrzymać wszystkie procesy zgodne ze wzorcem *note*z symbolami wieloznacznymi . Przed zatrzymaniem każdego procesu zgodnego ze wzorcem zostanie wyświetlony monit.

    PS> Stop-Proc -Name *note*

    Zostanie wyświetlone następujące dane wyjściowe.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (1112)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

    Zostanie wyświetlone następujące dane wyjściowe.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

    Zostanie wyświetlone następujące dane wyjściowe.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

Zobacz też