Partilhar via

Adding Parameter Sets to a Cmdlet (Adicionar Conjuntos de Parâmetros a um Cmdlet)

Coisas a saber sobre conjuntos de parâmetros

O Windows PowerShell define um conjunto de parâmetros como um grupo de parâmetros que operam juntos. Ao agrupar os parâmetros de um cmdlet, você pode criar um único cmdlet que pode alterar sua funcionalidade com base no grupo de parâmetros especificado pelo usuário.

Um exemplo de cmdlet que usa dois conjuntos de parâmetros para definir funcionalidades diferentes é o cmdlet Get-EventLog fornecido pelo Windows PowerShell. Esse cmdlet retorna informações diferentes quando o usuário especifica o parâmetro List ou LogName. Se o parâmetro LogName for especificado, o cmdlet retornará informações sobre os eventos em um determinado log de eventos. Se o parâmetro List for especificado, o cmdlet retornará informações sobre os próprios arquivos de log (não as informações de evento que eles contêm). Nesse caso, os parâmetros List e LogName identificam dois conjuntos de parâmetros separados.

Duas coisas importantes a lembrar sobre conjuntos de parâmetros é que o tempo de execução do Windows PowerShell usa apenas um conjunto de parâmetros para uma entrada específica e que cada conjunto de parâmetros deve ter pelo menos um parâmetro exclusivo para esse conjunto de parâmetros.

Para ilustrar esse último ponto, este cmdlet Stop-Proc usa três conjuntos de parâmetros: ProcessName, ProcessIde InputObject. Cada um desses conjuntos de parâmetros tem um parâmetro que não está nos outros conjuntos de parâmetros. Os conjuntos de parâmetros podem compartilhar outros parâmetros, mas o cmdlet usa os parâmetros exclusivos ProcessName, ProcessIde InputObject para identificar qual conjunto de parâmetros o tempo de execução do Windows PowerShell deve usar.

Declarando a classe de cmdlet

A primeira etapa na criação do cmdlet é sempre nomear o cmdlet e declarar a classe .NET que implementa o cmdlet. Para este cmdlet, o verbo do ciclo de vida "Parar" é usado porque o cmdlet interrompe os processos do sistema. O nome do substantivo "Proc" é usado porque o cmdlet funciona em processos. Na declaração abaixo, observe que o verbo do cmdlet e o nome do substantivo são refletidos no nome da classe do cmdlet.

Observação

Para obter mais informações sobre nomes verbais de cmdlet aprovados, consulte Cmdlet Verb Names.

O código a seguir é a definição de classe para este cmdlet Stop-Proc.

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

<Cmdlet(VerbsLifecycle.Stop, "Proc", DefaultParameterSetName:="ProcessId", _
SupportsShouldProcess:=True)> _
Public Class StopProcCommand
    Inherits PSCmdlet

Declarando os parâmetros do cmdlet

Este cmdlet define três parâmetros necessários como entrada para o cmdlet (esses parâmetros também definem os conjuntos de parâmetros), bem como um parâmetro Force que gerencia o que o cmdlet faz e um parâmetro PassThru que determina se o cmdlet envia um objeto de saída através do pipeline. Por padrão, esse cmdlet não passa um objeto pelo pipeline. Para obter mais informações sobre esses dois últimos parâmetros, consulte Criando um cmdlet que modifica o sistema.

Declarando o parâmetro Name

Este parâmetro de entrada permite que o usuário especifique os nomes dos processos a serem interrompidos. Observe que a palavra-chave do atributo ParameterSetName do atributo System.Management.Automation.ParameterAttribute especifica o conjunto de parâmetros ProcessName para esse parâmetro.

