Condividi tramite

Aggiunta di segnalazioni di errori non irreversibili al cmdlet

I cmdlet possono segnalare errori non irreversibili chiamando il metodo System.Management.Automation.Cmdlet.WriteError e continuare a funzionare 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 irreversibili dai relativi metodi di elaborazione di input.

Per gli errori non irreversibili (oltre a errori irreversibili), il cmdlet deve passare un System.Management.Automation.ErrorRecord oggetto che identifica l'errore. Ogni record di errore viene identificato da una stringa univoca denominata "identificatore di errore". Oltre all'identificatore, la categoria di ogni errore viene specificata da costanti definite da un 'enumerazione System.Management.Automation.ErrorCategory. L'utente può visualizzare gli errori in base alla categoria impostando la variabile $ErrorView su "CategoryView".

Per altre informazioni sui record di errore, vedere i record di errore di Windows PowerShell.

Definizione del cmdlet

Il primo passaggio della creazione dei cmdlet è sempre la denominazione del cmdlet e la dichiarazione della classe .NET che implementa il cmdlet . Questo cmdlet recupera le informazioni sul processo, quindi il nome del verbo scelto qui è "Get". Quasi qualsiasi tipo di cmdlet in grado di recuperare informazioni può elaborare l'input della riga di comando. Per altre informazioni sui verbi dei cmdlet approvati, vedere cmdlet Verb Names.

Di seguito è riportata la definizione di questo cmdlet Get-Proc. I dettagli di questa definizione vengono forniti 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 Aggiunta di parametri che elaborano 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 di input forniti dalla classe System.Management.Automation.Cmdlet. Questi metodi vengono illustrati 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 tutti i processi se non viene specificato alcun nome. I dettagli di questa sostituzione vengono forniti 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 al suo nucleo. Seguire le linee guida di .NET per determinare l'eccezione da usare. Fondamentalmente, 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 eccezione 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 è possibile determinare l'errore e da dove proviene 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 proviene 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 eseguire un ramo anche nelle parti dell'identificatore di errore, nonché nell'identificatore di errore e nella 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 tersely 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 includa un identificatore di processo. Gli identificatori di errore sono utili per un utente solo quando corrispondono agli identificatori visualizzati da altri utenti che riscontrano lo stesso problema.

Le eccezioni non gestite non vengono rilevate da PowerShell nelle condizioni seguenti:

  • Se un cmdlet crea un nuovo thread e codice in esecuzione in tale thread genera un'eccezione non gestita, PowerShell non intercetta l'errore e terminerà il processo.
  • Se un oggetto dispone di codice nel relativo distruttore o metodi Dispose che causano un'eccezione non gestita, PowerShell non intercetta l'errore e terminerà il processo.

Segnalazione di errori non irreversibili

Uno dei metodi di elaborazione di input può segnalare un errore non irreversibile 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'interno dell'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 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
  }

Aspetti da ricordare per la scrittura di errori non irreversibili

Per un errore non irreversibile, il cmdlet deve generare un identificatore di errore specifico per ogni oggetto di input specifico.

Un cmdlet deve spesso modificare l'azione di PowerShell generata da un errore non irreversibile. A tale scopo, è possibile definire i parametri ErrorAction e ErrorVariable. Se si definisce il parametro ErrorAction, il cmdlet presenta le opzioni utente System.Management.Automation.ActionPreference, è anche possibile influenzare direttamente l'azione impostando la variabile $ErrorActionPreference.

Il cmdlet può salvare errori non irreversibili in una variabile usando il parametro ErrorVariable, che non è interessato dall'impostazione di ErrorAction. Gli errori possono essere aggiunti a una variabile di errore esistente aggiungendo un segno più (+) alla parte anteriore del nome della variabile.

Codice di esempio

Per il codice di esempio C# completo, vedere Esempio getProcessSample04.

Definire tipi di oggetto e formattazione

PowerShell passa informazioni tra i cmdlet usando oggetti .NET. Di conseguenza, un cmdlet potrebbe dover definire il proprio tipo oppure potrebbe essere necessario estendere un tipo esistente fornito da un altro cmdlet. Per altre informazioni sulla definizione di nuovi tipi o sull'estensione dei tipi esistenti, vedere Estensione dei tipi di oggetto e formattazione.

Compilazione del cmdlet

Dopo aver implementato un cmdlet, è necessario registrarlo con Windows PowerShell tramite uno snap-in di Windows PowerShell. Per altre informazioni sulla registrazione dei cmdlet, vedere Come registrare cmdlet, provider e applicazioni host.

Test del cmdlet

Quando il cmdlet è stato registrato con PowerShell, è possibile testarlo eseguendolo nella riga di comando. Verrà ora testato il cmdlet di esempio Get-Proc per verificare se segnala un errore:

  • Avviare PowerShell e usare il cmdlet Get-Proc per recuperare i processi denominati "TEST".

    Get-Proc -Name test

    Viene 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

  • Last updated on