Instrução On Error (Visual Basic)
Habilita uma rotina de tratamento de erros e especifica o local da rotina dentro de um procedimento; também pode ser usada para desabilitar uma rotina de tratamento de erros. A instrução On Error é usada no tratamento de erros não estruturados e pode ser usada em vez de tratamento de exceção estruturada. O tratamento de exceção estruturado é integrado ao .NET, geralmente é mais eficiente e, portanto, é recomendável ao lidar com erros de runtime em seu aplicativo.
Sem tratamento de erro ou tratamento de exceção, qualquer erro em tempo de execução que ocorra é fatal: uma mensagem de erro é exibida e a execução é interrompida.
Observação
A palavra-chave Error também é usada na Instrução Error, que tem suporte para compatibilidade com versões anteriores.
Sintaxe
On Error { GoTo [ line | 0 | -1 ] | Resume Next }
Partes
| Termo | Definição |
|---|---|
GoTo linha |
Habilita a rotina de tratamento de erros que começa na linha especificada no argumento line necessário. O argumento line é qualquer rótulo de linha ou número de linha. Se ocorrer um erro em tempo de execução, controle branches para a linha especificada, tornando o manipulador de erros ativo. A linha especificada deve estar no mesmo procedimento que a instrução On Error; caso contrário, ocorrerá um erro em tempo de compilação. |
GoTo 0 |
Desabilita o manipulador de erros habilitado no procedimento atual e o redefine como Nothing. |
GoTo -1 |
Desabilita a exceção habilitada no procedimento atual e a redefine como Nothing. |
Resume Next |
Especifica que, quando ocorre um erro em tempo de execução, o controle vai para a instrução imediatamente após a instrução em que o erro ocorreu e a execução continua desse ponto. Use esse formulário em vez de On Error GoTo ao acessar objetos. |
Comentários
Observação
Recomendamos que você use o tratamento de exceção estruturado em seu código sempre que possível, em vez de usar o tratamento de exceção não estruturado e a instrução On Error. Para obter mais informações, consulte Instrução Try...Catch...Finally.
Um manipulador de erros "habilitado" é aquele que é ativado por uma instrução On Error. Um manipulador de erros "ativo" é um manipulador habilitado que está em processo de tratamento de um erro.
Se ocorrer um erro enquanto um manipulador de erros estiver ativo (entre a ocorrência do erro e uma instrução Resume, Exit Sub, Exit Function ou Exit Property), o manipulador de erros do procedimento atual não poderá lidar com o erro. O controle retorna ao procedimento de chamada.
Se o procedimento de chamada tiver um manipulador de erros habilitado, ele será ativado para lidar com o erro. Se o manipulador de erros do procedimento de chamada também estiver ativo, o controle passará por procedimentos de chamada anteriores até que um manipulador de erros habilitado, mas inativo, seja encontrado. Se nenhum manipulador de erros for encontrado, o erro será fatal no ponto em que ele realmente ocorreu.
Cada vez que o manipulador de erros passa o controle de volta para um procedimento de chamada, esse procedimento se torna o procedimento atual. Depois que um erro é tratado por um manipulador de erros em qualquer procedimento, a execução é retomada no procedimento atual no ponto designado pela instrução Resume.
Observação
Uma rotina de tratamento de erros não é um procedimento Sub nem um procedimento Function. É uma seção de código marcada por um rótulo de linha ou um número de linha.
Propriedade number
As rotinas de tratamento de erros dependem do valor na propriedade Number do objeto Err para determinar a causa do erro. A rotina deve testar ou salvar valores de propriedade relevantes no objeto Err antes que qualquer outro erro possa ocorrer ou antes que um procedimento que possa causar um erro seja chamado. Os valores da propriedade no objeto Err refletem apenas o erro mais recente. A mensagem de erro associada a Err.Number está contida em Err.Description.
Instrução Throw
Um erro gerado com o método Err.Raise define a propriedade Exception como uma instância recém-criada da classe Exception. Para dar suporte à criação de exceções de tipos de exceção derivadas, há suporte para uma instrução Throw no idioma. Isso requer um único parâmetro que é a instância de exceção a ser gerada. O seguinte exemplo mostra como esses recursos podem ser usados com o suporte ao tratamento de exceções existente:
On Error GoTo Handler
Throw New DivideByZeroException()
Handler:
If (TypeOf Err.GetException() Is DivideByZeroException) Then
' Code for handling the error is entered here.
End If
Observe que a instrução On Error GoTo intercepta todos os erros, independentemente da classe de exceção.
On Error Resume Next
On Error Resume Next faz com que a execução continue com a instrução imediatamente após a instrução que causou o erro em tempo de execução ou com a instrução imediatamente após a chamada mais recente do procedimento que contém a instrução On Error Resume Next. Essa instrução permite que a execução continue apesar de um erro em tempo de execução. Você pode colocar a rotina de tratamento de erros onde o erro ocorreria em vez de transferir o controle para outro local dentro do procedimento. Uma instrução On Error Resume Next fica inativa quando outro procedimento é chamado, portanto, você deverá executar uma instrução On Error Resume Next em cada rotina chamada se desejar tratamento de erro embutido dentro dessa rotina.
Observação
O constructo On Error Resume Next pode ser preferível a On Error GoTo ao manipular erros gerados durante o acesso a outros objetos. Verificar Err após cada interação com um objeto remove a ambiguidade sobre qual objeto foi acessado pelo código. Você pode ter certeza de qual objeto colocou o código de erro em Err.Number, bem como de qual objeto originalmente gerou o erro (o objeto especificado em Err.Source).
On Error GoTo 0
On Error GoTo 0 desabilita o tratamento de erros no procedimento atual. Ele não especifica a linha 0 como o início do código de tratamento de erros, mesmo que o procedimento contenha uma linha numerada 0. Sem uma instrução On Error GoTo 0, um manipulador de erros é desabilitado automaticamente quando um procedimento é encerrado.
On Error GoTo -1
On Error GoTo -1 desabilita a exceção no procedimento atual. Ele não especifica a linha -1 como o início do código de tratamento de erros, mesmo que o procedimento contenha uma linha numerada -1. Sem uma instrução On Error GoTo -1, uma exceção é desabilitada automaticamente quando um procedimento é encerrado.
Para impedir que o código de tratamento de erros seja executado quando nenhum erro tiver ocorrido, coloque uma instrução Exit Sub, Exit Function ou Exit Property imediatamente antes da rotina de tratamento de erros, como no seguinte fragmento:
Public Sub InitializeMatrix(ByVal Var1 As Object, ByVal Var2 As Object)
On Error GoTo ErrorHandler
' Insert code that might generate an error here
Exit Sub
ErrorHandler:
' Insert code to handle the error here
Resume Next
End Sub
Aqui, o código de tratamento de erros segue a instrução Exit Sub e precede a instrução End Sub para separá-la do fluxo de procedimento. Você pode colocar o código de tratamento de erros em qualquer lugar em um procedimento.
Erros não mapeados
Erros não mapeados em objetos são retornados ao aplicativo controlador quando o objeto está em execução como um arquivo executável. No ambiente de desenvolvimento, os erros não mapeados são retornados ao aplicativo controlador somente se as opções adequadas forem definidas. Consulte a documentação do aplicativo host para obter uma descrição de quais opções devem ser definidas durante a depuração, como defini-las e se o host pode criar classes.
Se você criar um objeto que acesse outros objetos, tente manipular os erros não tratados que eles passarem de volta. Se não puder, mapeie os códigos de erro em Err.Number para um dos próprios erros e passe-os de volta para o chamador do objeto. Especifique o erro adicionando o código de erro à constante VbObjectError. Por exemplo, se o código de erro for 1052, atribua-o da seguinte maneira:
Err.Number = vbObjectError + 1052
Cuidado
Os erros do sistema durante as chamadas para DLLs (bibliotecas de vínculo dinâmico) do Windows não geram exceções e não podem ser capturados com a captura de erro do Visual Basic. Ao chamar funções DLL, você deve verificar cada valor retornado para obter êxito ou falha (de acordo com as especificações da API) e, em caso de falha, verifique o valor na propriedade Err do objeto LastDLLError.
Exemplo
Este exemplo primeiro usa a instrução On Error GoTo para especificar o local de uma rotina de tratamento de erros dentro de um procedimento. No exemplo, uma tentativa de dividir por zero gera o erro número 6. O erro é tratado na rotina de tratamento de erros e o controle é retornado para a instrução que causou o erro. A instrução On Error GoTo 0 desativa a captura de erro. Em seguida, a instrução On Error Resume Next é usada para adiar a captura de erros para que o contexto do erro gerado pela próxima instrução possa ser conhecido com certeza. Observe que Err.Clear é usado para limpar as propriedades do objeto Err depois que o erro é tratado.
Public Sub OnErrorDemo()
On Error GoTo ErrorHandler ' Enable error-handling routine.
Dim x As Integer = 32
Dim y As Integer = 0
Dim z As Integer
z = x / y ' Creates a divide by zero error
On Error GoTo 0 ' Turn off error trapping.
On Error Resume Next ' Defer error trapping.
z = x / y ' Creates a divide by zero error again
If Err.Number = 6 Then
' Tell user what happened. Then clear the Err object.
Dim Msg As String
Msg = "There was an error attempting to divide by zero!"
MsgBox(Msg, , "Divide by zero error")
Err.Clear() ' Clear Err object fields.
End If
Exit Sub ' Exit to avoid handler.
ErrorHandler: ' Error-handling routine.
Select Case Err.Number ' Evaluate error number.
Case 6 ' Divide by zero error
MsgBox("You attempted to divide by zero!")
' Insert code to handle this error
Case Else
' Insert code to handle other situations here...
End Select
Resume Next ' Resume execution at the statement immediately
' following the statement where the error occurred.
End Sub
Requisitos
Namespace: Microsoft.VisualBasic
Assembly: Biblioteca de Tempo de Execução do Visual Basic (em Microsoft.VisualBasic.dll)
