Aggiunta di segnalazioni di errori non irreversibili al cmdlet
I cmdlet possono segnalare errori non continui chiamando il metodo System.Management.Automation.Cmdlet.WriteError e continuare a operare sull'oggetto di input corrente o su altri oggetti pipeline in ingresso. In questa sezione viene illustrato come creare un cmdlet che segnala errori non erminanti dai relativi metodi di elaborazione dell'input.
Per gli errori non di terminazione, nonché per gli errori di terminazione, il cmdlet deve passare un oggetto System.Management.Automation.ErrorRecord che identifica l'errore. Ogni record di errore è identificato da una stringa univoca denominata "identificatore errore". Oltre all'identificatore, la categoria di ogni errore viene specificata dalle costanti definite da un'enumerazione System.Management.Automation.ErrorCategory. L'utente può visualizzare gli errori in base alla categoria impostando $ErrorView la variabile su "CategoryView".
Per altre informazioni sui record di errore, vedere Windows PowerShell Error Records.
Definizione del cmdlet
Il primo passaggio nella creazione dei cmdlet consiste sempre nel denominare il cmdlet e dichiarare la classe .NET che implementa il cmdlet. Questo cmdlet recupera le informazioni sul processo, quindi il nome del verbo scelto qui è "Get". Quasi tutti i cmdlet in grado di recuperare informazioni possono elaborare l'input della riga di comando. Per altre informazioni sui verbi dei cmdlet approvati, vedere Nomi dei verbi dei cmdlet.
Di seguito è riportata la definizione per questo Get-Proc cmdlet. I dettagli di questa definizione sono disponibili in Creazione del primo cmdlet.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Definizione dei parametri
Se necessario, il cmdlet deve definire i parametri per l'elaborazione dell'input. Questo cmdlet Get-Proc definisce un parametro Name come descritto in Adding Parameters that Process Command-Line Input.
Ecco la dichiarazione di parametro per il parametro Name di questo cmdlet 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
Override dei metodi di elaborazione dell'input
Tutti i cmdlet devono eseguire l'override di almeno uno dei metodi di elaborazione dell'input forniti dalla classe System.Management.Automation.Cmdlet. Questi metodi sono descritti in Creazione del primo cmdlet.
Nota
Il cmdlet deve gestire ogni record nel modo più indipendente possibile.
Questo cmdlet Get-Proc esegue l'override del metodo System.Management.Automation.Cmdlet.ProcessRecord per gestire il parametro Name per l'input fornito dall'utente o da uno script. Questo metodo otterrà i processi per ogni nome di processo richiesto o per tutti i processi se non viene specificato alcun nome. I dettagli di questo override sono disponibili in Creazione del primo cmdlet.
Aspetti da ricordare quando si segnalano errori
L'oggetto System.Management.Automation.ErrorRecord passato dal cmdlet durante la scrittura di un errore richiede un'eccezione alla base. Seguire le linee guida di .NET per determinare l'eccezione da usare. In pratica, se l'errore è semanticamente uguale a un'eccezione esistente, il cmdlet deve usare o derivare da tale eccezione. In caso contrario, deve derivare una nuova gerarchia di eccezioni o eccezioni direttamente dalla classe System.Exception.
Quando si creano identificatori di errore (a cui si accede tramite la proprietà FullyQualifiedErrorId della classe ErrorRecord), tenere presente quanto segue.
Usare stringhe destinate a scopi diagnostici in modo che, quando si esamina l'identificatore completo, sia possibile determinare qual è l'errore e da dove deriva l'errore.
Un identificatore di errore completo ben formato potrebbe essere il seguente.
CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand
Si noti che nell'esempio precedente l'identificatore di errore (il primo token) definisce l'errore e la parte rimanente indica da dove è stato generato l'errore.
- Per scenari più complessi, l'identificatore di errore può essere un token separato da punti che può essere analizzato durante l'ispezione. In questo modo è possibile creare un ramo anche sulle parti dell'identificatore di errore, nonché sull'identificatore dell'errore e sulla categoria di errore.
Il cmdlet deve assegnare identificatori di errore specifici a percorsi di codice diversi. Tenere presenti le informazioni seguenti per l'assegnazione degli identificatori di errore:
- Un identificatore di errore deve rimanere costante per tutto il ciclo di vita del cmdlet. Non modificare la semantica di un identificatore di errore tra le versioni dei cmdlet.
- Usare il testo per un identificatore di errore che corrisponde in modo esevero all'errore segnalato. Non usare spazi vuoti o punteggiatura.
- Fare in modo che il cmdlet generi solo identificatori di errore riproducibili. Ad esempio, non deve generare un identificatore che include un identificatore di processo. Gli identificatori di errore sono utili per un utente solo quando corrispondono agli identificatori che vengono riscontrati da altri utenti che riscontrano lo stesso problema.
Le eccezioni non gestite non vengono intercettate da PowerShell nelle condizioni seguenti:
- Se un cmdlet crea un nuovo thread e il codice in esecuzione in tale thread genera un'eccezione non gestita, PowerShell non rileva l'errore e termina il processo.
- Se nel distruttore di un oggetto è presente codice o metodi Dispose che causano un'eccezione non gestita, PowerShell non intercetterà l'errore e terminerà il processo.
Segnalazione di errori non erminanti
Uno qualsiasi dei metodi di elaborazione dell'input può segnalare un errore non sterminante al flusso di output usando il metodo System.Management.Automation.Cmdlet.WriteError.
Di seguito è riportato un esempio di codice di questo cmdlet Get-Proc che illustra la chiamata a System.Management.Automation.Cmdlet.WriteError dall'override del metodo System.Management.Automation.Cmdlet.ProcessRecord. In questo caso, la chiamata viene effettuata se il cmdlet non riesce a trovare un processo per un identificatore di processo specificato.
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
}
Aspetti da ricordare sulla scrittura di errori non diterminazione
Per un errore nonminante, il cmdlet deve generare un identificatore di errore specifico per ogni oggetto di input specifico.
Un cmdlet deve spesso modificare l'azione di PowerShell prodotta da un errore nonminante. A tale scopo, è possibile definire i ErrorAction parametri ErrorVariable e . Se si definisce il parametro , il cmdlet presenta le opzioni utente ErrorAction System.Management.Automation.ActionPreference, è anche possibile influenzare direttamente l'azione impostando la $ErrorActionPreference variabile .
Il cmdlet può salvare gli errori non sterminanti in una variabile usando il parametro , che non è influenzato ErrorVariable dall'impostazione di ErrorAction . Gli errori possono essere aggiunti a una variabile di errore esistente aggiungendo un segno più (+) all'inizio del nome della variabile.
Codice di esempio
Per il codice di esempio C# completo, vedere l'esempio GetProcessSample04.
Definire i tipi di oggetto e la formattazione
PowerShell passa informazioni tra i cmdlet usando oggetti .NET. Di conseguenza, un cmdlet potrebbe dover definire il proprio tipo o il cmdlet potrebbe dover estendere un tipo esistente fornito da un altro cmdlet. Per altre informazioni sulla definizione di nuovi tipi o sull'estensione di tipi esistenti, vedere Estensione dei tipi di oggetto e formattazione.
Compilazione del cmdlet
Dopo aver implementato un cmdlet, è necessario registrarlo con Windows PowerShell tramite Windows PowerShell snap-in. Per altre informazioni sulla registrazione dei cmdlet, vedere How to Register Cmdlets, Providers, and Host Applications.
Test del cmdlet
Dopo aver registrato il cmdlet con PowerShell, è possibile testarlo eseguendolo nella riga di comando. Testare l'esempio Get-Proc cmdlet per verificare se segnala un errore:
Avviare PowerShell e usare il cmdlet Get-Proc per recuperare i processi denominati "TEST".
get-proc -name testViene visualizzato l'output seguente.
get-proc : Operation is not valid due to the current state of the object. At line:1 char:9 + get-proc <<<< -name test
Vedere anche
Aggiunta di parametri che elaborano gli input della pipeline
Aggiunta di parametri che elaborano Command-Line input
Estensione dei tipi di oggetto e formattazione
Come registrare cmdlet, provider e applicazioni host
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per