Lägga till användarmeddelanden i en cmdlet

Cmdletar 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 håller på att utföra en åtgärd som kan få oväntade resultat.

• Statusrapporteringsmeddelanden som innehåller information om hur mycket arbete cmdleten har slutfört när du utför en åtgärd som tar lång tid.

Det finns inga gränser för antalet meddelanden som cmdleten kan skriva eller vilken typ av meddelanden som cmdleten skriver. Varje meddelande skrivs genom att göra ett specifikt anrop inifrån indatabearbetningsmetoden för din cmdlet.

Definiera cmdleten

Det första steget när cmdleten skapas är att alltid namnge cmdleten och deklarera .NET-klassen som implementerar cmdleten. Alla typer av cmdletar kan skriva användarmeddelanden från sina indatabearbetningsmetoder. Så i allmänhet kan du namnge den här cmdleten med valfritt verb som anger vilka systemändringar cmdleten utför. Mer information om godkända cmdlet-verb finns i Cmdlet-verbnamn.

Cmdleten Stop-Proc är utformad för att ändra systemet. Därför måste System.Management.Automation.CmdletAttribute-deklarationen för .NET-klassen innehålla nyckelordet SupportsShouldProcess attribut och anges till 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 system.

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

Definiera parametrar för systemändring

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

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

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

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

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 hur cmdleten fungerar. Anropet görs från en indatabearbetningsmetod.

Följande två kodavsnitt från exempel-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 metodanropen spåras till värdprogrammet, en fil eller ett felsökningsprogram utan att du behöver utfö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 anteckningar

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 cmdleten sample Stop-Proc 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 återgivning till användaren.

Följande kod är ett exempel på ett förloppsmeddelande skrivet 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 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.

• 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.
  

Se även

Skapa en cmdlet som ändrar systemets

Skapa en Windows PowerShell-cmdlet

utöka objekttyper och formatering

Registrera cmdletar, leverantörer och värdprogram

Windows PowerShell SDK