Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Cmdlets kunnen niet-afsluitfouten melden door de methode System.Management.Automation.Cmdlet.WriteError aan te roepen en nog steeds te blijven werken op het huidige invoerobject of op verdere binnenkomende pijplijnobjecten. In deze sectie wordt uitgelegd hoe u een cmdlet maakt die niet-afsluitfouten rapporteert op basis van de invoerverwerkingsmethoden.
Voor niet-afsluitfouten (evenals afsluitfouten) moet de cmdlet een System.Management.Automation.ErrorRecord doorgeven object waarmee de fout wordt geïdentificeerd. 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 opsomming. De gebruiker kan fouten weergeven op basis van hun categorie door de $ErrorView variabele in te stellen op CategoryView.
Zie Windows PowerShell-foutrecordsvoor meer informatie over foutrecords.
De cmdlet definiëren
De eerste stap bij het maken van de cmdlet is altijd de naamgeving van de cmdlet en het declareren van de .NET-klasse die de cmdlet implementeert. Deze cmdlet haalt procesgegevens op, dus de werkwoordnaam die hier is gekozen, is 'Get'. (Bijna elk type cmdlet waarmee informatie kan worden opgehaald, kan opdrachtregelinvoer verwerken.) Zie Cmdlet Verb Namesvoor meer informatie over goedgekeurde cmdlet-werkwoorden.
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. Deze Get-Proc cmdlet definieert een parameter Name zoals beschreven in Parameters toevoegen die Command-Line Invoerverwerken.
Hier volgt de parameterdeclaratie voor de parameter Name van deze 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 System.Management.Automation.Cmdlet klasse overschrijven. Deze methoden worden besproken in Uw eerste cmdlet maken.
Notitie
Uw cmdlet moet elke record zo onafhankelijk mogelijk verwerken.
Deze Get-Proc cmdlet overschrijft de methode System.Management.Automation.Cmdlet.ProcessRecord voor het afhandelen van de parameter Name voor invoer die door de gebruiker of een script wordt geleverd. Met deze methode worden de processen voor elke aangevraagde procesnaam of alle processen opgevraagd als er geen naam is opgegeven. Details van deze onderdrukking worden gegeven in Uw eerste cmdlet maken.
Dingen die u moet onthouden bij het rapporteren van fouten
Het System.Management.Automation.ErrorRecord-object dat door de cmdlet wordt doorgegeven bij het schrijven van een fout, 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 deze uitzondering gebruiken of afleiden. Anders moet deze een nieuwe uitzonderings- of uitzonderingshiërarchie rechtstreeks afleiden uit de klasse System.Exception.
Houd bij het maken van fout-id's (toegankelijk via de eigenschap FullyQualifiedErrorId van de klasse ErrorRecord) rekening met het volgende.
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 als volgt zijn.
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 tijdens inspectie kan worden geparseerd. Hierdoor kunt u de onderdelen van de fout-id en de fout-id en foutcategorie vertakken.
De cmdlet moet specifieke fout-id's toewijzen aan verschillende codepaden. Houd rekening met de volgende informatie voor het toewijzen van fout-id's:
- Een fout-id moet gedurende de levenscyclus van de cmdlet constant blijven. Wijzig de semantiek van een fout-id tussen cmdlet-versies niet.
- Gebruik tekst voor een fout-id die tersely overeenkomt met de fout die wordt gerapporteerd. Gebruik geen spatie of leestekens.
- Laat uw cmdlet alleen fout-id's 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.
Niet-verwerkte uitzonderingen worden niet onderschept door PowerShell in de volgende voorwaarden:
- Als een cmdlet een nieuwe thread maakt en code die in die thread wordt uitgevoerd, een onverwerkte uitzondering genereert, treedt de fout niet op in PowerShell en wordt het proces beëindigd.
- Als een object code bevat in de destructor- of verwijderingsmethoden die een niet-verwerkte uitzondering veroorzaken, wordt de fout niet onderschekt en wordt het proces beëindigd.
Niet-afsluitfouten rapporteren
Een van de invoerverwerkingsmethoden kan een niet-afsluitfout rapporteren aan de uitvoerstroom met behulp van de methode System.Management.Automation.Cmdlet.WriteError.
Hier volgt een codevoorbeeld van deze Get-Proc cmdlet die de aanroep van System.Management.Automation.Cmdlet.WriteError illustreert vanuit de onderdrukking van de methode System.Management.Automation.Cmdlet.ProcessRecord. In dit geval wordt de aanroep uitgevoerd 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 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
}
Dingen die u moet onthouden over het schrijven van niet-afsluitfouten
Voor een niet-afsluitfout 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-afsluitfout. Dit kan door de parameters ErrorAction en ErrorVariable te definiëren. Als u de parameter ErrorAction definieert, bevat de cmdlet de gebruikersopties System.Management.Automation.ActionPreference, kunt u de actie ook rechtstreeks beïnvloeden door de $ErrorActionPreference variabele in te stellen.
De cmdlet kan niet-afsluitfouten opslaan in een variabele met behulp van de parameter ErrorVariable, die niet wordt beïnvloed door de instelling van ErrorAction. Fouten kunnen worden toegevoegd aan een bestaande foutvariabele door een plusteken (+) toe te voegen aan de voorzijde van de naam van de variabele.
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 door een andere cmdlet wordt geleverd. Zie Objecttypen en Opmaak uitbreidenvoor 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 registreren bij Windows PowerShell via een Windows PowerShell-module. Zie Cmdlets, providers en hosttoepassingen registrerenvoor 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-Get-Proc cmdlet testen om te zien of er een fout wordt gerapporteerd:
Start PowerShell en gebruik de Get-Proc cmdlet 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
Met ons samenwerken op GitHub
De bron voor deze inhoud vindt u op GitHub, waar u ook problemen en pull-aanvragen kunt maken en controleren. Bekijk onze gids voor inzenders voor meer informatie.
