Aggiunta di messaggi utente al cmdlet

Articolo
09/24/2021

I cmdlet possono scrivere diversi tipi di messaggi che possono essere visualizzati all'utente dal runtime Windows PowerShell runtime. 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 contenenti una notifica che indica che il cmdlet sta per eseguire un'operazione che può avere risultati imprevisti.
Messaggi di report sullo stato che contengono informazioni sulla quantità di lavoro completata dal cmdlet durante l'esecuzione di un'operazione che richiede molto tempo.

Non sono previsti limiti al numero di messaggi che il cmdlet può scrivere o al 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 nella creazione del cmdlet consiste sempre nel denominare il cmdlet e dichiarare la classe .NET che implementa il cmdlet. Qualsiasi cmdlet può scrivere notifiche utente dai relativi metodi di elaborazione dell'input. Pertanto, in generale, è possibile assegnare un nome a questo cmdlet usando qualsiasi verbo che indichi le modifiche di sistema eseguite dal cmdlet. Per altre informazioni sui verbi dei cmdlet approvati, vedere Nomi dei verbi dei cmdlet.

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 attribute ed SupportsShouldProcess essere impostata su true .

Il codice seguente è la definizione per questa Stop-Proc cmdlet. Per altre informazioni su questa definizione, vedere Creazione di un cmdlet che modifica il sistema.

[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 , Force e 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, in genere sarà System.Management.Automation.Cmdlet.ProcessRecord. Questo Stop-Proc cmdlet esegue l'override del metodo di elaborazione dell'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 sul modo in cui questo metodo chiama i metodi System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue, vedere Creazione di un cmdlet che modifica il 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 queste 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 al funzionamento del cmdlet. La chiamata viene effettuata da un metodo di elaborazione di input.

Nota

Windows PowerShell definisce anche un parametro che presenta informazioni Debug 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.ProcessRecord.

Questo messaggio di debug viene scritto immediatamente prima della chiamata a 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 della chiamata a System.Management.Automation.Cmdlet.WriteObject.

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

Windows PowerShell automaticamente tutte le chiamate System.Management.Automation.Cmdlet.WriteDebug all'infrastruttura di traccia e ai cmdlet. In questo modo le chiamate al metodo possono essere tracciate nell'applicazione host, in un file o in un debugger senza dover eseguire altre operazioni di sviluppo 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 notepad

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 la sovrascrittura di 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

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

Nota

Questo Stop-Proc cmdlet 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 sta tentando 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 StopProcessSample02 Sample.

Definire i tipi di oggetto e la formattazione

Windows PowerShell le 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 di tipi esistenti, vedere Estensione di tipi di oggetto e formattazione.

Compilazione del cmdlet

Dopo l'implementazione, un cmdlet deve essere registrato con Windows PowerShell tramite uno snap-in Windows PowerShell di configurazione. Per altre informazioni sulla registrazione dei cmdlet, vedere Come registrare cmdlet, provider e applicazioni host.

Test del cmdlet

Dopo aver registrato il cmdlet con Windows PowerShell, è possibile testarlo eseguendolo nella riga di comando. Testare il cmdlet di esempio Stop-Proc. Per altre informazioni sull'uso dei cmdlet dalla riga di comando, vedere l'Attività iniziali con Windows PowerShell.

La voce della riga di comando seguente usa Stop-Proc per arrestare il processo denominato "NOTEPAD", fornire notifiche dettagliate e stampare 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.