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

Artikel
09/24/2021

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

För att icke-fastställa 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 uppräkning av System.Management.Automation.ErrorCategory. Användaren kan visa fel baserat på deras kategori genom att ange $ErrorView variabeln till "CategoryView".

Mer information om felposter finns i Windows PowerShell felposter.

Definiera cmdleten

Det första steget i att skapa cmdleten är att alltid namnge cmdleten och deklarera den .NET-klass som implementerar cmdleten . Den här cmdleten hämtar processinformation, så verbnamnet som väljs här är "Get". (Nästan alla slags cmdlet 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 denna Get-Proc cmdlet. 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

Om det behövs måste cmdleten definiera parametrar för bearbetning av indata. Den Get-Proc cmdleten definierar en Name-parameter enligt beskrivningen i 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ätta metoder för indatabearbetning

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

Anteckning

Din cmdlet bör hantera varje post så oberoende som möjligt.

Den Get-Proc cmdleten åsidosätter metoden System.Management.Automation.Cmdlet.ProcessRecord för att hantera name-parametern 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 ett fel skrivs kräver ett undantag i grunden. Följ .NET-riktlinjerna när du fastställer vilket undantag som ska användas. Om felet är semantiskt samma 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 (nås via egenskapen FullyQualifiedErrorId för klassen ErrorRecord).

Använd strängar som är riktade i diagnostiskt syfte så att du när du inspekterar den fullständigt kvalificerade identifieraren kan avgöra vad felet är och var felet kom från.
En väl utformad 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 från.

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

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

En felidentifierare bör vara konstant under cmdlet-livscykeln. Ändra inte semantiken för en felidentifierare mellan cmdlet-versioner.
Använd text för en felidentifierare som tersely motsvarar felet som rapporteras. Använd inte blanksteg eller skiljetecken.
Se till att din cmdlet endast genererar felidentifierare som kan återskapas. Den bör till exempel inte generera en identifierare som innehåller en processidentifierare. Felidentifierare är bara användbara för användare när de motsvarar identifierare som andra användare upplever samma problem.

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

Om en cmdlet skapar en ny tråd och kod som körs i tråden kastar ett ohanterat undantag, kommer PowerShell inte att fånga felet och avslutar processen.
Om ett objekt har kod i sin destructor eller ta bort metoder som orsakar ett ohanterat undantag, kommer PowerShell inte att fånga felet och avslutar processen.

Rapportera obestämda fel

Vilken som helst av indatabearbetningsmetoderna kan rapportera ett obestämd 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 Metoden System.Management.Automation.Cmdlet.WriteError i å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 nonterminating 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-obestämda fel

För ett obestämd fel måste cmdleten generera en specifik felidentifierare för varje specifikt indataobjekt.

En cmdlet behöver ofta ändra PowerShell-åtgärden som produceras av ett obestämd fel. Det kan du göra genom att definiera ErrorAction ErrorVariable parametrarna och . Om du definierar parametern visar cmdleten användaralternativen ErrorAction System.Management.Automation.ActionPreference. Du kan också påverka åtgärden direkt genom att ange $ErrorActionPreference variabeln .

Cmdleten kan spara obestämda fel till en variabel med hjälp av parametern , som ErrorVariable 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 (+) längst fram i variabelnamnet.

Kodexempel

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

Definiera objekttyper och formatering

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 du registrera den med Windows PowerShell en Windows PowerShell snapin-modulen. Mer information om hur du registrerar cmdlets finns i How to Register Cmdlets, Providers, and Host Applications.

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 Get-Proc cmdleten för att se om den 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 cmdlets, providers och värdprogram

Windows PowerShell-referens

Cmdlet-exempel

Share via