Megszakítást nem okozó hibajelentések hozzáadása a parancsmaghoz

A parancsmagok a System.Management.Automation.Cmdlet.WriteError metódus meghívásával jelenthetnek nem végződő hibákat, és továbbra is az aktuális bemeneti objektumon vagy további bejövő folyamatobjektumokon működnek tovább. Ez a szakasz bemutatja, hogyan hozhat létre olyan parancsmagot, amely a bemeneti feldolgozási módszerek nem végződő hibáit jelenti.

A nem végződő hibák (valamint a hibák megszüntetése) esetén a parancsmagnak át kell adnia egy System.Management.Automation.ErrorRecord objektumot, amely azonosítja a hibát. Minden hibarekordot egy "hibaazonosító" nevű egyedi sztring azonosít. Az azonosítón kívül az egyes hibák kategóriáját egy System.Management.Automation.ErrorCategory enumerálás által meghatározott állandók határozzák meg. A felhasználó a kategória alapján tekintheti meg a hibákat, ha a $ErrorView változót "CategoryView" értékre állítja.

További információ a hibarekordokról: Windows PowerShell hibarekordok.

A parancsmag definiálása

A parancsmag létrehozásának első lépése mindig a parancsmag elnevezése és a parancsmagot implementáló .NET-osztály deklarálása. Ez a parancsmag lekéri a folyamatadatokat, így az itt kiválasztott ige neve "Get". (Szinte bármilyen parancsmag, amely képes adatokat beolvasni, képes feldolgozni a parancssori bemenetet.) A jóváhagyott parancsmag-parancsmagokkal kapcsolatos további információkért lásd parancsmagok parancsmagjának nevei.

A Get-Proc parancsmag definíciója a következő. Ennek a definíciónak a részleteit az Az első parancsmag létrehozásacímű cikkben találja.

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

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

Paraméterek definiálása

Szükség esetén a parancsmagnak paramétereket kell meghatároznia a bemenet feldolgozásához. Ez a Get-Proc parancsmag egy Név paramétert határoz meg az BemenetiCommand-Line paraméterek hozzáadása című cikkben leírtak szerint.

Itt található a Get-Proc parancsmag Név paraméterének paraméterdeklarációja.

[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

Bemeneti feldolgozási módszerek felülírása

Minden parancsmagnak felül kell bírálnia a System.Management.Automation.Cmdlet osztály által biztosított bemeneti feldolgozási módszerek legalább egyikét. Ezeket a metódusokat Az első parancsmag létrehozásacímű témakörben tárgyaljuk.

Megjegyzés

A parancsmagnak a lehető leg függetlenül kell kezelnie az egyes rekordokat.

Ez a Get-Proc parancsmag felülbírálja a System.Management.Automation.Cmdlet.ProcessRecord metódust a Név paraméter kezeléséhez a felhasználó vagy egy szkript által megadott bemenethez. Ez a metódus lekéri a folyamatokat az egyes kért folyamatnevekhez vagy az összes folyamathoz, ha nincs megadva név. A felülbírálás részleteit Az első parancsmag létrehozásacímű cikkben találja.

Fontos tudnivalók a hibák jelentésekor

A System.Management.Automation.ErrorRecord objektum, amelyet a parancsmag a hiba írásakor ad át, kivételt igényel a magjában. A használandó kivétel meghatározásakor kövesse a .NET-irányelveket. Alapvetően, ha a hiba szemantikailag megegyezik egy meglévő kivétellel, a parancsmagnak ebből a kivételből kell származnia. Ellenkező esetben az új kivétel- vagy kivételhierarchiát közvetlenül a System.Exception osztályból kell származtatnia.

A hibaazonosítók létrehozásakor (az ErrorRecord osztály TeljesképűErrorId tulajdonságán keresztül érhető el) tartsa szem előtt az alábbiakat.

• Diagnosztikai célokat szolgáló sztringeket használjon, így a teljes azonosító vizsgálatakor meghatározhatja, hogy mi a hiba, és honnan származik a hiba.

• A jól formázott, teljesen minősített hibaazonosító a következő lehet.

  CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

Figyelje meg, hogy az előző példában a hibaazonosító (az első jogkivonat) meghatározza, hogy mi a hiba, a fennmaradó rész pedig azt jelzi, hogy honnan származik a hiba.

• Összetettebb forgatókönyvek esetén a hibaazonosító egy ponttal elválasztott jogkivonat lehet, amely az ellenőrzés során elemezhető. Így túl elágazhat a hibaazonosító részein, valamint a hibaazonosítón és a hibakategórián.

A parancsmagnak adott hibaazonosítókat kell hozzárendelnie különböző kódútvonalakhoz. A hibaazonosítók hozzárendeléséhez tartsa szem előtt az alábbi információkat:

• A hibaazonosítónak a parancsmag teljes életciklusa során állandónak kell maradnia. Ne módosítsa a parancsmagverziók közötti hibaazonosító szemantikáját.
• Használjon szöveget olyan hibaazonosítóhoz, amely megfelel a jelentett hibának. Ne használjon szóközt vagy írásjelet.
• A parancsmag csak reprodukálható hibaazonosítókat hozzon létre. Például nem hozhat létre olyan azonosítót, amely folyamatazonosítót tartalmaz. A hibaazonosítók csak akkor hasznosak a felhasználók számára, ha megfelelnek az azonos problémát tapasztaló más felhasználók által látott azonosítóknak.

A PowerShell nem kezeletlen kivételeket kap a következő feltételek mellett:

• Ha egy parancsmag létrehoz egy új szálat, és a szálon futó kód kezeletlen kivételt okoz, a PowerShell nem fogja elkapni a hibát, és leállítja a folyamatot.
• Ha egy objektum kóddal rendelkezik a destruktorában, vagy a nem kezelt kivételt okozó törlési metódusokkal rendelkezik, a PowerShell nem fogja elkapni a hibát, és leállítja a folyamatot.

Nem végződő hibák jelentése

A bemeneti feldolgozási módszerek bármelyike jelenthet egy nem végződő hibát a kimeneti adatfolyamnak a System.Management.Automation.Cmdlet.WriteError metódussal.

Íme egy példa erre a Get-Proc parancsmagra, amely a System.Management.Automation.Cmdlet.WriteError hívását mutatja be a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálásán belül. Ebben az esetben a hívás akkor történik, ha a parancsmag nem talál egy folyamatot egy megadott folyamatazonosítóhoz.

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
  }