[Parameter(
   Position = 0,
   ParameterSetName = "ProcessName",
   Mandatory = true,
   ValueFromPipeline = true,
   ValueFromPipelineByPropertyName = true,
   HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
    get { return processNames; }
    set { processNames = value; }
}
private string[] processNames;

<Parameter(Position:=0, ParameterSetName:="ProcessName", _
Mandatory:=True, _
ValueFromPipeline:=True, ValueFromPipelineByPropertyName:=True, _
HelpMessage:="The name of one or more processes to stop. " & _
    "Wildcards are permitted."), [Alias]("ProcessName")> _
Public Property Name() As String()
    Get
        Return processNames
    End Get
    Set(ByVal value As String())
        processNames = value
    End Set
End Property

Private processNames() As String

Observe também que o alias "ProcessName" é dado a esse parâmetro.

Declarando o parâmetro id

Este parâmetro de entrada permite ao usuário especificar os identificadores dos processos a serem interrompidos. Observe que a palavra-chave ParameterSetName atributo do atributo System.Management.Automation.ParameterAttribute especifica o conjunto de parâmetros ProcessId.

[Parameter(
           ParameterSetName = "ProcessId",
           Mandatory = true,
           ValueFromPipelineByPropertyName = true,
           ValueFromPipeline = true
)]
[Alias("ProcessId")]
public int[] Id
{
  get { return processIds; }
  set { processIds = value; }
}
private int[] processIds;

<Parameter(ParameterSetName:="ProcessId", _
Mandatory:=True, _
ValueFromPipelineByPropertyName:=True, _
ValueFromPipeline:=True), [Alias]("ProcessId")> _
Public Property Id() As Integer()
    Get
        Return processIds
    End Get
    Set(ByVal value As Integer())
        processIds = value
    End Set
End Property
Private processIds() As Integer

Observe também que o alias "ProcessId" é dado a esse parâmetro.

Declarando o parâmetro InputObject

Esse parâmetro de entrada permite que o usuário especifique um objeto de entrada que contém informações sobre os processos a serem interrompidos. Observe que a palavra-chave do atributo ParameterSetName do atributo System.Management.Automation.ParameterAttribute especifica o conjunto de parâmetros InputObject para esse parâmetro.

[Parameter(
           ParameterSetName = "InputObject",
           Mandatory = true,
           ValueFromPipeline = true)]
public Process[] InputObject
{
  get { return inputObject; }
  set { inputObject = value; }
}
private Process[] inputObject;

<Parameter(ParameterSetName:="InputObject", _
Mandatory:=True, ValueFromPipeline:=True)> _
Public Property InputObject() As Process()
    Get
        Return myInputObject
    End Get
    Set(ByVal value As Process())
        myInputObject = value
    End Set
End Property
Private myInputObject() As Process

Observe também que esse parâmetro não tem alias.

Declarando parâmetros em vários conjuntos de parâmetros

Embora deva haver um parâmetro exclusivo para cada conjunto de parâmetros, os parâmetros podem pertencer a mais de um conjunto de parâmetros. Nesses casos, forneça ao parâmetro compartilhado uma System.Management.Automation.ParameterAttribute declaração de atributo para cada conjunto ao qual o parâmetro pertence. Se um parâmetro estiver em todos os conjuntos de parâmetros, você só precisará declarar o atributo parameter uma vez e não precisará especificar o nome do conjunto de parâmetros.

Substituindo um método de processamento de entrada

Cada cmdlet deve substituir um método de processamento de entrada, na maioria das vezes esse será o método System.Management.Automation.Cmdlet.ProcessRecord. Neste cmdlet, o método System.Management.Automation.Cmdlet.ProcessRecord é substituído para que o cmdlet possa processar qualquer número de processos. Ele contém uma instrução Select que chama um método diferente com base no conjunto de parâmetros especificado pelo usuário.

protected override void ProcessRecord()
{
  switch (ParameterSetName)
  {
    case "ProcessName":
         ProcessByName();
         break;

    case "ProcessId":
         ProcessById();
         break;

    case "InputObject":
         foreach (Process process in inputObject)
         {
           SafeStopProcess(process);
         }
         break;

    default:
         throw new ArgumentException("Bad ParameterSet Name");
  } // switch (ParameterSetName...
} // ProcessRecord

Protected Overrides Sub ProcessRecord()
    Select Case ParameterSetName
        Case "ProcessName"
            ProcessByName()

        Case "ProcessId"
            ProcessById()

        Case "InputObject"
            Dim process As Process
            For Each process In myInputObject
                SafeStopProcess(process)
            Next process

        Case Else
            Throw New ArgumentException("Bad ParameterSet Name")
    End Select

End Sub 'ProcessRecord ' ProcessRecord

Os métodos Helper chamados pela instrução Select não são descritos aqui, mas você pode ver sua implementação no exemplo de código completo na próxima seção.

Exemplo de código

Para obter o código de exemplo C# completo, consulte Exemplo de StopProcessSample04.

Definindo tipos de objeto e formatação

O Windows PowerShell passa informações entre cmdlets usando objetos .NET. Consequentemente, um cmdlet pode precisar definir seu próprio tipo, ou o cmdlet pode precisar estender um tipo existente fornecido por outro cmdlet. Para obter mais informações sobre como definir novos tipos ou estender tipos existentes, consulte Estendendo tipos de objeto e formatando.

Criando o cmdlet

Depois de implementar um cmdlet, você deve registrá-lo com o Windows PowerShell por meio de um snap-in do Windows PowerShell. Para obter mais informações sobre como registrar cmdlets, consulte Como registrar cmdlets, provedores e aplicativos host.

Testando o cmdlet

Quando seu cmdlet tiver sido registrado no Windows PowerShell, teste-o executando-o na linha de comando. Aqui estão alguns testes que mostram como os parâmetros ProcessId e InputObject podem ser usados para testar seus conjuntos de parâmetros para parar um processo.

  • Com o Windows PowerShell iniciado, execute o cmdlet Stop-Proc com o parâmetro ProcessId definido para interromper um processo com base em seu identificador. Nesse caso, o cmdlet está usando o conjunto de parâmetros ProcessId para interromper o processo.

    PS> Stop-Proc -Id 444
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • Com o Windows PowerShell iniciado, execute o cmdlet Stop-Proc com o parâmetro InputObject definido para interromper processos no objeto do Bloco de Notas recuperado pelo comando Get-Process.

    PS> Get-Process notepad | Stop-Proc
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

Ver também

Criando um cmdlet que modifica o sistema

Como criar um cmdlet do Windows PowerShell

Estendendo tipos de objeto e formatação

Como registrar cmdlets, provedores e aplicativos host

SDK do Windows PowerShell

  • Last updated on