Instrução On Error (Visual Basic)On Error Statement (Visual Basic)

Habilita uma rotina de tratamento de erros e especifica o local da rotina dentro de um procedimento; também pode ser usado para desabilitar uma rotina de tratamento de erros.Enables an error-handling routine and specifies the location of the routine within a procedure; can also be used to disable an error-handling routine. A instrução On Error é usada no tratamento de erros não estruturado e pode ser usada em vez de manipulação de exceção estruturada.The On Error statement is used in unstructured error handling and can be used instead of structured exception handling. A manipulação de exceção estruturada é criada no .net, geralmente é mais eficiente e, portanto, é recomendada ao lidar com erros de tempo de execução em seu aplicativo.Structured exception handling is built into .NET, is generally more efficient, and so is recommended when handling runtime errors in your application.

Sem tratamento de erro ou tratamento de exceção, qualquer erro de tempo de execução que ocorra é fatal: uma mensagem de erro é exibida e a execução é interrompida.Without error handling or exception handling, any run-time error that occurs is fatal: an error message is displayed, and execution stops.

Observação

A palavra-chave Error também é usada na instrução Error, que tem suporte para compatibilidade com versões anteriores.The Error keyword is also used in the Error Statement, which is supported for backward compatibility.

SintaxeSyntax

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

PartesParts

TermoTerm DefiniçãoDefinition
linha de GoToGoTo line Habilita a rotina de tratamento de erros que começa na linha especificada no argumento de linha necessário.Enables the error-handling routine that starts at the line specified in the required line argument. O argumento de linha é qualquer rótulo de linha ou número de linha.The line argument is any line label or line number. Se ocorrer um erro em tempo de execução, controle as ramificações para a linha especificada, tornando o manipulador de erros ativo.If a run-time error occurs, control branches to the specified line, making the error handler active. A linha especificada deve estar no mesmo procedimento que a instrução On Error ou ocorrerá um erro de tempo de compilação.The specified line must be in the same procedure as the On Error statement or a compile-time error will occur.
GoTo 0 Desabilita o manipulador de erro habilitado no procedimento atual e o redefine como Nothing.Disables enabled error handler in the current procedure and resets it to Nothing.
GoTo -1 Desabilita a exceção habilitada no procedimento atual e a redefine como Nothing.Disables enabled exception in the current procedure and resets it to Nothing.
Resume Next Especifica que quando ocorrer um erro em tempo de execução, o controle vai para a instrução imediatamente após a instrução em que ocorreu o erro e a execução continua desse ponto.Specifies that when a run-time error occurs, control goes to the statement immediately following the statement where the error occurred, and execution continues from that point. Use esse formulário em vez de On Error GoTo ao acessar objetos.Use this form rather than On Error GoTo when accessing objects.

ComentáriosRemarks

Observação

É recomendável que você use manipulação de exceção estruturada em seu código sempre que possível, em vez de usar a manipulação de exceção não estruturada e a instrução de On Error.We recommend that you use structured exception handling in your code whenever possible, rather than using unstructured exception handling and the On Error statement. Para obter mais informações, consulte Instrução Try...Catch...Finally.For more information, see Try...Catch...Finally Statement.

Um manipulador de erro "habilitado" é um que é ativado por uma instrução On Error.An "enabled" error handler is one that is turned on by an On Error statement. Um manipulador de erro "ativo" é um manipulador habilitado que está no processo de tratamento de um erro.An "active" error handler is an enabled handler that is in the process of handling an error.

Se ocorrer um erro enquanto um manipulador de erro estiver ativo (entre a ocorrência do erro e uma Resume, Exit Sub, Exit Functionou instrução Exit Property), o manipulador de erros do procedimento atual não poderá tratar o erro.If an error occurs while an error handler is active (between the occurrence of the error and a Resume, Exit Sub, Exit Function, or Exit Property statement), the current procedure's error handler cannot handle the error. O controle retorna para o procedimento de chamada.Control returns to the calling procedure.

Se o procedimento de chamada tiver um manipulador de erro habilitado, ele será ativado para manipular o erro.If the calling procedure has an enabled error handler, it is activated to handle the error. Se o manipulador de erro do procedimento de chamada também estiver ativo, o controle passa de volta pelos procedimentos de chamada anteriores até que um manipulador de erro habilitado, mas inativo, seja encontrado.If the calling procedure's error handler is also active, control passes back through previous calling procedures until an enabled, but inactive, error handler is found. Se nenhum manipulador de erro desse tipo for encontrado, o erro será fatal no ponto em que ele realmente ocorreu.If no such error handler is found, the error is fatal at the point at which it actually occurred.

