Přidání zasílání zpráv o neukončujících chybách do rutiny
Rutiny můžou hlásit neukončující chyby voláním metody System.Management.Automation.Automation.WriteError a nadále pracovat s aktuálním vstupním objektem nebo dalšími příchozími objekty kanálu. Tato část vysvětluje, jak vytvořit rutinu, která hlásí neukončující chyby z metod zpracování vstupu.
V případě neukončujících chyb (i ukončovaných chyb) musí rutina předat System.Management.Automation.ErrorRecord objekt identifikující chybu. Každý záznam chyby je identifikován jedinečným řetězcem označovaným jako "identifikátor chyby". Kromě identifikátoru je kategorie každé chyby určena konstantami definovanými System.Management.Automation.ErrorCategory výčtu. Uživatel může zobrazit chyby na základě jejich kategorie nastavením proměnné $ErrorView na CategoryView.
Další informace o záznamech chyb najdete v tématu Záznamy chyb prostředí Windows PowerShell.
Definování rutiny
Prvním krokem při vytváření rutin je vždy pojmenování rutiny a deklarování třídy .NET, která tuto rutinu implementuje. Tato rutina načte informace o procesu, takže zde zvolený název příkazu je Get. (Téměř jakýkoli druh rutiny, která dokáže načíst informace, může zpracovat vstup příkazového řádku.) Další informace o schválených rutinách naleznete v tématu Názvy příkazů rutin.
Následuje definice této rutiny Get-Proc. Podrobnosti o této definici jsou uvedeny v Vytvoření první rutiny.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Definování parametrů
V případě potřeby musí vaše rutina definovat parametry pro zpracování vstupu. Tato rutina Get-Proc definuje parametr Name, jak je popsáno v Přidání parametrů, které zpracovávají Command-Line vstupní.
Tady je deklarace parametru pro parametr Name této rutiny Get-Proc.
[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
Přepsání metod zpracování vstupu
Všechny rutiny musí přepsat alespoň jednu z metod zpracování vstupu, které poskytuje třída System.Management.Automation.Cmdlet. Tyto metody jsou popsány v Vytvoření první rutiny.
Poznámka:
Rutina by měla zpracovávat každý záznam co nejstranněji.
Tato rutina Get-Proc přepíše metodu System.Management.Automation.Automation.ProcessRecord pro zpracování parametru Název pro vstup poskytnutý uživatelem nebo skriptem. Tato metoda získá procesy pro každý požadovaný název procesu nebo všechny procesy, pokud není zadaný žádný název. Podrobnosti o tomto přepsání jsou uvedeny v Vytvoření první rutiny.
Co je potřeba pamatovat při hlášení chyb
System.Management.Automation.ErrorRecord objekt, který rutina předává při zápisu chyby, vyžaduje výjimku v jejím jádru. Při určování výjimky, která se má použít, postupujte podle pokynů .NET. V podstatě platí, že pokud je chyba sémanticky stejná jako existující výjimka, měla by rutina použít nebo odvodit z této výjimky. Jinak by měla odvodit novou výjimku nebo hierarchii výjimek přímo z třídy System.Exception.
Při vytváření identifikátorů chyb (přístup prostřednictvím FullyQualifiedErrorId vlastnost ErrorRecord třídy) mějte na paměti následující.
Používejte řetězce cílené pro účely diagnostiky, aby při kontrole plně kvalifikovaného identifikátoru bylo možné určit, co je chyba a odkud chyba pochází.
Plně kvalifikovaný identifikátor chyby ve správném formátu může být následující.
CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand
Všimněte si, že v předchozím příkladu identifikátor chyby (první token) určuje, co je chyba, a zbývající část označuje, odkud chyba pochází.
- V případě složitějších scénářů může identifikátor chyby být tečkovaným tokenem odděleným tečkou, který je možné analyzovat při kontrole. To vám umožní také větvet části identifikátoru chyby a také identifikátor chyby a kategorii chyb.
Rutina by měla přiřadit konkrétní identifikátory chyb různým cestám kódu. Při přiřazování identifikátorů chyb mějte na paměti následující informace:
- Identifikátor chyby by měl zůstat konstantní v průběhu životního cyklu rutiny. Neměňte sémantiku identifikátoru chyby mezi verzemi rutin.
- Použijte text pro identifikátor chyby, který tersely odpovídá nahlášené chybě. Nepoužívejte prázdné znaky ani interpunkci.
- Požádejte rutinu, aby vygenerovala pouze identifikátory chyb, které jsou reprodukovatelné. Neměl by například generovat identifikátor, který obsahuje identifikátor procesu. Identifikátory chyb jsou užitečné pro uživatele pouze v případě, že odpovídají identifikátorům, které vidí jiní uživatelé se stejným problémem.
Neošetřené výjimky nezachytí PowerShell v následujících podmínkách:
- Pokud rutina vytvoří nové vlákno a kód spuštěný v daném vlákně vyvolá neošetřenou výjimku, PowerShell chybu nezachytí a proces ukončí.
- Pokud objekt obsahuje kód v jeho destruktoru nebo Dispose metody, které způsobí neošetřenou výjimku, PowerShell chybu nezachytí a proces ukončí.
Hlášení neukončujících chyb
Jakákoli z metod zpracování vstupu může nahlásit neukončující chybu výstupního datového proudu pomocí metody System.Management.Automation.Cmdlet.WriteError.
Tady je příklad kódu z této rutiny Get-Proc, která znázorňuje volání System.Management.Automation.Automation.WriteError z přepsání System.Management.Automation.Cmdlet.ProcessRecord metoda. V takovém případě je volání provedeno, pokud rutina nemůže najít proces pro zadaný identifikátor procesu.
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
}
Co je potřeba pamatovat na psaní neukončujících chyb
V případě neukončující chyby musí rutina pro každý konkrétní vstupní objekt vygenerovat konkrétní identifikátor chyby.
Rutina často potřebuje upravit akci PowerShellu vytvořenou neukončující chybou. To lze provést definováním parametrů ErrorAction a ErrorVariable. Pokud definujete parametr ErrorAction, rutina zobrazí možnosti uživatele System.Management.Automation.ActionPreference, můžete také přímo ovlivnit akci nastavením proměnné $ErrorActionPreference.
Rutina může uložit neukončující chyby do proměnné pomocí parametru ErrorVariable, který není ovlivněn nastavením ErrorAction. Selhání je možné připojit k existující chybové proměnné přidáním znaménka plus (+) před název proměnné.
Ukázka kódu
Úplný vzorový kód jazyka C# najdete v tématu GetProcessSample04 Sample.
Definování typů objektů a formátování
PowerShell předává informace mezi rutinami pomocí objektů .NET. Proto může být potřeba, aby rutina definovala vlastní typ, nebo může být potřeba rozšířit existující typ poskytovaný jinou rutinou. Další informace o definování nových typů nebo rozšíření existujících typů naleznete v tématu Rozšíření typů objektů a formátování.
Sestavení rutiny
Po implementaci rutiny ji musíte zaregistrovat ve Windows PowerShellu prostřednictvím modulu snap-in Prostředí Windows PowerShell. Další informace o registraci rutin naleznete v tématu Postup registrace rutin, poskytovatelů a hostitelských aplikací.
Testování rutiny
Když je rutina zaregistrovaná v PowerShellu, můžete ji otestovat spuštěním na příkazovém řádku. Pojďme ukázkovou Get-Proc rutinu otestovat a zjistit, jestli hlásí chybu:
Spusťte PowerShell a pomocí rutiny Get-Proc načtěte procesy s názvem TEST.
Get-Proc -Name testZobrazí se následující výstup.
Get-Proc : Operation is not valid due to the current state of the object. At line:1 char:9 + Get-Proc <<<< -Name test
