Lägga till rapportering av fel som avbryter körningen i en cmdlet

Cmdletar kan rapportera icke-avslutande fel genom att anropa metoden System.Management.Automation.Cmdlet.WriteError och fortfarande fortsätta att fungera på det aktuella indataobjektet eller på ytterligare inkommande pipelineobjekt. I det här avsnittet beskrivs hur du skapar en cmdlet som rapporterar icke-avslutande fel från dess indatabearbetningsmetoder.

För icke-avslutande fel (samt avslutande fel) måste cmdleten skicka ett System.Management.Automation.ErrorRecord objekt som identifierar felet. Varje felpost identifieras av en unik sträng som kallas "felidentifierare". Förutom identifieraren anges kategorin för varje fel av konstanter som definieras av en System.Management.Automation.ErrorCategory uppräkning. Användaren kan visa fel baserat på sin kategori genom att ange variabeln $ErrorView till "CategoryView".

Mer information om felposter finns i Windows PowerShell-felposter.

Definiera cmdleten

Det första steget när cmdleten skapas är att alltid namnge cmdleten och deklarera .NET-klassen som implementerar cmdleten. Den här cmdleten hämtar processinformation, så verbnamnet som väljs här är "Get". (Nästan alla typer av cmdletar som kan hämta information kan bearbeta kommandoradsindata.) Mer information om godkända cmdlet-verb finns i Cmdlet-verbnamn.

Följande är definitionen för den här Get-Proc cmdleten. Information om den här definitionen finns i Skapa din första cmdlet.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Definiera parametrar

Vid behov måste cmdleten definiera parametrar för bearbetning av indata. Den här Get-Proc-cmdleten definierar parametern Name enligt beskrivningen i Add Parameters that Process Command-Line Input.This Get-Proc cmdlet defines a Name parameter as described in Adding Parameters that Process Command-Line Input.

Här är parameterdeklarationen för parametern Name för den här Get-Proc cmdleten.

