Compartilhar via

Solicitar confirmação por meio 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 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 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 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 parâmetro Force 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.

Para obter um exemplo de como chamar o método System.Management.Automation.Cmdlet.ShouldProcess, consulte How to Request Confirmations.

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 explicitamente ConfirmImpact. 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