Dela via

Lägga till alias, jokerteckenexpansion och hjälp i cmdlet-parametrar

  • Artikel

I det här avsnittet beskrivs hur du lägger till alias, jokerteckenexpansion och hjälpmeddelanden till parametrarna för cmdleten Stop-Proc (beskrivs i Skapa en cmdlet som ändrar system).

Den här Stop-Proc-cmdleten försöker stoppa processer som hämtas med cmdleten Get-Proc (beskrivs i Skapa din första cmdlet).

Definiera cmdleten

Det första steget när cmdleten skapas är att alltid namnge cmdleten och deklarera .NET-klassen som implementerar cmdleten. Eftersom du skriver en cmdlet för att ändra systemet bör den namnges därefter. Eftersom den här cmdleten stoppar systemprocesserna använder den verbet Stop, som definieras av klassen System.Management.Automation.VerbsLifecycle, med substantivet Proc för att indikera processen. Mer information om godkända cmdlet-verb finns i Cmdlet-verbnamn.

Följande kod är klassdefinitionen för den här Stop-Proc cmdleten.

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

Definiera parametrar för systemändring

Din cmdlet måste definiera parametrar som stöder systemändringar och användarfeedback. Cmdleten bör definiera en Name parameter eller motsvarande så att cmdleten kan ändra systemet med någon form av identifierare. Dessutom bör cmdleten definiera parametrarna Force och PassThru. Mer information om dessa parametrar finns i Skapa en cmdlet som ändrar system.

Definiera ett parameteralias

Ett parameteralias kan vara ett alternativt namn eller ett väldefinierat kortnamn på 1 eller 2 bokstäver för en cmdlet-parameter. I båda fallen är målet med att använda alias att förenkla användarinmatningen från kommandoraden. Windows PowerShell stöder parameteralias via attributet System.Management.Automation.AliasAttribute, som använder deklarationssyntaxen [Alias()].

Följande kod visar hur ett alias läggs till i parametern 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;

Förutom att använda attributet System.Management.Automation.AliasAttribute utför Windows PowerShell-körningen delvis namnmatchning, även om inga alias har angetts. Om din cmdlet till exempel har parametern FileName och det är den enda parametern som börjar med Fkan användaren ange Filename, Filenam, File, Fieller F och fortfarande identifiera posten som parametern FileName.

Skapa hjälp för parametrar

Med Windows PowerShell kan du skapa hjälp för cmdlet-parametrar. Gör detta för alla parametrar som används för systemändring och användarfeedback. För varje parameter som stöd för Hjälp kan du ange nyckelordet HelpMessage attribut i attributet System.Management.Automation.ParameterAttribute attributdeklaration. Det här nyckelordet definierar texten som ska visas för användaren för hjälp med att använda parametern. Du kan också ange nyckelordet HelpMessageBaseName för att identifiera basnamnet för en resurs som ska användas för meddelandet. Om du anger det här nyckelordet måste du också ange nyckelordet HelpMessageResourceId för att ange resursidentifieraren.

Följande kod från den här Stop-Proc-cmdleten definierar nyckelordet HelpMessage för parametern 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."
)]

Åsidosätta en indatabearbetningsmetod

Din cmdlet måste åsidosätta en metod för indatabearbetning, oftast är detta System.Management.Automation.Cmdlet.ProcessRecord. När du ändrar systemet bör cmdleten anropa metoderna System.Management.Automation.Cmdlet.ShouldProcess och System.Management.Automation.Cmdlet.ShouldContinue så att användaren kan ge feedback innan en ändring görs. Mer information om dessa metoder finns i Create a Cmdlet that Modifies the System.

Stöd för jokerteckenexpansion

För att tillåta val av flera objekt kan din cmdlet använda System.Management.Automation.WildcardPattern och System.Management.Automation.WildcardOptions klasser för att ge stöd för jokerteckenexpansion för parameterindata. Exempel på jokerteckenmönster är lsa*, *.txtoch [a-c]*. Använd back-quote-tecknet (`) som ett escape-tecken när mönstret innehåller ett tecken som ska användas bokstavligen.

Jokerteckenexpansioner av fil- och sökvägsnamn är exempel på vanliga scenarier där cmdleten kanske vill tillåta stöd för sökvägsindata när valet av flera objekt krävs. Ett vanligt fall finns i filsystemet, där en användare vill se alla filer som finns i den aktuella mappen.

Du bör bara behöva en anpassad implementering av jokerteckenmönster som matchar sällan. I det här fallet bör cmdleten ha stöd för antingen hela POSIX 1003.2, 3.13-specifikationen för jokerteckenexpansion eller följande förenklade delmängd:

  • Frågetecken (?). Matchar alla tecken på den angivna platsen.
  • Asterisk (*). Matchar noll eller fler tecken som börjar på den angivna platsen.
  • Öppen hakparentes ([). Introducerar ett mönsterparentesuttryck som kan innehålla tecken eller ett teckenintervall. Om ett intervall krävs används ett bindestreck (-) för att ange intervallet.
  • Stäng hakparentes (]). Avslutar ett mönsterparentesuttryck.
  • Escape-tecken för citattecken (`). Anger att nästa tecken ska tas bokstavligen. Tänk på att när du anger back-quote-tecknet från kommandoraden (i stället för att ange det programmatiskt) måste escape-tecknet för back-quote anges två gånger.

Anmärkning

Mer information om jokerteckenmönster finns i Stöd för jokertecken i Cmdlet-parametrar.

Följande kod visar hur du anger jokerteckenalternativ och definierar det jokerteckenmönster som används för att matcha parametern Name för den här cmdleten.

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

Följande kod visar hur du testar om processnamnet matchar det definierade jokerteckenmönstret. Observera att om processnamnet i det här fallet inte matchar mönstret fortsätter cmdleten att hämta nästa processnamn.

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

Kodexempel

Den fullständiga C#-exempelkoden finns i StopProcessSample03 Sample.

Definiera objekttyper och formatering

Windows PowerShell skickar information mellan cmdletar med hjälp av .NET-objekt. Därför kan en cmdlet behöva definiera sin egen typ, eller så kan cmdleten behöva utöka en befintlig typ som tillhandahålls av en annan cmdlet. Mer information om hur du definierar nya typer eller utökar befintliga typer finns i Utöka objekttyper och formatering.

Skapa cmdleten

När du har implementerat en cmdlet måste den registreras med Windows PowerShell via en Windows PowerShell-snapin-modul. Mer information om hur du registrerar cmdletar finns i Så här registrerar du cmdletar, leverantörer och värdprogram.

Testa cmdleten

När din cmdlet har registrerats med Windows PowerShell kan du testa den genom att köra den på kommandoraden. Nu ska vi testa exemplet Stop-Proc cmdlet. Mer information om hur du använder cmdletar från kommandoraden finns i Komma igång med Windows PowerShell.

  • Starta Windows PowerShell och använd Stop-Proc för att stoppa en process med hjälp av aliaset ProcessName för parametern Name.

    PS> Stop-Proc -ProcessName notepad

    Följande utdata visas.

    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

  • Gör följande post på kommandoraden. Eftersom parametern Namn är obligatorisk uppmanas du att ange den. När du anger !? visas hjälptexten som är associerad med parametern.

    PS> Stop-Proc

    Följande utdata visas.

    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

  • Gör nu följande post för att stoppa alla processer som matchar jokerteckenmönstret *note*. Du uppmanas innan du stoppar varje process som matchar mönstret.

    PS> Stop-Proc -Name *note*

    Följande utdata visas.

    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

    Följande utdata visas.

    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

    Följande utdata visas.

    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

Se även