[Parameter(
           Position = 0,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
[ValidateNotNullOrEmpty]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

<Parameter(Position:=0, ValueFromPipeline:=True, _
ValueFromPipelineByPropertyName:=True), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Åsidosättande indatabearbetningsmetoder

Alla cmdletar måste åsidosätta minst en av de indatabearbetningsmetoder som tillhandahålls av klassen System.Management.Automation.Cmdlet. Dessa metoder beskrivs i Skapa din första cmdlet.

Den här Get-Proc-cmdleten åsidosätter metoden System.Management.Automation.Cmdlet.ProcessRecord för att hantera parametern Name för indata från användaren eller ett skript. Den här metoden hämtar processerna för varje begärt processnamn eller alla processer om inget namn anges. Information om den här åsidosättningen finns i Skapa din första cmdlet.

Saker att komma ihåg när du rapporterar fel

Det System.Management.Automation.ErrorRecord objekt som cmdleten skickar när du skriver ett fel kräver ett undantag i grunden. Följ .NET-riktlinjerna när du fastställer undantaget som ska användas. Om felet är semantiskt detsamma som ett befintligt undantag bör cmdleten använda eller härleda från det undantaget. Annars bör den härleda en ny undantags- eller undantagshierarki direkt från klassen System.Exception.

Tänk på följande när du skapar felidentifierare (som nås via egenskapen FullyQualifiedErrorId för klassen ErrorRecord).

• Använd strängar som är avsedda för diagnostiska ändamål så att du när du inspekterar den fullständigt kvalificerade identifieraren kan avgöra vad felet är och var felet kom ifrån.

• En välformulerad fullständigt kvalificerad felidentifierare kan vara följande.

  CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

Observera att i föregående exempel anger felidentifieraren (den första token) vad felet är och den återstående delen anger var felet kom ifrån.

• För mer komplexa scenarier kan felidentifieraren vara en punktavgränsad token som kan parsas vid inspektion. På så sätt kan du förgrena delar av felidentifieraren samt felidentifieraren och felkategorin.

Cmdleten bör tilldela specifika felidentifierare till olika kodsökvägar. Tänk på följande information för tilldelning av felidentifierare:

• En felidentifierare bör förbli konstant under hela cmdletens livscykel. Ändra inte semantiken för en felidentifierare mellan cmdlet-versioner.
• Använd text för en felidentifierare som tersely motsvarar det fel som rapporteras. Använd inte blanksteg eller skiljetecken.
• Låt din cmdlet endast generera felidentifierare som är reproducerbara. Den bör till exempel inte generera en identifierare som innehåller en processidentifierare. Felidentifierare är endast användbara för en användare när de motsvarar identifierare som visas av andra användare som har samma problem.

Ohanterade undantag fångas inte av PowerShell under följande villkor:

• Om en cmdlet skapar en ny tråd och kod som körs i den tråden genererar ett ohanterat undantag, kommer PowerShell inte att fånga upp felet och avsluta processen.
• Om ett objekt har kod i sina destruktor- eller rensningsmetoder som orsakar ett ohanterat undantag, kommer PowerShell inte att fånga upp felet och avsluta processen.

Rapportera icke-avslutande fel

Någon av metoderna för indatabearbetning kan rapportera ett icke-avslutande fel till utdataströmmen med hjälp av metoden System.Management.Automation.Cmdlet.WriteError.

Här är ett kodexempel från den här Get-Proc-cmdleten som illustrerar anropet till System.Management.Automation.Cmdlet.WriteError inifrån åsidosättningen av metoden System.Management.Automation.Cmdlet.ProcessRecord. I det här fallet görs anropet om cmdleten inte kan hitta en process för en angiven processidentifierare.

protected override void ProcessRecord()
{
  // If no name parameter passed to cmdlet, get all processes.
  if (processNames == null)
  {
    WriteObject(Process.GetProcesses(), true);
  }
    else
    {
      // If a name parameter is passed to cmdlet, get and write
      // the associated processes.
      // Write a non-terminating error for failure to retrieve
      // a process.
      foreach (string name in processNames)
      {
        Process[] processes;

        try
        {
          processes = Process.GetProcessesByName(name);
        }
        catch (InvalidOperationException ex)
        {
          WriteError(new ErrorRecord(
                     ex,
                     "NameNotFound",
                     ErrorCategory.InvalidOperation,
                     name));
          continue;
        }

        WriteObject(processes, true);
      } // foreach (...
    } // else
  }

Saker att komma ihåg om att skriva icke-avslutande fel

För ett icke-avslutande fel måste cmdleten generera en specifik felidentifierare för varje specifikt indataobjekt.

En cmdlet måste ofta ändra PowerShell-åtgärden som genereras av ett fel som inte avslutas. Det kan du göra genom att definiera parametrarna ErrorAction och ErrorVariable. Om du definierar parametern ErrorAction visar cmdleten användaralternativen System.Management.Automation.ActionPreferencekan du också direkt påverka åtgärden genom att ange variabeln $ErrorActionPreference.

Cmdleten kan spara icke-avslutande fel till en variabel med hjälp av parametern ErrorVariable, som inte påverkas av inställningen för ErrorAction. Fel kan läggas till i en befintlig felvariabel genom att lägga till ett plustecken (+) framför variabelnamnet.

Kodexempel

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

Definiera objekttyper och formatering

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 du registrera den 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 PowerShell kan du testa den genom att köra den på kommandoraden. Nu ska vi testa exempel-Get-Proc cmdlet för att se om det rapporterar ett fel:

• Starta PowerShell och använd cmdleten Get-Proc för att hämta processerna med namnet "TEST".

  Get-Proc -Name test
  

  Följande utdata visas.

  Get-Proc : Operation is not valid due to the current state of the object.
  At line:1 char:9
  + Get-Proc  <<<< -Name test
  

Se även

• Lägga till parametrar som bearbetar pipelineindata

• Lägga till parametrar som bearbetar Command-Line indata

• Skapa din första cmdlet

• utöka objekttyper och formatering

• Registrera cmdletar, leverantörer och värdprogram

• Windows PowerShell-referens

• Cmdlet-exempel