Erros de encerramento

Este tópico discute o método usado para relatar erros de encerramento. Ele também discute como chamar o método de dentro do cmdlet e discute as exceções que podem ser retornadas pelo runtime do Windows PowerShell quando o método é chamado.

Quando ocorre um erro de encerramento, o cmdlet deve relatar o erro chamando o método System.Management.Automation.Cmdlet.ThrowTerminatingError*. Esse método permite que o cmdlet envie um registro de erro que descreva a condição que causou o erro de encerramento. Para obter mais informações sobre registros de erros, consulte Registros de Erros do Windows PowerShell.

Quando o método System.Management.Automation.Cmdlet.ThrowTerminatingError* é chamado, o runtime do Windows PowerShell interrompe permanentemente a execução do pipeline e gera uma exceção System.Management.Automation.PipelineStoppedException. Qualquer tentativa subsequente de chamar System.Management.Automation.Cmdlet.WriteObject, System.Management.Automation.Cmdlet.WriteErrorou várias outras APIs faz com que essas chamadas gerem uma exceção System.Management.Automation.PipelineStoppedException.

A exceção System.Management.Automation.PipelineStoppedException do também poderá ocorrer se outro cmdlet no pipeline relatar um erro de encerramento, se o usuário tiver solicitado que interromper o pipeline ou se o pipeline tiver sido interrompido antes da conclusão por qualquer motivo. O cmdlet não precisa capturar o System.Management.Automation.PipelineStoppedException exceção, a menos que ele precise limpar recursos abertos ou seu estado interno.

Os cmdlets podem gravar qualquer número de objetos de saída ou erros de não terminação antes de relatar um erro de encerramento. No entanto, o erro de encerramento interrompe permanentemente o pipeline e nenhuma saída adicional, erros de encerramento ou erros de não terminação podem ser relatados.

Os cmdlets podem chamar System.Management.Automation.Cmdlet.ThrowTerminatingError* somente do thread que chamou o System.Management.Automation.Cmdlet.BeginProcessing, System.Management.Automation.Cmdlet.ProcessRecordou System.Management.Automation.Cmdlet.EndProcessing método de processamento de entrada. Não tente chamar System.Management.Automation.Cmdlet.ThrowTerminatingError* ou System.Management.Automation.Cmdlet.WriteError de outro thread. Em vez disso, os erros devem ser comunicados novamente para o thread principal.

É possível que um cmdlet gere uma exceção em sua implementação do System.Management.Automation.Cmdlet.BeginProcessing, System.Management.Automation.Cmdlet.ProcessRecordou método System.Management.Automation.Cmdlet.EndProcessing. Qualquer exceção gerada desses métodos (exceto por algumas condições de erro graves que interrompem o host do Windows PowerShell) é interpretada como um erro de encerramento que interrompe o pipeline, mas não o Windows PowerShell como um todo. (Isso se aplica somente ao thread do cmdlet principal. Exceções não executadas em threads gerados pelo cmdlet, em geral, interrompem o host do Windows PowerShell.) Recomendamos que você use System.Management.Automation.Cmdlet.ThrowTerminatingError* em vez de gerar uma exceção porque o registro de erro fornece informações adicionais sobre a condição de erro, o que é útil para o usuário final. Os cmdlets devem respeitar a diretriz de código gerenciado contra capturar e lidar com todas as exceções (catch (Exception e)). Converta apenas exceções de tipos conhecidos e esperados em registros de erro.

Consulte Também

System.Management.Automation.Cmdlet.BeginProcessing

System.Management.Automation.Cmdlet.EndProcessing

System.Management.Automation.Cmdlet.ProcessRecord

System.Management.Automation.PipelineStoppedException

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.Cmdlet.WriteError

registros de erro do Windows PowerShell

gravando um cmdlet do Windows PowerShell