Přidání aliasů, podpory zástupných znaků a nápovědy pro parametry rutiny

  • Článek

Tato část popisuje, jak přidat aliasy, rozšíření zástupných znaků a zprávy nápovědy k parametrům Stop-Proc rutiny (popsané v části Vytvoření rutiny, která upraví systém).

Tato Stop-Proc rutina se pokusí zastavit procesy načtené pomocí Get-Proc rutiny (popsané v části Vytvoření první rutiny).

Definování rutiny

Prvním krokem při vytváření rutin je vždy pojmenování rutiny a deklarování třídy .NET, která implementuje rutinu. Protože píšete rutinu pro změnu systému, měla by být odpovídajícím způsobem pojmenována. Vzhledem k tomu, že tato rutina zastaví systémové procesy, používá příkaz Stop definovaný třídou System.Management.Automation.Verbslifecycle s podstatným slovesným uživatelem Proc k označení procesu. Další informace o schválených příkazech rutin najdete v tématu Názvy příkazů rutin.

Následující kód je definice třídy pro tuto Stop-Proc rutinu.

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

Definování parametrů pro úpravu systému

Vaše rutina potřebuje definovat parametry, které podporují úpravy systému a zpětnou vazbu uživatelů. Rutina by měla definovat parametr Name nebo ekvivalentní, aby tato rutina mohla systém upravit určitým druhem identifikátoru. Kromě toho by rutina měla definovat parametry Force a PassThru . Další informace o těchtoparametrch

Definování aliasu parametru

Alias parametru může být alternativním názvem nebo dobře definovaným 1 písmenem nebo krátkým názvem 2 písmen pro parametr rutiny. V obou případech je cílem použití aliasů zjednodušit zadávání uživatelů z příkazového řádku. Windows PowerShell podporuje aliasy parametrů prostřednictvím atributu System.Management.Automation.Aliasattribute, který používá syntaxi [Alias()]deklarace .

Následující kód ukazuje, jak se alias přidá 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;

Kromě použití atributu System.Management.Automation.Aliasattribute provádí modul runtime Windows PowerShell částečné porovnávání názvů, i když nejsou zadány žádné aliasy. Pokud má například vaše rutina parametr FileName a to je jediný parametr, který začíná F, může uživatel zadat Filename, Filenam, , , Filenebo Fia F stále rozpozná položku jako parametr FileName .

Vytvoření nápovědy pro parametry

Windows PowerShell umožňuje vytvořit nápovědu pro parametry rutiny. Udělejte to pro jakýkoli parametr použitý pro úpravu systému a zpětnou vazbu uživatelů. Pro každý parametr, který podporuje nápovědu, můžete nastavit klíčové slovo atributu HelpMessage v deklaraci atributu System.Management.Automation.Parameterattribute. Toto klíčové slovo definuje text, který se má uživateli zobrazit za účelem pomoci s použitím parametru. Můžete také nastavit klíčové slovo HelpMessageBaseName k identifikaci základního názvu prostředku, který se má použít pro zprávu. Pokud nastavíte toto klíčové slovo, musíte také nastavit klíčové slovo HelpMessageResourceId pro zadání identifikátoru prostředku.

Následující kód z této Stop-Proc rutiny definuje klíčové slovo atributu HelpMessage pro parametr 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."
)]

Přepsání metody zpracování vstupu

Vaše rutina musí přepsat metodu zpracování vstupu, nejčastěji se jedná o System.Management.Automation.Cmdlet.ProcessRecord. Při úpravě systému by rutina měla volat metody System.Management.Automation.Cmdlet.ShouldProcess a System.Management.Automation.Rutin.ShouldContinue, aby uživateli umožnily poskytnout zpětnou vazbu před provedením změny. Další informace o těchto metodách naleznete v tématu Vytvoření rutiny, která upravuje systém.

Podpora rozšíření zástupných znaků

