Partilhar via

Requesting Confirmation from Cmdlets (Pedir Confirmação a Partir de Cmdlets)

Os cmdlets devem solicitar confirmação quando estiverem prestes a fazer uma alteração no sistema que está fora do ambiente do Windows PowerShell. Por exemplo, se um cmdlet estiver prestes a adicionar uma conta de usuário ou interromper um processo, o cmdlet deverá exigir a confirmação do usuário antes de prosseguir. Por outro lado, se um cmdlet estiver prestes a alterar uma variável do Windows PowerShell, ele não precisará exigir confirmação.

Para fazer uma solicitação de confirmação, o cmdlet deve indicar que dá suporte a solicitações de confirmação e deve chamar os System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue métodos (opcionais) para exibir uma mensagem de solicitação de confirmação.

Pedidos de confirmação de suporte

Para dar suporte a solicitações de confirmação, o cmdlet deve definir o parâmetro SupportsShouldProcess do atributo Cmdlet como true. Isso habilita os parâmetros de cmdlet Confirm e WhatIf fornecidos pelo Windows PowerShell. O parâmetro Confirm permite que o usuário controle se a solicitação de confirmação é exibida. O parâmetro WhatIf permite que o usuário determine se o cmdlet deve exibir uma mensagem ou executar sua ação. Não adicione manualmente os parâmetros Confirm e WhatIf a um cmdlet.

O exemplo a seguir mostra uma declaração de atributo Cmdlet que dá suporte a solicitações de confirmação.

[Cmdlet(VerbsDiagnostic.Test, "RequestConfirmationTemplate1",
        SupportsShouldProcess = true)]

Chamando os métodos de solicitação de confirmação

No código do cmdlet, chame o método System.Management.Automation.Cmdlet.ShouldProcess antes que a operação que altera o sistema seja executada. Projete o cmdlet para que, se a chamada retornar um valor de false, a operação não seja executada e o cmdlet processe a próxima operação.

Chamando o método ShouldContinue

A maioria dos cmdlets solicita confirmação usando apenas o método System.Management.Automation.Cmdlet.ShouldProcess. No entanto, alguns casos podem exigir confirmação adicional. Para esses casos, complemente a chamada System.Management.Automation.Cmdlet.ShouldProcess com uma chamada para o método System.Management.Automation.Cmdlet.ShouldContinue. Isso permite que o cmdlet ou provedor controle mais finamente o escopo do Sim para todos os resposta ao prompt de confirmação.

Se um cmdlet chamar o System.Management.Automation.Cmdlet.ShouldContinue método, o cmdlet também deverá fornecer um parâmetro de opção Force. Se o usuário especificar Force quando o usuário invocar o cmdlet, o cmdlet ainda deverá chamar System.Management.Automation.Cmdlet.ShouldProcess, mas deverá ignorar a chamada para System.Management.Automation.Cmdlet.ShouldContinue.

System.Management.Automation.Cmdlet.ShouldContinue lançará uma exceção quando for chamada de um ambiente não interativo onde o usuário não pode ser solicitado. Adicionar um parâmetro Force garante que o comando ainda possa ser executado quando é invocado em um ambiente não interativo.

O exemplo a seguir mostra como chamar System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue.

if (ShouldProcess (...) )
{
  if (Force || ShouldContinue(...))
  {
     // Add code that performs the operation.
  }
}

O comportamento de uma chamada de System.Management.Automation.Cmdlet.ShouldProcess pode variar dependendo do ambiente no qual o cmdlet é invocado. O uso das diretrizes anteriores ajudará a garantir que o cmdlet se comporte de forma consistente com outros cmdlets, independentemente do ambiente do host.

Para obter um exemplo de como chamar o método System.Management.Automation.Cmdlet.ShouldProcess, consulte Como solicitar confirmações.

Especificar o nível de impacto

Ao criar o cmdlet, especifique o nível de impacto (a gravidade) da alteração. Para fazer isso, defina o valor do parâmetro ConfirmImpact do atributo Cmdlet como High, Medium ou Low. Você pode especificar um valor para ConfirmImpact somente quando também especificar o parâmetro SupportsShouldProcess para o cmdlet.

Para a maioria dos cmdlets, não é necessário especificar explicitamente ConfirmImpact. Em vez disso, use a configuração padrão do parâmetro, que é Medium. Se você definir ConfirmImpact como Alto, a operação será confirmada por padrão. Reserve essa configuração para ações que causam grandes interrupções, como reformatar um volume de disco rígido.

Chamando métodos sem confirmação

Se o cmdlet ou provedor precisar enviar uma mensagem, mas não solicitar confirmação, ele poderá chamar os três métodos a seguir. Evite usar o método System.Management.Automation.Cmdlet.WriteObject para enviar mensagens desses tipos porque saída de System.Management.Automation.Cmdlet.WriteObject está misturada com a saída normal do seu cmdlet ou provedor, o que dificulta a escrita de scripts.

Os cmdlets e provedores primeiro chamam os seguintes métodos para solicitar confirmação antes de tentarem executar uma operação que altera um sistema fora do Windows PowerShell:

Eles fazem isso chamando o método System.Management.Automation.Cmdlet.ShouldProcess, que solicita que o usuário confirme a operação com base em como o usuário invocou o comando.

Ver também

Escrevendo um cmdlet do Windows PowerShell

  • Last updated on