Adicionar conjuntos de parâmetros como um cmdlet
Coisas para saber sobre conjuntos de parâmetros
O Windows PowerShell define um conjunto de parâmetros como um grupo de parâmetros que operam juntos. Agrupando os parâmetros de um cmdlet, você pode criar um único cmdlet que pode alterar sua funcionalidade com base em qual grupo de parâmetros o usuário especifica.
Um exemplo de um cmdlet que usa dois conjuntos de parâmetros para definir diferentes funcionalidades é 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 log de eventos específico. 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 runtime 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 runtime do Windows PowerShell deve usar.
Declarando a classe cmdlet
A primeira etapa na criação do cmdlet é sempre nomear o cmdlet e declarar a classe .NET que implementa o cmdlet. Para esse 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 cmdlet.
Observação
Para obter mais informações sobre nomes de verbo de cmdlet aprovados, consulte Nomes de Verbo do Cmdlet.
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
Esse 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 por meio 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
Esse parâmetro de entrada permite que o usuário especifique os nomes dos processos a serem interrompidos. Observe que a palavra-chave de atributo ParameterSetName do atributo System.Management.Automation.ParameterAttribute especifica o parâmetro ProcessName definido 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 de ID
Esse parâmetro de entrada permite que o usuário especifique os identificadores dos processos a serem interrompidos. Observe que a palavra-chave de atributo ParameterSetName 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 contenha informações sobre os processos a serem interrompidos. Observe que a palavra-chave de atributo ParameterSetName do atributo System.Management.Automation.ParameterAttribute especifica o parâmetro InputObject definido 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 seja necessário 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 declaração de atributo System.Management.Automation.ParameterAttribute 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 de parâmetro 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, geralmente 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 em qual conjunto de parâmetros o usuário especificou.
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 auxiliares 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 de exemplo 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 formatação.
Compilando o cmdlet
Depois de implementar um cmdlet, você deve registrá-lo no 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 o 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 interromper um processo.
Com o Windows PowerShell iniciado, execute o cmdlet Stop-Proc com o parâmetro
ProcessIddefinido para interromper um processo com base em seu identificador. Nesse caso, o cmdlet está usando o parâmetroProcessIddefinido 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"): YCom o Windows PowerShell iniciado, execute o cmdlet Stop-Proc com o parâmetro
InputObjectdefinido para interromper processos no objeto do Bloco de Notas recuperado pelo comandoGet-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
Consulte Também
criando um cmdlet que modifica o sistema
como criar um cmdlet do Windows PowerShell
estendendo tipos de objeto e formatação
