Creazione di un cmdlet che modifica il sistemaCreating a Cmdlet that Modifies the System

A volte un cmdlet deve modificare lo stato di esecuzione del sistema, non solo lo stato del runtime di Windows PowerShell.Sometimes a cmdlet must modify the running state of the system, not just the state of the Windows PowerShell runtime. In questi casi, il cmdlet deve consentire all'utente di confermare se apportare o meno la modifica.In these cases, the cmdlet should allow the user a chance to confirm whether or not to make the change.

Per supportare la conferma, un cmdlet deve eseguire due operazioni.To support confirmation a cmdlet must do two things.

Grazie al supporto della conferma, un cmdlet espone i Confirm WhatIf parametri e forniti da Windows PowerShell e soddisfa anche le linee guida di sviluppo per i cmdlet. per ulteriori informazioni sulle linee guida per lo sviluppo di cmdlet, vedere linee guida per losviluppo di cmdlet.By supporting confirmation, a cmdlet exposes the Confirm and WhatIf parameters that are provided by Windows PowerShell, and also meets the development guidelines for cmdlets (For more information about cmdlet development guidelines, see Cmdlet Development Guidelines.).

Modifica del sistemaChanging the System

L'azione di "modifica del sistema" si riferisce a qualsiasi cmdlet che potenzialmente modifica lo stato del sistema al di fuori di Windows PowerShell.The act of "changing the system" refers to any cmdlet that potentially changes the state of the system outside Windows PowerShell. Ad esempio, l'arresto di un processo, l'abilitazione o la disabilitazione di un account utente o l'aggiunta di una riga a una tabella di database sono tutte modifiche al sistema che devono essere confermate.For example, stopping a process, enabling or disabling a user account, or adding a row to a database table are all changes to the system that should be confirmed. Al contrario, le operazioni di lettura dei dati o di stabilire connessioni temporanee non cambiano il sistema e in genere non richiedono la conferma.In contrast, operations that read data or establish transient connections do not change the system and generally do not require confirmation. Non è inoltre necessaria una conferma per le azioni il cui effetto è limitato all'interno del runtime di Windows PowerShell, ad esempio set-variable .Confirmation is also not needed for actions whose effect is limited to inside the Windows PowerShell runtime, such as set-variable. I cmdlet che potrebbero o meno apportare una modifica permanente devono dichiarare SupportsShouldProcess e chiamare System. Management. Automation. cmdlet. ShouldProcess solo se stanno per apportare una modifica permanente.Cmdlets that might or might not make a persistent change should declare SupportsShouldProcess and call System.Management.Automation.Cmdlet.ShouldProcess only if they are about to make a persistent change.

Nota

La conferma ShouldProcess si applica solo ai cmdlet.ShouldProcess confirmation applies only to cmdlets. Se un comando o uno script modifica lo stato di esecuzione di un sistema chiamando direttamente i metodi o le proprietà .NET oppure chiamando le applicazioni all'esterno di Windows PowerShell, questo tipo di conferma non sarà disponibile.If a command or script modifies the running state of a system by directly calling .NET methods or properties, or by calling applications outside of Windows PowerShell, this form of confirmation will not be available.

Cmdlet StopProcThe StopProc Cmdlet

Questo argomento descrive un cmdlet Stop-proc che tenta di arrestare i processi recuperati usando il cmdlet Get-proc, descritto in creazione del primo cmdlet.This topic describes a Stop-Proc cmdlet that attempts to stop processes that are retrieved using the Get-Proc cmdlet (described in Creating Your First Cmdlet).

Definizione del cmdletDefining the Cmdlet

