Udostępnij za pomocą

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

W tej sekcji opisano sposób dodawania aliasów, rozszerzania symboli wieloznacznych i komunikatów Pomocy do parametrów polecenia cmdlet Stop-Proc (opisanego w artykule Creating a Cmdlet that Modifies the System).

To polecenie cmdlet Stop-Proc próbuje zatrzymać procesy pobierane przy użyciu polecenia cmdlet Get-Proc (opisanego w Tworzenie pierwszego polecenia cmdlet).

Definiowanie polecenia cmdlet

Pierwszym krokiem tworzenia polecenia cmdlet jest zawsze nazewnictwo polecenia cmdlet i deklarowanie klasy .NET, która implementuje polecenie cmdlet. Ponieważ piszesz polecenie cmdlet w celu zmiany systemu, powinno ono być odpowiednio nazwane. Ponieważ to polecenie cmdlet zatrzymuje procesy systemowe, używa czasownika Stop, zdefiniowanego przez System.Management.Automation.VerbsLifecycle klasy, z proc wskazywać proces. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników poleceń cmdlet, zobacz Cmdlet Verb Names.

Poniższy kod to definicja klasy dla tego polecenia cmdlet Stop-Proc.

[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ć Nazwa parametru lub równoważnego, aby polecenie cmdlet mogło zmodyfikować 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 Creating a Cmdlet that modifies the 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 używania aliasów jest uproszczenie wpisu użytkownika z wiersza polecenia. Program Windows PowerShell obsługuje aliasy parametrów za pośrednictwem atrybutu System.Management.Automation.AliasAttribute, który używa składni deklaracji [Alias()].

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

/// <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 programu 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, File, Filub F i nadal rozpoznać wpis jako parametr FileName.

Tworzenie pomocy dotyczącej parametrów

Program 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ć HelpMessage słowo kluczowe atrybutu w System.Management.Automation.ParameterAttribute deklaracji atrybutu. 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ć HelpMessageResourceId słowo kluczowe, aby określić identyfikator zasobu.

Poniższy kod z tego polecenia cmdlet Stop-Proc 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 wejściowego

Polecenie cmdlet musi zastąpić metodę przetwarzania wejściowego. Najczęściej będzie 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 Creating a Cmdlet that Modifies the System.

Obsługa rozszerzania symboli wieloznacznych

Aby zezwolić na wybór wielu obiektów, polecenie cmdlet może użyć System.Management.Automation.WildcardPattern i System.Management.Automation.WildcardOptions klasy, 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 wstecznego (`) jako znaku ucieczki, gdy wzorzec zawiera znak, który powinien być używany dosłownie.

Rozszerzenia wieloznaczne 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 dotyczy systemu plików, w którym użytkownik chce zobaczyć wszystkie pliki znajdujące się w bieżącym folderze.

Niestandardowa implementacja dopasowywania wzorców wieloznacznych powinna być potrzebna tylko rzadko. W takim przypadku polecenie cmdlet powinno obsługiwać pełną specyfikację POSIX 1003.2, 3.13 dla rozszerzenia symboli wieloznacznych lub następujący uproszczony podzestaw:

  • Znak zapytania (?). Pasuje do dowolnego znaku w określonej lokalizacji.
  • Gwiazdka (*). Dopasuje zero lub więcej znaków rozpoczynających się w określonej lokalizacji.
  • Otwórz nawias kwadratowy ([). 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.
  • Zamknij nawias kwadratowy (]). Kończy wyrażenie nawiasu deseń.
  • 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 temacie Parametry polecenia cmdlet.

Poniższy kod pokazuje, jak ustawić opcje symboli wieloznacznych i zdefiniować wzorzec symboli wieloznacznych używany do rozpoznawania parametru nazwa 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 następnej nazwy procesu.

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

Przykładowy kod

Aby uzyskać pełny przykładowy kod w języku C#, zobacz StopProcessSample03 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.

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

    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 wieloznaczny *note*. 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ż

  • Last updated on