Record degli errori di Windows PowerShell

Articolo
09/24/2021

I cmdlet devono passare un oggetto System.Management.Automation.ErrorRecord che identifica la condizione di errore per gli errori di terminazione e non di terminazione.

L'oggetto System.Management.Automation.ErrorRecord contiene le informazioni seguenti:

Eccezione che descrive l'errore. Spesso si tratta di un'eccezione rilevata e convertita dal cmdlet in un record di errore. Ogni record di errore deve contenere un'eccezione.

Se il cmdlet non ha rilevato un'eccezione, deve creare una nuova eccezione e scegliere la classe di eccezione che descrive meglio la condizione di errore. Tuttavia, non è necessario generare l'eccezione perché è possibile accedervi tramite la proprietà System.Management.Automation.ErrorRecord.Exception dell'oggetto System.Management.Automation.ErrorRecord.

Identificatore di errore che fornisce un designatore di destinazione che può essere usato a scopo diagnostico e da script Windows PowerShell per gestire condizioni di errore specifiche con gestori di errori specifici. Ogni record di errore deve contenere un identificatore di errore (vedere Identificatore errore).
Categoria di errore che fornisce un designatore generale che può essere usato per scopi diagnostici. Ogni record di errore deve specificare una categoria di errore (vedere Categoria di errore).
Un messaggio di errore di sostituzione facoltativo e un'azione consigliata (vedere Messaggio di errore di sostituzione).
Informazioni facoltative sulla chiamata al cmdlet che ha generato l'errore. Queste informazioni vengono specificate da Windows PowerShell (vedere Messaggio di chiamata).
Oggetto di destinazione in fase di elaborazione quando si è verificato l'errore. Potrebbe trattarsi dell'oggetto di input o di un altro oggetto che il cmdlet stava elaborando. Ad esempio, per il comando , l'errore potrebbe essere un'istanza di un remove-item -recurse c:\somedirectory oggetto FileInfo per "c:\somedirectory\lockedfile". Le informazioni sull'oggetto di destinazione sono facoltative.

Identificatore errore

Quando si crea un record di errore, specificare un identificatore che definisce la condizione di errore all'interno del cmdlet. Windows PowerShell combina l'identificatore di destinazione con il nome del cmdlet per creare un identificatore di errore completo. È possibile accedere all'identificatore di errore completo tramite la proprietà System.Management.Automation.ErrorRecord.FullyQualifiedErrorId dell'oggetto System.Management.Automation.ErrorRecord. L'identificatore di errore non è disponibile da solo. È disponibile solo come parte dell'identificatore di errore completo.

Usare le linee guida seguenti per generare identificatori di errore quando si creano record di errore:

Impostare identificatori di errore specifici per una condizione di errore. Scegliere come destinazione gli identificatori di errore per scopi diagnostici e per gli script che gestiscono condizioni di errore specifiche con gestori di errori specifici. Un utente deve essere in grado di usare l'identificatore di errore per identificare l'errore e la relativa origine. Gli identificatori di errore consentono anche la segnalazione di condizioni di errore specifiche da eccezioni esistenti, in modo che non siano necessarie nuove sottoclassi di eccezione.
In generale, assegnare identificatori di errore diversi a percorsi di codice diversi. L'utente finale trae vantaggio da identificatori specifici. Spesso, ogni percorso di codice che chiama System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.Throwterminatingerror* ha un proprio identificatore. Come regola, definire un nuovo identificatore quando si definisce una nuova stringa di modello per il messaggio di errore e viceversa. Non usare il messaggio di errore come identificatore.
Quando si pubblica il codice usando un identificatore di errore specifico, si stabilisce la semantica degli errori con tale identificatore per l'intero ciclo di vita del supporto tecnico. Non riutilizzarla in un contesto semanticamente diverso dal contesto originale. Se la semantica di questo errore cambia, creare e quindi usare un nuovo identificatore.
In genere è consigliabile usare un identificatore di errore specifico solo per le eccezioni di un particolare tipo CLR. Se il tipo dell'eccezione o il tipo dell'oggetto di destinazione cambia, creare e quindi usare un nuovo identificatore.
Scegliere il testo per l'identificatore di errore che corrisponde concisamente all'errore che si sta segnalando. Usare convenzioni standard .NET Framework di denominazione e di uso delle maiuscole. Non usare spazi vuoti o punteggiatura. Non localizzare gli identificatori di errore.
Non generare dinamicamente identificatori di errore in modo non riproducibile. Ad esempio, non incorporare informazioni sugli errori, ad esempio un ID processo. Gli identificatori di errore sono utili solo se corrispondono agli identificatori di errore riscontrati da altri utenti che riscontrano la stessa condizione di errore.