Il primo passaggio nella creazione di cmdlet è sempre il nome del cmdlet e la dichiarazione della classe .NET che implementa il cmdlet.The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that implements the cmdlet. Poiché si sta scrivendo un cmdlet per modificare il sistema, è necessario denominarlo di conseguenza.Because you are writing a cmdlet to change the system, it should be named accordingly. Questo cmdlet interrompe i processi di sistema, quindi il nome del verbo scelto qui è "Stop", definito dalla classe System. Management. Automation. Verbslifecycle , con il sostantivo "proc" per indicare che il cmdlet interrompe i processi.This cmdlet stops system processes, so the verb name chosen here is "Stop", defined by the System.Management.Automation.Verbslifecycle class, with the noun "Proc" to indicate that the cmdlet stops processes. Per altre informazioni sui verbi di cmdlet approvati, vedere nomi dei verbi di cmdlet.For more information about approved cmdlet verbs, see Cmdlet Verb Names.

Di seguito è riportata la definizione della classe per il cmdlet Stop-proc.The following is the class definition for this Stop-Proc cmdlet.

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

Tenere presente che nella Dichiarazione System. Management. Automation. CmdletAttribute la SupportsShouldProcess parola chiave attribute è impostata su true per consentire al cmdlet di effettuare chiamate a System. Management. Automation. cmdlet. ShouldProcess e System. Management. Automation. cmdlet. ShouldContinue.Be aware that in the System.Management.Automation.CmdletAttribute declaration, the SupportsShouldProcess attribute keyword is set to true to enable the cmdlet to make calls to System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue. Senza questa parola chiave impostata, Confirm i WhatIf parametri e non saranno disponibili per l'utente.Without this keyword set, the Confirm and WhatIf parameters will not be available to the user.

Azioni estremamente distruttiveExtremely Destructive Actions

Alcune operazioni sono estremamente distruttive, ad esempio la riformattazione di una partizione del disco rigido attiva.Some operations are extremely destructive, such as reformatting an active hard disk partition. In questi casi, il cmdlet deve essere impostato ConfirmImpact = ConfirmImpact.High quando si dichiara l'attributo System. Management. Automation. CmdletAttribute .In these cases, the cmdlet should set ConfirmImpact = ConfirmImpact.High when declaring the System.Management.Automation.CmdletAttribute attribute. Questa impostazione impone al cmdlet di richiedere la conferma dell'utente anche quando l'utente non ha specificato il Confirm parametro.This setting forces the cmdlet to request user confirmation even when the user has not specified the Confirm parameter. Tuttavia, gli sviluppatori di cmdlet devono evitare ConfirmImpact il sovrautilizzo di per le operazioni potenzialmente distruttive, ad esempio l'eliminazione di un account utente.However, cmdlet developers should avoid overusing ConfirmImpact for operations that are just potentially destructive, such as deleting a user account. Tenere presente che se ConfirmImpact è impostato su System. Management. Automation. ConfirmImpact High.Remember that if ConfirmImpact is set to System.Management.Automation.ConfirmImpact High.

Analogamente, è improbabile che alcune operazioni siano distruttive, sebbene in teoria modifichino lo stato di esecuzione di un sistema al di fuori di Windows PowerShell.Similarly, some operations are unlikely to be destructive, although they do in theory modify the running state of a system outside Windows PowerShell. Questi cmdlet possono impostare ConfirmImpact su System. Management. Automation. ConfirmImpact. Low.Such cmdlets can set ConfirmImpact to System.Management.Automation.Confirmimpact.Low. Questa operazione consente di ignorare le richieste di conferma in cui l'utente ha richiesto di confermare solo le operazioni a medio e a elevato utilizzo.This will bypass confirmation requests where the user has asked to confirm only medium-impact and high-impact operations.

Definizione dei parametri per la modifica del sistemaDefining Parameters for System Modification

In questa sezione viene descritto come definire i parametri del cmdlet, inclusi quelli necessari per supportare la modifica del sistema.This section describes how to define the cmdlet parameters, including those that are needed to support system modification. Per informazioni generali sulla definizione dei parametri, vedere aggiunta di parametri che elaborano l'input della riga di comando.See Adding Parameters that Process CommandLine Input if you need general information about defining parameters.

