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.

Sintaxe

On Error { GoTo [ line | 0 | -1 ] | Resume Next }

Partes

Comentários

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.

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.

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

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)

Confira também

• Err
• Number
• Description
• LastDllError
• Instrução End
• Instrução Exit
• Instrução Resume
• Mensagens de Erro
• Instrução Try...Catch...Finally