Categoria di errore

Quando si crea un record di errore, specificare la categoria dell'errore usando una delle costanti definite dall'enumerazione System.Management.Automation.ErrorCategory. Windows PowerShell usa la categoria di errore per visualizzare le informazioni sull'errore quando gli utenti impostano $ErrorView la variabile su "CategoryView" .

Evitare di usare la costante NotSpecified System.Management.Automation.ErrorCategory. Se sono disponibili informazioni sull'errore o sull'operazione che ha causato l'errore, scegliere la categoria che meglio descrive l'errore o l'operazione, anche se la categoria non è una corrispondenza perfetta.

Le informazioni visualizzate da Windows PowerShell sono definite stringa di visualizzazione della categoria e vengono compilate dalle proprietà della classe System.Management.Automation.Errorcategoryinfo. A questa classe è possibile accedere tramite la proprietà System.Management.Automation.ErrorRecord.CategoryInfo dell'errore.

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

Nell'elenco seguente vengono descritte le informazioni visualizzate:

Category: costante System.Management.Automation.ErrorCategory Windows PowerShell definita dall'utente.
TargetName: per impostazione predefinita, il nome dell'oggetto che il cmdlet stava elaborando quando si è verificato l'errore. Oppure un'altra stringa definita dal cmdlet.
TargetType: per impostazione predefinita, il tipo dell'oggetto di destinazione. Oppure un'altra stringa definita dal cmdlet.
Attività: per impostazione predefinita, il nome del cmdlet che ha creato il record di errore. Oppure un'altra stringa definita dal cmdlet.
Motivo: per impostazione predefinita, il tipo di eccezione. Oppure un'altra stringa definita dal cmdlet.

Messaggio di errore di sostituzione

Quando si sviluppa un record di errore per un cmdlet, il messaggio di errore predefinito per l'errore proviene dal testo del messaggio predefinito nella proprietà System.Exception.Message. Si tratta di una proprietà di sola lettura il cui testo del messaggio è destinato solo a scopi di debug (in base alle .NET Framework seguenti. È consigliabile creare un messaggio di errore che sostituisca o aumenta il testo del messaggio predefinito. Rendere il messaggio più semplice da usare e più specifico per il cmdlet .

Il messaggio di sostituzione viene fornito da un oggetto System.Management.Automation.ErrorDetails. Utilizzare uno dei costruttori seguenti di questo oggetto perché forniscono informazioni aggiuntive sulla localizzazione che possono essere usate da Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): usare questo costruttore se la stringa modello è una stringa di risorsa nello stesso assembly in cui viene implementato il cmdlet o se si vuole caricare la stringa del modello tramite un override del metodo System.Management.Automation.Cmdlet.GetResourceString.
ErrorDetails(Assembly, String, String, Object[]): usare questo costruttore se la stringa modello si trova in un altro assembly e non viene caricata tramite un override di System.Management.Automation.Cmdlet.GetResourceString.

Il messaggio di sostituzione deve essere conforme alle linee guida .NET Framework progettazione per la scrittura di messaggi di eccezione con una piccola differenza. Le linee guida specificano che i messaggi di eccezione devono essere scritti per gli sviluppatori. Questi messaggi sostitutivi devono essere scritti per l'utente del cmdlet.

Il messaggio di errore sostitutivo deve essere aggiunto prima che venga chiamato il metodo System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.Throwterminatingerror*. Per aggiungere un messaggio di sostituzione, impostare la proprietà System.Management.Automation.ErrorRecord.ErrorDetails del record di errore. Quando questa proprietà è impostata, Windows PowerShell la proprietà System.Management.Automation.ErrorDetails.Message* anziché il testo del messaggio predefinito.

Informazioni sulle azioni consigliate

L'oggetto System.Management.Automation.ErrorDetails può anche fornire informazioni sulle azioni consigliate quando si verifica l'errore.

Informazioni sulla chiamata

Quando un cmdlet usa System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.Throwterminatingerror* per segnalare un record di errore, Windows PowerShell aggiunge automaticamente informazioni che descrivono il comando richiamato quando si è verificato l'errore. Queste informazioni vengono fornite da un oggetto System.Management.Automation.Invocationinfo che contiene il nome del cmdlet richiamato dal comando, il comando stesso e le informazioni sulla pipeline o sullo script. Questa proprietà è di sola lettura.