Aggiunta di messaggi utente al cmdlet

I cmdlet possono scrivere diversi tipi di messaggi che possono essere visualizzati all'utente dal runtime di Windows PowerShell. Questi messaggi includono i tipi seguenti:

• Messaggi dettagliati che contengono informazioni generali sull'utente.

• Eseguire il debug dei messaggi contenenti informazioni sulla risoluzione dei problemi.

• Messaggi di avviso che contengono una notifica che il cmdlet sta per eseguire un'operazione che può avere risultati imprevisti.

• Messaggi del report di stato contenenti informazioni sulla quantità di lavoro completata dal cmdlet durante l'esecuzione di un'operazione che richiede molto tempo.

Non esistono limiti al numero di messaggi che il cmdlet può scrivere o il tipo di messaggi scritti dal cmdlet. Ogni messaggio viene scritto effettuando una chiamata specifica dall'interno del metodo di elaborazione di input del cmdlet.

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 . Qualsiasi tipo di cmdlet può scrivere notifiche utente dai metodi di elaborazione dell'input; Pertanto, in generale, è possibile denominare questo cmdlet usando qualsiasi verbo che indica le modifiche di sistema eseguite dal cmdlet. Per altre informazioni sui verbi dei cmdlet approvati, vedere cmdlet Verb Names.

Il cmdlet Stop-Proc è progettato per modificare il sistema; pertanto, la dichiarazione System.Management.Automation.CmdletAttribute per la classe .NET deve includere la parola chiave dell'attributo SupportsShouldProcess e essere impostata su true.

Il codice seguente è la definizione per questa classe di cmdlet Stop-Proc. Per altre informazioni su questa definizione, vedere Creating a Cmdlet that Modifies the System.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Definizione dei parametri per la modifica del sistema

Il cmdlet Stop-Proc definisce tre parametri: Name, Forcee PassThru. Per altre informazioni sulla definizione di questi parametri, vedere Creazione di un cmdlet che modifica il sistema.

Ecco la dichiarazione di parametro per il cmdlet Stop-Proc.

[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
  get { return force; }
  set { force = value; }
}
private bool force;

/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
  get { return passThru; }
  set { passThru = value; }
}
private bool passThru;

Override di un metodo di elaborazione di input

Il cmdlet deve eseguire l'override di un metodo di elaborazione di input, spesso System.Management.Automation.Cmdlet.ProcessRecord. Questo cmdlet Stop-Proc esegue l'override del metodo di elaborazione di input System.Management.Automation.Cmdlet.ProcessRecord. In questa implementazione del cmdlet Stop-Proc vengono effettuate chiamate per scrivere messaggi dettagliati, messaggi di debug e messaggi di avviso.

Nota

Per altre informazioni su come questo metodo chiama i metodi System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue, vedere Creazione di un cmdlet che modifica ildi sistema.

Scrittura di un messaggio dettagliato

Il metodo System.Management.Automation.Cmdlet.WriteVerbose viene usato per scrivere informazioni generali a livello di utente non correlate a condizioni di errore specifiche. L'amministratore di sistema può quindi usare tali informazioni per continuare a elaborare altri comandi. Inoltre, tutte le informazioni scritte con questo metodo devono essere localizzate in base alle esigenze.

Il codice seguente di questo cmdlet Stop-Proc mostra due chiamate al metodo System.Management.Automation.Cmdlet.WriteVerbose dall'override del metodo System.Management.Automation.Cmdlet.ProcessRecord.

message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);

message = String.Format("Stopped process \"{0}\", pid {1}.",
                        processName, process.Id);

WriteVerbose(message);

Scrittura di un messaggio di debug

Il metodo System.Management.Automation.Cmdlet.WriteDebug viene usato per scrivere messaggi di debug che possono essere usati per risolvere i problemi relativi all'operazione del cmdlet. La chiamata viene eseguita da un metodo di elaborazione di input.

Nota