Il cmdlet Stop-proc definisce tre parametri: Name , Force e PassThru .The Stop-Proc cmdlet defines three parameters: Name, Force, and PassThru.

Il Name parametro corrisponde alla Name proprietà dell'oggetto di input del processo.The Name parameter corresponds to the Name property of the process input object. Tenere presente che il Name parametro in questo esempio è obbligatorio, in quanto il cmdlet avrà esito negativo se non è presente un processo denominato da arrestare.Be aware that the Name parameter in this sample is mandatory, as the cmdlet will fail if it does not have a named process to stop.

Il Force parametro consente all'utente di eseguire l'override delle chiamate a System. Management. Automation. cmdlet. ShouldContinue.The Force parameter allows the user to override calls to System.Management.Automation.Cmdlet.ShouldContinue. In realtà, qualsiasi cmdlet che chiama System. Management. Automation. cmdlet. ShouldContinue deve avere un Force parametro in modo che quando Force viene specificato, il cmdlet ignora la chiamata a System. Management. Automation. cmdlet. ShouldContinue e procede con l'operazione.In fact, any cmdlet that calls System.Management.Automation.Cmdlet.ShouldContinue should have a Force parameter so that when Force is specified, the cmdlet skips the call to System.Management.Automation.Cmdlet.ShouldContinue and proceeds with the operation. Tenere presente che questa operazione non influisce sulle chiamate a System. Management. Automation. cmdlet. ShouldProcess.Be aware that this does not affect calls to System.Management.Automation.Cmdlet.ShouldProcess.

Il PassThru parametro consente all'utente di indicare se il cmdlet passa un oggetto di output attraverso la pipeline, in questo caso, dopo l'arresto di un processo.The PassThru parameter allows the user to indicate whether the cmdlet passes an output object through the pipeline, in this case, after a process is stopped. Tenere presente che questo parametro è associato al cmdlet stesso anziché a una proprietà dell'oggetto di input.Be aware that this parameter is tied to the cmdlet itself instead of to a property of the input object.

Di seguito è illustrata la dichiarazione di parametro per il cmdlet Stop-proc.Here is the parameter declaration for the Stop-Proc cmdlet.