Pokud chcete povolit výběr více objektů, může vaše rutina použít třídy System.Management.Automation.WildcardPattern a System.Management.Automation.WildcardOptions k zajištění podpory rozšíření zástupných znaků pro vstup parametrů. Příklady zástupných znaků jsou lsa*, *.txta [a-c]*. Znak zpětné uvozovky (`) použijte jako řídicí znak, pokud vzor obsahuje znak, který by se měl použít doslova.

Rozšíření zástupných znaků názvů souborů a cest jsou příklady běžných scénářů, ve kterých může rutina chtít povolit podporu vstupů cesty při výběru více objektů. Běžným případem je systém souborů, kdy uživatel chce zobrazit všechny soubory umístěné v aktuální složce.

Měli byste potřebovat přizpůsobenou implementaci odpovídající zástupným znakům pouze zřídka. V tomto případě by vaše rutina měla podporovat úplnou specifikaci POSIX 1003.2, 3.13 pro rozšíření zástupných znaků nebo následující zjednodušenou podmnožinu:

  • Otazník (?). Odpovídá libovolnému znaku v zadaném umístění.
  • Hvězdička (*). Odpovídá nule nebo více znaků počínaje zadaným umístěním.
  • Otevřít závorku ([). Představuje výraz závorky vzoru, který může obsahovat znaky nebo rozsah znaků. Pokud je oblast povinná, použije se spojovník (-) k označení oblasti.
  • Zavřít závorku (]). Ukončí výraz závorky vzoru.
  • Řídicí znak zpětné uvozovky (`). Označuje, že další znak by se měl brát doslova. Mějte na paměti, že při zadávání znaku zpětné uvozovky z příkazového řádku (na rozdíl od jeho programového zadání) musí být řídicí znak zpětné uvozovky zadán dvakrát.

Poznámka

Další informace o vzorech zástupných znaků najdete v tématu Podpora zástupných znaků v parametrech rutiny.

Následující kód ukazuje, jak nastavit možnosti zástupných znaků a definovat vzor zástupných znaků použitý k překladu parametru Name pro tuto rutinu.

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

Následující kód ukazuje, jak otestovat, jestli název procesu odpovídá definovanému zástupné sadě. Všimněte si, že pokud v tomto případě název procesu neodpovídá vzoru, rutina pokračuje v získání dalšího názvu procesu.

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

Vzorek kódu

Úplný ukázkový kód jazyka C# najdete v části StopProcessSample03 Sample.

Definování typů objektů a formátování

Windows PowerShell předává informace mezi rutinami pomocí objektů .Net. V důsledku toho může být potřeba definovat vlastní typ rutiny nebo rutina může potřebovat rozšířit existující typ poskytnutý jinou rutinou. Další informace o definování nových typů nebo rozšíření existujících typů najdete v tématu Rozšíření typů objektů a formátování.

Sestavení rutiny

Po implementaci rutiny musí být zaregistrovaný v Windows PowerShell prostřednictvím modulu snap-in Windows PowerShell. Další informace o registraci rutin najdete v tématu Registrace rutin, poskytovatelů a hostitelských aplikací.

Testování rutiny

Když je rutina zaregistrovaná v Windows PowerShell, můžete ji otestovat spuštěním na příkazovém řádku. Pojďme ukázkovou rutinu Stop-Proc otestovat. Další informace o používání rutin z příkazového řádku najdete v Začínáme s Windows PowerShell.

  • Spusťte Windows PowerShell a použijte Stop-Proc k zastavení procesu pomocí aliasu ProcessName pro parametr Name.

    PS> Stop-Proc -ProcessName notepad

    Zobrazí se následující výstup.

    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

  • Na příkazovém řádku proveďte následující položku. Protože je parametr Name povinný, zobrazí se výzva k jeho zadání. Zadání !? zobrazí text nápovědy přidružený k parametru.

    PS> Stop-Proc

    Zobrazí se následující výstup.

    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

  • Teď proveďte následující položku a zastavte všechny procesy, které odpovídají vzoru *note*zástupných znaků . Před zastavením každého procesu, který odpovídá vzoru, se zobrazí výzva.

    PS> Stop-Proc -Name *note*

    Zobrazí se následující výstup.

    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

    Zobrazí se následující výstup.

    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

    Zobrazí se následující výstup.

    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

Viz také