Tudnivalók a nem megszüntető hibák írásáról

Nem végződő hiba esetén a parancsmagnak minden egyes bemeneti objektumhoz létre kell hoznia egy adott hibaazonosítót.

A parancsmagnak gyakran módosítania kell a nem végződő hiba által létrehozott PowerShell-műveletet. Ezt a ErrorAction és ErrorVariable paraméterek megadásával teheti meg. Ha a ErrorAction paramétert definiálja, a parancsmag a System.Management.Automation.ActionPreference felhasználói beállításokat jeleníti meg, közvetlenül is befolyásolhatja a műveletet a $ErrorActionPreference változó beállításával.

A parancsmag mentheti a nem végződő hibákat egy változóba a ErrorVariable paraméter használatával, amelyet a ErrorActionbeállítása nem érint. A hibák hozzáfűzhetők egy meglévő hibaváltozóhoz egy pluszjel (+) hozzáadásával a változó neve elé.

Kódminta

A teljes C#-mintakódért lásd GetProcessSample04 Minta.

Objektumtípusok és formázás definiálása

A PowerShell .NET-objektumokkal továbbítja az adatokat a parancsmagok között. Következésképpen előfordulhat, hogy egy parancsmagnak meg kell határoznia a saját típusát, vagy előfordulhat, hogy a parancsmagnak ki kell terjesztenie egy másik parancsmag által biztosított meglévő típust. További információ az új típusok definiálásáról vagy a meglévő típusok kibővítéséről: Objektumtípusok és formázás kiterjesztése.

A parancsmag létrehozása

A parancsmag implementálása után regisztrálnia kell azt a Windows PowerShellben egy Windows PowerShell beépülő modulon keresztül. A parancsmagok regisztrálásáról további információt a parancsmagok, szolgáltatók és gazdagépalkalmazások .

A parancsmag tesztelése

Ha a parancsmag regisztrálva lett a PowerShellben, a parancssorban futtatva tesztelheti. Teszteljük a minta Get-Proc parancsmagot, és nézzük meg, hogy hibajelentést jelent-e:

• Indítsa el a PowerShellt, és használja a Get-Proc parancsmagot a "TEST" nevű folyamatok lekéréséhez.

  Get-Proc -Name test
  

  Megjelenik a következő kimenet.

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

Lásd még:

• Folyamatbemenetet feldolgozó paraméterek hozzáadása

• Bemeneti Command-Line feldolgozó paraméterek hozzáadása

• Az első parancsmag létrehozása

• Objektumtípusok és formázás kiterjesztése

• Parancsmagok, szolgáltatók és gazdagépalkalmazások regisztrálása

• Windows PowerShell-referencia

• parancsmagminták