Cada vez que o manipulador de erro passa o controle de volta para um procedimento de chamada, esse procedimento torna-se o procedimento atual.Each time the error handler passes control back to a calling procedure, that procedure becomes the current procedure. Depois que um erro é manipulado por um manipulador de erro em qualquer procedimento, a execução é retomada no procedimento atual no ponto designado pela instrução Resume.Once an error is handled by an error handler in any procedure, execution resumes in the current procedure at the point designated by the Resume statement.

Observação

Uma rotina de tratamento de erros não é um procedimento Sub ou um procedimento Function.An error-handling routine is not a Sub procedure or a Function procedure. É uma seção de código marcada por um rótulo de linha ou um número de linha.It is a section of code marked by a line label or a line number.

Propriedade NumberNumber Property

As rotinas de tratamento de erros dependem do valor na propriedade Number do objeto Err para determinar a causa do erro.Error-handling routines rely on the value in the Number property of the Err object to determine the cause of the error. 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.The routine should test or save relevant property values in the Err object before any other error can occur or before a procedure that might cause an error is called. Os valores de propriedade no objeto Err refletem apenas o erro mais recente.The property values in the Err object reflect only the most recent error. A mensagem de erro associada a Err.Number está contida em Err.Description.The error message associated with Err.Number is contained in Err.Description.

Instrução ThrowThrow Statement

Um erro que é gerado com o método Err.Raise define a propriedade Exception como uma instância recém-criada da classe Exception.An error that is raised with the Err.Raise method sets the Exception property to a newly created instance of the Exception class. Para oferecer suporte à geração de exceções de tipos de exceção derivadas, há suporte para uma instrução Throw no idioma.In order to support the raising of exceptions of derived exception types, a Throw statement is supported in the language. Isso usa um único parâmetro que é a instância de exceção a ser gerada.This takes a single parameter that is the exception instance to be thrown. O exemplo a seguir mostra como esses recursos podem ser usados com o suporte para manipulação de exceção existente:The following example shows how these features can be used with the existing exception handling support:

    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.Notice that the On Error GoTo statement traps all errors, regardless of the exception class.

Se houver erro, retome avançarOn 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 de 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.On Error Resume Next causes execution to continue with the statement immediately following the statement that caused the run-time error, or with the statement immediately following the most recent call out of the procedure containing the On Error Resume Next statement. Essa instrução permite que a execução continue apesar de um erro de tempo de execução.This statement allows execution to continue despite a run-time error. Você pode colocar a rotina de tratamento de erros em que o erro ocorreria em vez de transferir o controle para outro local dentro do procedimento.You can place the error-handling routine where the error would occur rather than transferring control to another location within the procedure. Uma instrução On Error Resume Next se torna inativa quando outro procedimento é chamado, portanto, você deve executar uma instrução On Error Resume Next em cada rotina chamada se desejar o tratamento de erros embutidos dentro dessa rotina.An On Error Resume Next statement becomes inactive when another procedure is called, so you should execute an On Error Resume Next statement in each called routine if you want inline error handling within that routine.

Observação

A construção de On Error Resume Next pode ser preferível a On Error GoTo ao manipular erros gerados durante o acesso a outros objetos.The On Error Resume Next construct may be preferable to On Error GoTo when handling errors generated during access to other objects. A verificação de Err após cada interação com um objeto remove a ambiguidade sobre qual objeto foi acessado pelo código.Checking Err after each interaction with an object removes ambiguity about which object was accessed by the code. Você pode ter certeza de qual objeto colocou o código de erro em Err.Number, bem como qual objeto gerou originalmente o erro (o objeto especificado em Err.Source).You can be sure which object placed the error code in Err.Number, as well as which object originally generated the error (the object specified in Err.Source).

Se houver erro, GoTo 0On Error GoTo 0

On Error GoTo 0 desabilita o tratamento de erros no procedimento atual.On Error GoTo 0 disables error handling in the current procedure. 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 como 0.It doesn't specify line 0 as the start of the error-handling code, even if the procedure contains a line numbered 0. Sem uma instrução On Error GoTo 0, um manipulador de erro é desabilitado automaticamente quando um procedimento é encerrado.Without an On Error GoTo 0 statement, an error handler is automatically disabled when a procedure is exited.

