Lägga till användarmeddelanden i en cmdlet

Artikel
09/24/2021
5 minuter för att läsa

Cmdlets kan skriva flera typer av meddelanden som kan visas för användaren av Windows PowerShell körningen. Dessa meddelanden innehåller följande typer:

Utförliga meddelanden som innehåller allmän användarinformation.
Felsöka meddelanden som innehåller felsökningsinformation.
Varningsmeddelanden som innehåller ett meddelande om att cmdleten är på väg att utföra en åtgärd som kan ha oväntade resultat.
Förloppsrapportmeddelanden som innehåller information om hur mycket arbete cmdleten har slutfört när en åtgärd som tar lång tid utförs.

Det finns inga begränsningar för hur många meddelanden din cmdlet kan skriva eller vilken typ av meddelanden som din cmdlet skriver. Varje meddelande skrivs genom att göra ett specifikt anrop inifrån indatabearbetningsmetoden för din cmdlet.

Definiera cmdleten

Det första steget i att skapa cmdleten är att alltid namnge cmdleten och deklarera den .NET-klass som implementerar cmdleten. Alla sorters cmdlet kan skriva användarmeddelanden från sina metoder för bearbetning av indata. i allmänhet kan du namnge denna cmdlet med hjälp av alla verb som anger vilka systemändringar som cmdleten utför. Mer information om godkända cmdlet-verb finns i Cmdlet-verbnamn.

Cmdleten Stop-Proc har utformats för att ändra systemet. Därför måste deklarationen System.Management.Automation.CmdletAttribute för .NET-klassen innehålla SupportsShouldProcess attributet nyckelord och vara inställd på true .

Följande kod är definitionen för den här Stop-Proc cmdlet-klassen. Mer information om den här definitionen finns i Skapa en cmdlet som ändrar systemet.

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

Definiera parametrar för systemändring

Cmdleten Stop-Proc definierar tre parametrar: Name Force , och PassThru . Mer information om hur du definierar dessa parametrar finns i Skapa en cmdlet som ändrar systemet.

Här är parameterdeklarationen för Stop-Proc cmdlet.

[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;

Åsidosätta en metod för indatabearbetning

Din cmdlet måste åsidosätta en indatabearbetningsmetod, oftast är det System.Management.Automation.Cmdlet.ProcessRecord. Den Stop-Proc cmdleten åsidosätter indatabearbetningsmetoden System.Management.Automation.Cmdlet.ProcessRecord. I den här implementeringen Stop-Proc cmdleten görs anrop för att skriva utförliga meddelanden, felsökningsmeddelanden och varningsmeddelanden.

Anteckning

Mer information om hur den här metoden anropar metoderna System.Management.Automation.Cmdlet.ShouldProcess och System.Management.Automation.Cmdlet.ShouldContinue finns i Skapa en cmdletsom ändrar systemet .

Skriva ett utförligt meddelande

Metoden System.Management.Automation.Cmdlet.WriteVerbose används för att skriva allmän information på användarnivå som inte är relaterad till specifika felvillkor. Systemadministratören kan sedan använda den informationen för att fortsätta bearbeta andra kommandon. Dessutom bör all information som skrivs med den här metoden lokaliseras efter behov.

Följande kod från den här Stop-Proc-cmdleten visar två anrop till metoden System.Management.Automation.Cmdlet.WriteVerbose från åsidosättningen av metoden 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);

Skriva ett felsökningsmeddelande

Metoden System.Management.Automation.Cmdlet.WriteDebug används för att skriva felsökningsmeddelanden som kan användas för att felsöka cmdletens drift. Anropet görs från en bearbetningsmetod för indata.

Anteckning

Windows PowerShell definierar också Debug en parameter som visar både utförlig och felsökningsinformation. Om din cmdlet stöder den här parametern behöver den inte anropa System.Management.Automation.Cmdlet.WriteDebug i samma kod som anropar System.Management.Automation.Cmdlet.WriteVerbose.

Följande två kodavsnitt från Stop-Proc-cmdleten visar anrop till metoden System.Management.Automation.Cmdlet.WriteDebug från åsidosättningen av metoden System.Management.Automation.Cmdlet.ProcessRecord.

Det här felsökningsmeddelandet skrivs omedelbart innan System.Management.Automation.Cmdlet.ShouldProcess anropas.

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

Det här felsökningsmeddelandet skrivs omedelbart innan System.Management.Automation.Cmdlet.WriteObject anropas.

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

Windows PowerShell dirigerar automatiskt alla System.Management.Automation.Cmdlet.WriteDebug-anrop till spårningsinfrastrukturen och cmdletarna. På så sätt kan metodanrop spåras till värdprogrammet, en fil eller ett felsökningsprogram utan att du behöver göra något extra utvecklingsarbete i cmdleten. Följande kommandoradspost implementerar en spårningsåtgärd.

PS> trace-expression stop-proc -file proc.log -command stop-proc notepad

Skriva ett varningsmeddelande

Metoden System.Management.Automation.Cmdlet.WriteWarning används för att skriva en varning när cmdleten är på väg att utföra en åtgärd som kan ha ett oväntat resultat, till exempel skriva över en skrivskyddad fil.

Följande kod från Stop-Proc-cmdleten visar anropet till metoden System.Management.Automation.Cmdlet.WriteWarning från åsidosättningen av metoden System.Management.Automation.Cmdlet.ProcessRecord.

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

Skriva ett förloppsmeddelande

System.Management.Automation.Cmdlet.WriteProgress används för att skriva förloppsmeddelanden när cmdlet-åtgärder tar längre tid att slutföra. Ett anrop till System.Management.Automation.Cmdlet.WriteProgress skickar ett System.Management.Automation.Progressrecord-objekt som skickas till värdprogrammet för rendering till användaren.

Anteckning

Den Stop-Proc cmdleten innehåller inte något anrop till metoden System.Management.Automation.Cmdlet.WriteProgress.

Följande kod är ett exempel på ett förloppsmeddelande som skrivits av en cmdlet som försöker kopiera ett objekt.

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);

Kodexempel

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

Definiera objekttyper och formatering

Windows PowerShell skickar information mellan cmdlets 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 en Windows PowerShell snapin-modulen. Mer information om hur du registrerar cmdlets finns i Registrera cmdlets, providers 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 Stop-Proc cmdlet. Mer information om hur du använder cmdlets från kommandoraden finns i Komma igång med Windows PowerShell.

Följande kommandoradspost använder Stop-Proc för att stoppa processen med namnet "ANTECKNINGAR", tillhandahålla utförliga meddelanden och skriva ut felsökningsinformation.

PS> stop-proc -Name notepad -Verbose -Debug

Följande utdata visas.

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.