Windows PowerShell definisce anche un parametro Debug che presenta informazioni dettagliate e di debug. Se il cmdlet supporta questo parametro, non è necessario chiamare System.Management.Automation.Cmdlet.WriteDebug nello stesso codice che chiama System.Management.Automation.Cmdlet.WriteVerbose.

Le due sezioni di codice seguenti del cmdlet Stop-Proc di esempio mostrano le chiamate al metodo System.Management.Automation.Cmdlet.WriteDebug dall'override del metodo System.Management.Automation.Cmdlet.ProcessRecor d.

Questo messaggio di debug viene scritto immediatamente prima che venga chiamato System.Management.Automation.Cmdlet.ShouldProcess.

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

Questo messaggio di debug viene scritto immediatamente prima di viene chiamato il System.Management.Automation.Cmdlet.WriteObject.

message =
         String.Format("Writing process \"{0}\" to pipeline",
         processName);
WriteDebug(message);
WriteObject(process);

Windows PowerShell instrada automaticamente qualsiasi System.Management.Automation.Cmdlet.WriteDebug chiamate all'infrastruttura di traccia e ai cmdlet. In questo modo è possibile tracciare le chiamate al metodo all'applicazione host, a un file o a un debugger senza dover eseguire operazioni di sviluppo aggiuntive all'interno del cmdlet. La voce della riga di comando seguente implementa un'operazione di traccia.

ps> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc blocco note

Scrittura di un messaggio di avviso

Il metodo System.Management.Automation.Cmdlet.WriteWarning viene usato per scrivere un avviso quando il cmdlet sta per eseguire un'operazione che potrebbe avere un risultato imprevisto, ad esempio sovrascrivendo un file di sola lettura.

Il codice seguente del cmdlet Stop-Proc di esempio mostra la chiamata al metodo System.Management.Automation.Cmdlet.WriteWarning dall'override del metodo System.Management.Automation.Cmdlet.ProcessRecord.

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

Scrittura di un messaggio di stato

Il System.Management.Automation.Cmdlet.WriteProgress viene usato per scrivere messaggi di stato quando le operazioni dei cmdlet richiedono un periodo di tempo prolungato per il completamento. Una chiamata a System.Management.Automation.Cmdlet.WriteProgress passa un oggetto System.Management.Automation.Progressrecord inviato all'applicazione di hosting per il rendering all'utente.

Nota

Questo cmdlet Stop-Proc non include una chiamata al metodo system.Management.Automation.Cmdlet.WriteProgress.

Il codice seguente è un esempio di messaggio di stato scritto da un cmdlet che tenta di copiare un elemento.

int myId = 0;
string myActivity = "Copy-item: Copying *.* to C:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);

pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);

Codice di esempio

Per il codice di esempio C# completo, vedere esempio StopProcessSample02.

Definire tipi di oggetto e formattazione

Windows 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, deve essere registrato 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 Windows PowerShell, è possibile testarlo eseguendolo nella riga di comando. Verrà ora testato il cmdlet Stop-Proc di esempio. Per altre informazioni sull'uso dei cmdlet dalla riga di comando, vedere l'Introduzione a Windows PowerShell.

• La voce della riga di comando seguente usa Stop-Proc per arrestare il processo denominato "NOTEPAD", fornire notifiche dettagliate e stampare le informazioni di debug.

  PS> Stop-Proc -Name notepad -Verbose -Debug
  

  Viene visualizzato l'output seguente.

  VERBOSE: Attempting to stop process " notepad ".
  DEBUG: Acquired name for pid 5584 : "notepad"
  
  Confirm
  Continue with this operation?
  [Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"): Y
  
  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "notepad (5584)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  VERBOSE: Stopped process "notepad", pid 5584.
  

Vedere anche

Creare un cmdlet che modifica il di sistema

Come creare un cmdlet di Windows PowerShell

l'estensione dei tipi di oggetto e la formattazione

Come registrare cmdlet, provider e applicazioni host

windows PowerShell SDK