Compartilhar via

Solicitar confirmação por meio de cmdlets

Os cmdlets devem solicitar confirmação quando fizerem 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 confirmação do usuário antes de continuar. Por outro lado, se um cmdlet estiver prestes a alterar uma variável do Windows PowerShell, o cmdlet 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 métodos System.Management.Automation.Cmdlet.ShouldProcess e System.Management.Automation.Cmdlet.ShouldContinue (opcional) para exibir uma mensagem de solicitação de confirmação.

Suporte a solicitações de confirmação

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 e WhatIf os Confirm parâmetros 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 da operação que altera o sistema ser 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 método System.Management.Automation.Cmdlet.ShouldContinue, o cmdlet também deverá fornecer um parâmetro Force comutador. Se o usuário especificar Force quando o usuário invocar o cmdlet, o cmdlet ainda deverá chamar System.Management.Automation.Cmdlet.ShouldProcess, mas deve ignorar a chamada para System.Management.Automation.Cmdlet.ShouldContinue.

System.Management.Automation.Cmdlet.ShouldContinue gerará uma exceção quando for chamado de um ambiente não interativo em que o usuário não possa ser solicitado. A adição de um Force parâmetro garante que o comando ainda possa ser executado quando ele é 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 System.Management.Automation.Cmdlet.ShouldProcess pode variar dependendo do ambiente no qual o cmdlet é invocado. Usar as diretrizes anteriores ajudará a garantir que o cmdlet se comporte de forma consistente com outros cmdlets, independentemente do ambiente de host.

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 Alto, Médio ou Baixo. Você pode especificar um valor para ConfirmImpact somente quando também especificar o parâmetro SupportsShouldProcess para o cmdlet.

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

Chamando métodos de não 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 System.Management.Automation.Cmdlet.WriteObject saída é intermingida com a saída normal do seu cmdlet ou provedor, o que dificulta a gravação de script.

  • Para avisar o usuário e continuar com a operação, o cmdlet ou provedor pode chamar o método System.Management.Automation.Cmdlet.WriteWarning.

  • Para fornecer informações adicionais que o usuário pode recuperar usando o parâmetro Verbose, o cmdlet ou provedor pode chamar o método System.Management.Automation.Cmdlet.WriteVerbose.

  • Para fornecer detalhes de nível de depuração para outros desenvolvedores ou para suporte ao produto, o cmdlet ou provedor pode chamar o método System.Management.Automation.Cmdlet.WriteDebug. O usuário pode recuperar essas informações usando o parâmetro Debug.

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.

Consulte Também

gravando um cmdlet do Windows PowerShell

  • Last updated on