[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 dell'inputOverriding an Input Processing Method

Il cmdlet deve eseguire l'override di un metodo di elaborazione dell'input.The cmdlet must override an input processing method. Il codice seguente illustra l'override di System. Management. Automation. cmdlet. ProcessRecord usato nel cmdlet Stop-proc di esempio.The following code illustrates the System.Management.Automation.Cmdlet.ProcessRecord override used in the sample Stop-Proc cmdlet. Per ogni nome di processo richiesto, questo metodo garantisce che il processo non sia un processo speciale, tenta di arrestare il processo e quindi Invia un oggetto di output se il PassThru parametro è specificato.For each requested process name, this method ensures that the process is not a special process, tries to stop the process, and then sends an output object if the PassThru parameter is specified.

protected override void ProcessRecord()
{
  foreach (string name in processNames)
  {
    // For every process name passed to the cmdlet, get the associated
    // process(es). For failures, write a non-terminating error
    Process[] processes;

    try
    {
      processes = Process.GetProcessesByName(name);
    }
    catch (InvalidOperationException ioe)
    {
      WriteError(new ErrorRecord(ioe,"Unable to access the target process by name",
                 ErrorCategory.InvalidOperation, name));
      continue;
    }

    // Try to stop the process(es) that have been retrieved for a name
    foreach (Process process in processes)
    {
      string processName;

      try
      {
        processName = process.ProcessName;
      }

      catch (Win32Exception e)
        {
          WriteError(new ErrorRecord(e, "ProcessNameNotFound",
                     ErrorCategory.ReadError, process));
          continue;
        }

        // Call Should Process to confirm the operation first.
        // This is always false if WhatIf is set.
        if (!ShouldProcess(string.Format("{0} ({1})", processName,
                           process.Id)))
        {
          continue;
        }
        // Call ShouldContinue to make sure the user really does want
        // to stop a critical process that could possibly stop the computer.
        bool criticalProcess =
             criticalProcessNames.Contains(processName.ToLower());

        if (criticalProcess &&!force)
        {
          string message = String.Format
                ("The process \"{0}\" is a critical process and should not be stopped. Are you sure you wish to stop the process?",
                processName);

          // It is possible that ProcessRecord is called multiple times
          // when the Name parameter receives objects as input from the
          // pipeline. So to retain YesToAll and NoToAll input that the
          // user may enter across multiple calls to ProcessRecord, this
          // information is stored as private members of the cmdlet.
          if (!ShouldContinue(message, "Warning!",
                              ref yesToAll,
                              ref noToAll))
          {
            continue;
          }
        } // if (criticalProcess...
        // Stop the named process.
        try
        {
          process.Kill();
        }
        catch (Exception e)
        {
          if ((e is Win32Exception) || (e is SystemException) ||
              (e is InvalidOperationException))
          {
            // This process could not be stopped so write
            // a non-terminating error.
            string message = String.Format("{0} {1} {2}",
                             "Could not stop process \"", processName,
                             "\".");
            WriteError(new ErrorRecord(e, message,
                       ErrorCategory.CloseError, process));
                       continue;
          } // if ((e is...
          else throw;
        } // catch

        // If the PassThru parameter argument is
        // True, pass the terminated process on.
        if (passThru)
        {
          WriteObject(process);
        }
    } // foreach (Process...
  } // foreach (string...
} // ProcessRecord

Chiamata al metodo ShouldProcessCalling the ShouldProcess Method

Il metodo di elaborazione dell'input del cmdlet deve chiamare il metodo System. Management. Automation. cmdlet. ShouldProcess per confermare l'esecuzione di un'operazione prima che venga apportata una modifica, ad esempio l'eliminazione di file, allo stato di esecuzione del sistema.The input processing method of your cmdlet should call the System.Management.Automation.Cmdlet.ShouldProcess method to confirm execution of an operation before a change (for example, deleting files) is made to the running state of the system. Ciò consente al runtime di Windows PowerShell di fornire il comportamento corretto "WhatIf" e "Confirm" all'interno della shell.This allows the Windows PowerShell runtime to supply the correct "WhatIf" and "Confirm" behavior within the shell.

Nota

Se un cmdlet dichiara che supporta deve elaborare e non riesce a eseguire la chiamata System. Management. Automation. cmdlet. ShouldProcess , l'utente potrebbe modificare il sistema in modo imprevisto.If a cmdlet states that it supports should process and fails to make the System.Management.Automation.Cmdlet.ShouldProcess call, the user might modify the system unexpectedly.

La chiamata a System. Management. Automation. cmdlet. ShouldProcess invia il nome della risorsa da modificare all'utente, con il runtime di Windows PowerShell che prende in considerazione le impostazioni della riga di comando o le variabili di preferenza per determinare gli elementi da visualizzare all'utente.The call to System.Management.Automation.Cmdlet.ShouldProcess sends the name of the resource to be changed to the user, with the Windows PowerShell runtime taking into account any command-line settings or preference variables in determining what should be displayed to the user.

Nell'esempio seguente viene illustrata la chiamata a System. Management. Automation. cmdlet. ShouldProcess dall'override del metodo System. Management. Automation. cmdlet. ProcessRecord nel cmdlet Stop-proc di esempio.The following example shows the call to System.Management.Automation.Cmdlet.ShouldProcess from the override of the System.Management.Automation.Cmdlet.ProcessRecord method in the sample Stop-Proc cmdlet.

if (!ShouldProcess(string.Format("{0} ({1})", processName,
                   process.Id)))
{
  continue;
}

Chiamata al metodo ShouldContinueCalling the ShouldContinue Method

La chiamata al metodo System. Management. Automation. cmdlet. ShouldContinue Invia un messaggio secondario all'utente.The call to the System.Management.Automation.Cmdlet.ShouldContinue method sends a secondary message to the user. Questa chiamata viene eseguita dopo che la chiamata a System. Management. Automation. cmdlet. ShouldProcess restituisce true e se il Force parametro non è stato impostato su true .This call is made after the call to System.Management.Automation.Cmdlet.ShouldProcess returns true and if the Force parameter was not set to true. L'utente può quindi inviare commenti e suggerimenti per indicare se l'operazione deve essere continuata.The user can then provide feedback to say whether the operation should be continued. Il cmdlet chiama System. Management. Automation. cmdlet. ShouldContinue come controllo aggiuntivo per le modifiche di sistema potenzialmente pericolose o quando si desidera fornire all'utente opzioni Sì-a-tutti e no-to-all.Your cmdlet calls System.Management.Automation.Cmdlet.ShouldContinue as an additional check for potentially dangerous system modifications or when you want to provide yes-to-all and no-to-all options to the user.

Nell'esempio seguente viene illustrata la chiamata a System. Management. Automation. cmdlet. ShouldContinue dall'override del metodo System. Management. Automation. cmdlet. ProcessRecord nel cmdlet Stop-proc di esempio.The following example shows the call to System.Management.Automation.Cmdlet.ShouldContinue from the override of the System.Management.Automation.Cmdlet.ProcessRecord method in the sample Stop-Proc cmdlet.

if (criticalProcess &&!force)
{
  string message = String.Format
        ("The process \"{0}\" is a critical process and should not be stopped. Are you sure you wish to stop the process?",
        processName);

  // It is possible that ProcessRecord is called multiple times
  // when the Name parameter receives objects as input from the
  // pipeline. So to retain YesToAll and NoToAll input that the
  // user may enter across multiple calls to ProcessRecord, this
  // information is stored as private members of the cmdlet.
  if (!ShouldContinue(message, "Warning!",
                      ref yesToAll,
                      ref noToAll))
  {
    continue;
  }
} // if (criticalProcess...

Arresto dell'elaborazione dell'inputStopping Input Processing

Il metodo di elaborazione dell'input di un cmdlet che apporta modifiche al sistema deve fornire un modo per arrestare l'elaborazione dell'input.The input processing method of a cmdlet that makes system modifications must provide a way of stopping the processing of input. Nel caso di questo cmdlet Stop-proc, viene eseguita una chiamata dal metodo System. Management. Automation. cmdlet. ProcessRecord al metodo System. Diagnostics. Process. Kill * .In the case of this Stop-Proc cmdlet, a call is made from the System.Management.Automation.Cmdlet.ProcessRecord method to the System.Diagnostics.Process.Kill* method. Poiché il PassThru parametro è impostato su true , System. Management. Automation. cmdlet. ProcessRecord chiama anche System. Management. Automation. cmdlet. WriteObject per inviare l'oggetto processo alla pipeline.Because the PassThru parameter is set to true, System.Management.Automation.Cmdlet.ProcessRecord also calls System.Management.Automation.Cmdlet.WriteObject to send the process object to the pipeline.

Codice di esempioCode Sample

Per il codice di esempio C# completo, vedere l' esempio StopProcessSample01.For the complete C# sample code, see StopProcessSample01 Sample.

Definizione di tipi di oggetti e formattazioneDefining Object Types and Formatting

Windows PowerShell passa le informazioni tra i cmdlet usando gli oggetti .NET.Windows PowerShell passes information between cmdlets using .Net objects. Di conseguenza, un cmdlet può avere la necessità di definire un proprio tipo oppure il cmdlet deve estendere un tipo esistente fornito da un altro cmdlet.Consequently, a cmdlet may need to define its own type, or the cmdlet may need to extend an existing type provided by another cmdlet. Per ulteriori informazioni sulla definizione di nuovi tipi o sull'estensione di tipi esistenti, vedere estensione di tipi di oggetti e formattazione.For more information about defining new types or extending existing types, see Extending Object Types and Formatting.

Compilazione del cmdletBuilding the Cmdlet

Dopo l'implementazione di un cmdlet, è necessario registrarlo con Windows PowerShell tramite uno snap-in di Windows PowerShell.After implementing a cmdlet, it must be registered with Windows PowerShell through a Windows PowerShell snap-in. Per ulteriori informazioni sulla registrazione dei cmdlet, vedere come registrare i cmdlet, i provider e le applicazioni host.For more information about registering cmdlets, see How to Register Cmdlets, Providers, and Host Applications.

Test del cmdletTesting the Cmdlet

Quando il cmdlet è stato registrato con Windows PowerShell, è possibile testarlo eseguendolo nella riga di comando.When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the command line. Di seguito sono riportati diversi test che testano il cmdlet Stop-proc.Here are several tests that test the Stop-Proc cmdlet. Per ulteriori informazioni sull'utilizzo dei cmdlet dalla riga di comando, vedere la Introduzione con Windows PowerShell.For more information about using cmdlets from the command line, see the Getting Started with Windows PowerShell.

  • Avviare Windows PowerShell e usare il cmdlet Stop-proc per arrestare l'elaborazione, come illustrato di seguito.Start Windows PowerShell and use the Stop-Proc cmdlet to stop processing as shown below. Poiché il cmdlet specifica il Name parametro come obbligatorio, il cmdlet esegue una query per il parametro.Because the cmdlet specifies the Name parameter as mandatory, the cmdlet queries for the parameter.

    PS> stop-proc
    

    Viene visualizzato l'output seguente.The following output appears.

    Cmdlet stop-proc at command pipeline position 1
    Supply values for the following parameters:
    Name[0]:
    
  • A questo punto è possibile usare il cmdlet per arrestare il processo denominato "blocco note".Now let's use the cmdlet to stop the process named "NOTEPAD". Il cmdlet richiede di confermare l'azione.The cmdlet asks you to confirm the action.

    PS> stop-proc -Name notepad
    

    Viene visualizzato l'output seguente.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "notepad (4996)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
    
  • Usare stop-proc come illustrato per arrestare il processo critico denominato "WINLOGON".Use Stop-Proc as shown to stop the critical process named "WINLOGON". Viene richiesto e visualizzato un avviso relativo all'esecuzione di questa azione perché il sistema operativo verrà riavviato.You are prompted and warned about performing this action because it will cause the operating system to reboot.

    PS> stop-proc -Name Winlogon
    

    Viene visualizzato l'output seguente.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "winlogon (656)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
    Warning!
    The process " winlogon " is a critical process and should not be stopped. Are you sure you wish to stop the process?
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
    
  • A questo punto, provare ad arrestare il processo WINLOGON senza ricevere un avviso.Let's now try to stop the WINLOGON process without receiving a warning. Tenere presente che questa voce di comando usa il Force parametro per eseguire l'override dell'avviso.Be aware that this command entry uses the Force parameter to override the warning.

    PS> stop-proc -Name winlogon -Force
    

    Viene visualizzato l'output seguente.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "winlogon (656)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
    

Vedere ancheSee Also

Aggiunta di parametri che elaborano l'input della riga di comandoAdding Parameters that Process Command-Line Input

Estensione di tipi di oggetti e formattazioneExtending Object Types and Formatting

Come registrare cmdlet, provider e applicazioni hostHow to Register Cmdlets, Providers, and Host Applications

Windows PowerShell SDKWindows PowerShell SDK

Esempi di cmdletCmdlet Samples