Se houver erro GoTo-1On Error GoTo -1

On Error GoTo -1 desabilita a exceção no procedimento atual.On Error GoTo -1 disables the exception in the current procedure. 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.It does not specify line -1 as the start of the error-handling code, even if the procedure contains a line numbered -1. Sem uma instrução On Error GoTo -1, uma exceção é desabilitada automaticamente quando um procedimento é encerrado.Without an On Error GoTo -1 statement, an exception is automatically disabled when a procedure is exited.

Para evitar que o código de tratamento de erros seja executado quando não houve erro, coloque uma instrução Exit Sub, Exit Functionou Exit Property imediatamente antes da rotina de tratamento de erros, como no fragmento a seguir:To prevent error-handling code from running when no error has occurred, place an Exit Sub, Exit Function, or Exit Property statement immediately before the error-handling routine, as in the following fragment:

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.Here, the error-handling code follows the Exit Sub statement and precedes the End Sub statement to separate it from the procedure flow. Você pode posicionar o código de tratamento de erros em qualquer lugar em um procedimento.You can place error-handling code anywhere in a procedure.

Erros não interceptadosUntrapped Errors

Erros não interceptados em objetos são retornados ao aplicativo de controle quando o objeto está sendo executado como um arquivo executável.Untrapped errors in objects are returned to the controlling application when the object is running as an executable file. No ambiente de desenvolvimento, os erros não interceptados serão retornados para o aplicativo de controle somente se as opções apropriadas estiverem definidas.Within the development environment, untrapped errors are returned to the controlling application only if the proper options are set. 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.See your host application's documentation for a description of which options should be set during debugging, how to set them, and whether the host can create classes.

Se você criar um objeto que acessa outros objetos, deverá tentar lidar com os erros não manipulados que eles passam de volta.If you create an object that accesses other objects, you should try to handle any unhandled errors they pass back. Se você não puder, mapeie os códigos de erro em Err.Number para um de seus próprios erros e, em seguida, passe-os de volta para o chamador do seu objeto.If you cannot, map the error codes in Err.Number to one of your own errors and then pass them back to the caller of your object. Você deve especificar seu erro adicionando o código de erro à constante VbObjectError.You should specify your error by adding your error code to the VbObjectError constant. Por exemplo, se o código de erro for 1052, atribua-o da seguinte maneira:For example, if your error code is 1052, assign it as follows:

Err.Number = vbObjectError + 1052

Cuidado

Os erros do sistema durante chamadas para DLLs (bibliotecas de vínculo dinâmico) do Windows não geram exceções e não podem ser interceptados com Visual Basic interceptação de erro.System errors during calls to Windows dynamic-link libraries (DLLs) do not raise exceptions and cannot be trapped with Visual Basic error trapping. Ao chamar as funções de DLL, você deve verificar cada valor de retorno para êxito ou falha (de acordo com as especificações de API) e, em caso de falha, verifique o valor na propriedade LastDLLError do objeto de Err.When calling DLL functions, you should check each return value for success or failure (according to the API specifications), and in the event of a failure, check the value in the Err object's LastDLLError property.

ExemploExample

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.This example first uses the On Error GoTo statement to specify the location of an error-handling routine within a procedure. No exemplo, uma tentativa de dividir por zero gera o erro número 6.In the example, an attempt to divide by zero generates error number 6. O erro é tratado na rotina de tratamento de erros e, em seguida, o controle é retornado para a instrução que causou o erro.The error is handled in the error-handling routine, and control is then returned to the statement that caused the error. A instrução On Error GoTo 0 desativa a interceptação de erros.The On Error GoTo 0 statement turns off error trapping. Em seguida, a instrução On Error Resume Next é usada para adiar a interceptação de erros para que o contexto do erro gerado pela próxima instrução possa ser conhecido para determinados.Then the On Error Resume Next statement is used to defer error trapping so that the context for the error generated by the next statement can be known for certain. Observe que Err.Clear é usado para limpar as propriedades do objeto Err depois que o erro é manipulado.Note that Err.Clear is used to clear the Err object's properties after the error is handled.

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

{1>{2>Requisitos<2}<1}Requirements

Namespace: Microsoft. VisualBasicNamespace: Microsoft.VisualBasic

Assembly: Visual Basic a biblioteca de tempo de execução (em Microsoft. VisualBasic. dll)Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

Consulte tambémSee also