Rapportage aan uw cmdlet toevoegen voor fouten die niet leiden tot de beëindiging van een functie of bewerking
Cmdlets kunnen niet-beëindigingsfouten rapporteren door de methode System.Management.Automation.Cmdlet.WriteError aan te roepen en nog steeds te werken op het huidige invoerobject of op verdere binnenkomende pijplijnobjecten. In deze sectie wordt uitgelegd hoe u een cmdlet maakt die niet-beëindigingsfouten rapporteert op basis van de invoerverwerkingsmethoden.
Voor niet-beëindigingsfouten (evenals beëindigingsfouten) moet de cmdlet een System.Management.Automation.ErrorRecord-object doorgeven dat de fout identificeert. Elke foutrecord wordt geïdentificeerd door een unieke tekenreeks met de naam 'fout-id'. Naast de id wordt de categorie van elke fout opgegeven door constanten die zijn gedefinieerd door een System.Management.Automation.ErrorCategory-optelling. De gebruiker kan fouten weergeven op basis van de categorie door de variabele $ErrorView in te stellen op CategoryView.
Zie voor meer informatie over foutrecords Windows PowerShell Foutrecords.
De cmdlet definiëren
De eerste stap bij het maken van de cmdlet is het altijd benoemen van de cmdlet en het declareren van de .NET-klasse die de cmdlet implementeert. Met deze cmdlet worden procesgegevens opgehaald, dus de hier gekozen werkwoordnaam is 'Ophalen'. (Bijna elk soort cmdlet waarmee informatie kan worden opgehaald, kan opdrachtregelinvoer verwerken.) Zie cmdlet werkwoordnamen voor meer informatie over goedgekeurde cmdlet-woorden.
Hier volgt de definitie voor deze Get-Proc cmdlet. Details van deze definitie worden gegeven in Uw eerste cmdlet maken.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Parameters definiëren
Indien nodig moet uw cmdlet parameters definiëren voor het verwerken van invoer. Met Get-Proc cmdlet definieert u een naamparameter zoals beschreven in Parameters toevoegen die Command-Line verwerken.
Hier is de parameterdeclaratie voor de parameter Name van Get-Proc cmdlet.
[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
Invoerverwerkingsmethoden overschrijven
Alle cmdlets moeten ten minste één van de invoerverwerkingsmethoden van de klasse System.Management.Automation.Cmdlet overschrijven. Deze methoden worden besproken in Uw eerste cmdlet maken.
Notitie
Uw cmdlet moet elke record zo onafhankelijk mogelijk verwerken.
Met Get-Proc cmdlet overschrijven we de methode System.Management.Automation.Cmdlet.ProcessRecord om de parameter Name te verwerken voor invoer van de gebruiker of een script. Met deze methode worden de processen voor elke aangevraagde procesnaam of alle processen opgevraagd als er geen naam is opgegeven. Details van deze overschrijven worden gegeven in Uw eerste cmdlet maken.
Dingen om te onthouden bij het rapporteren van fouten
Het System.Management.Automation.ErrorRecord-object dat de cmdlet doorstaat wanneer er een fout wordt geschreven, vereist een uitzondering in de kern. Volg de .NET-richtlijnen bij het bepalen van de te gebruiken uitzondering. Als de fout semantisch hetzelfde is als een bestaande uitzondering, moet de cmdlet die uitzondering gebruiken of ervan afleiden. Anders moet er rechtstreeks vanuit de klasse System.Exception een nieuwe uitzonderings- of uitzonderingshiërarchie worden afgeleid.
Houd rekening met het volgende bij het maken van fout-id's (toegankelijk via de eigenschap FullyQualifiedErrorId van de klasse ErrorRecord).
Gebruik tekenreeksen die zijn bedoeld voor diagnostische doeleinden, zodat u bij het inspecteren van de volledig gekwalificeerde id kunt bepalen wat de fout is en waar de fout vandaan komt.
Een goed gevormde volledig gekwalificeerde fout-id kan er als volgt uit zien.
CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand
U ziet dat in het vorige voorbeeld de fout-id (het eerste token) aangeeft wat de fout is en het resterende deel aangeeft waar de fout vandaan komt.
- Voor complexere scenario's kan de fout-id een door punt gescheiden token zijn dat bij inspectie kan worden geparseerd. Hierdoor kunt u te vertakken op de onderdelen van de fout-id, evenals de fout-id en foutcategorie.
De cmdlet moet specifieke fout-id's toewijzen aan verschillende codepaden. Houd rekening met de volgende informatie voor de toewijzing van fout-id's:
- Een fout-id moet constant blijven gedurende de levenscyclus van de cmdlet. Wijzig de semantiek van een fout-id tussen cmdlet-versies niet.
- Gebruik tekst voor een fout-id die overeenkomt met de fout die wordt gerapporteerd. Gebruik geen witruimte of leestekens.
- Uw cmdlet alleen fout-id's laten genereren die reproduceerbaar zijn. Er mag bijvoorbeeld geen id worden gegenereerd die een proces-id bevat. Fout-id's zijn alleen nuttig voor een gebruiker wanneer ze overeenkomen met id's die worden gezien door andere gebruikers die hetzelfde probleem ondervinden.
Onverhandelde uitzonderingen worden niet door PowerShell in de volgende voorwaarden af vangen:
- Als een cmdlet een nieuwe thread maakt en code die wordt uitgevoerd in die thread een onverhandelde uitzondering veroorzaakt, zal PowerShell de fout niet ondervangen en wordt het proces beëindigd.
- Als een object code bevat in de destructor- of verwijderingsmethoden die een onverhandelde uitzondering veroorzaken, zal PowerShell de fout niet ondervangen en wordt het proces beëindigd.
Niet-beëindigingsfouten rapporteren
Een van de invoerverwerkingsmethoden kan een niet-beëindigingsfout rapporteren aan de uitvoerstroom met behulp van de methode System.Management.Automation.Cmdlet.WriteError.
Hier ziet u een codevoorbeeld van deze cmdlet Get-Proc waarmee de aanroep van System.Management.Automation.Cmdlet.WriteError vanuit de override van de system.Management.Automation.Cmdlet.ProcessRecord-methode wordt geïllustreerd. In dit geval wordt de aanroep gedaan als de cmdlet geen proces voor een opgegeven proces-id kan vinden.
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
}
Dingen om te onthouden over het schrijven van niet-beëindigingsfouten
Voor een niet-beëindigingsfout moet de cmdlet een specifieke fout-id genereren voor elk specifiek invoerobject.
Een cmdlet moet vaak de PowerShell-actie wijzigen die wordt geproduceerd door een niet-beëindigingsfout. U kunt dit doen door de parameters ErrorAction en te ErrorVariable definiëren. Als u de parameter definieert, geeft de cmdlet de gebruikersopties ErrorAction System.Management.Automation.ActionPreferenceweer. U kunt de actie ook rechtstreeks beïnvloeden door de variabele in te $ErrorActionPreference stellen.
De cmdlet kan niet-beëindigingsfouten opslaan in een variabele met behulp van de parameter , die ErrorVariable niet wordt beïnvloed door de instelling van ErrorAction . Fouten kunnen worden toegevoegd aan een bestaande foutvariabele door een plusteken (+) aan de voorkant van de variabelenaam toe te voegen.
Codevoorbeeld
Zie GetProcessSample04 Samplevoor de volledige C#-voorbeeldcode.
Objecttypen en -opmaak definiëren
PowerShell geeft informatie door tussen cmdlets met behulp van .NET-objecten. Daarom moet een cmdlet mogelijk een eigen type definiëren, of moet de cmdlet mogelijk een bestaand type uitbreiden dat wordt geleverd door een andere cmdlet. Zie Extending Object Types and Formatting (Objecttypen uitbreiden en opmaak) voor meer informatie over het definiëren van nieuwe typen of het uitbreiden van bestaande typen.
De cmdlet bouwen
Nadat u een cmdlet hebt geïmplementeerd, moet u deze Windows PowerShell via Windows PowerShell module. Zie Cmdlets, providers en hosttoepassingen registreren voor meer informatie over het registreren van cmdlets.
De cmdlet testen
Wanneer uw cmdlet is geregistreerd bij PowerShell, kunt u deze testen door deze uit te voeren op de opdrachtregel. We gaan de voorbeeld-cmdlet Get-Proc om te zien of er een fout wordt weergegeven:
Start PowerShell en gebruik de cmdlet Get-Proc om de processen met de naam TEST op te halen.
get-proc -name testDe volgende uitvoer wordt weergegeven.
get-proc : Operation is not valid due to the current state of the object. At line:1 char:9 + get-proc <<<< -name test
Zie ook
Parameters toevoegen die pijplijninvoer verwerken
Parameters toevoegen die de invoer Command-Line verwerken
Objecttypen en -opmaak uitbreiden
Cmdlets, providers en hosttoepassingen registreren