Eventos de conexãoConnection Events

Todos os provedores de dados de .NET Framework têm objetos de conexão com dois eventos que você pode usar para recuperar mensagens informativas de uma fonte de dados ou para determinar se o estado de uma conexão foi alterado.All of the .NET Framework data providers have Connection objects with two events that you can use to retrieve informational messages from a data source or to determine if the state of a Connection has changed. A tabela a seguir descreve os eventos do objeto de conexão .The following table describes the events of the Connection object.

eventoEvent DescriçãoDescription
InfoMessageInfoMessage Ocorre quando uma mensagem informativa é retornada de uma fonte de dados.Occurs when an informational message is returned from a data source. As mensagens informativas são as mensagens de uma fonte de dados que não resultam em uma exceção sendo lançada.Informational messages are messages from a data source that do not result in an exception being thrown.
StateChangeStateChange Ocorre quando o estado da conexão é alterado.Occurs when the state of the Connection changes.

Trabalhando com o evento InfoMessageWorking with the InfoMessage Event

Você pode recuperar avisos e mensagens informativas de uma fonte de dados do SQL Server usando o evento InfoMessage do objeto SqlConnection.You can retrieve warnings and informational messages from a SQL Server data source using the InfoMessage event of the SqlConnection object. Os erros retornados da fonte de dados com um nível de severidade de 11 a 16 geram uma exceção.Errors returned from the data source with a severity level of 11 through 16 cause an exception to be thrown. No entanto, o evento InfoMessage pode ser usado para obter as mensagens da fonte de dados que não estão associadas a um erro.However, the InfoMessage event can be used to obtain messages from the data source that are not associated with an error. No caso do Microsoft SQL Server, qualquer erro com uma severidade de 10 ou menos é considerado uma mensagem informativa e podem ser capturado usando o evento InfoMessage.In the case of Microsoft SQL Server, any error with a severity of 10 or less is considered to be an informational message, and can be captured by using the InfoMessage event. Para obter mais informações, consulte o artigo mecanismo de banco de dados severidades de erro .For more information, see the Database Engine Error Severities article.

O InfoMessage evento recebe um SqlInfoMessageEventArgs objeto contendo, em sua propriedade Errors , uma coleção das mensagens da fonte de dados.The InfoMessage event receives an SqlInfoMessageEventArgs object containing, in its Errors property, a collection of the messages from the data source. Você pode consultar os objetos de erro nesta coleção para obter o número do erro e o texto da mensagem, bem como a origem do erro.You can query the Error objects in this collection for the error number and message text, as well as the source of the error. O provedor de dados .NET Framework para SQL Server também inclui detalhes sobre o banco de dados, o procedimento armazenado e o número da linha da qual a mensagem veio.The .NET Framework Data Provider for SQL Server also includes detail about the database, stored procedure, and line number that the message came from.

ExemploExample

O exemplo de código a seguir mostra como adicionar um manipulador de eventos para o evento InfoMessage.The following code example shows how to add an event handler for the InfoMessage event.

' Assumes that connection represents a SqlConnection object.  
  AddHandler connection.InfoMessage, _  
    New SqlInfoMessageEventHandler(AddressOf OnInfoMessage)  
  
Private Shared Sub OnInfoMessage(sender As Object, _  
  args As SqlInfoMessageEventArgs)  
  Dim err As SqlError  
  For Each err In args.Errors  
    Console.WriteLine("The {0} has received a severity {1}, _  
       state {2} error number {3}\n" & _  
      "on line {4} of procedure {5} on server {6}:\n{7}", _  
      err.Source, err.Class, err.State, err.Number, err.LineNumber, _  
    err.Procedure, err.Server, err.Message)  
  Next  
End Sub  
// Assumes that connection represents a SqlConnection object.  
  connection.InfoMessage +=   
    new SqlInfoMessageEventHandler(OnInfoMessage);  
  
protected static void OnInfoMessage(  
  object sender, SqlInfoMessageEventArgs args)  
{  
  foreach (SqlError err in args.Errors)  
  {  
    Console.WriteLine(  
  "The {0} has received a severity {1}, state {2} error number {3}\n" +  
  "on line {4} of procedure {5} on server {6}:\n{7}",  
   err.Source, err.Class, err.State, err.Number, err.LineNumber,   
   err.Procedure, err.Server, err.Message);  
  }  
}  

Tratando erros como InfoMessagesHandling Errors as InfoMessages

O evento InfoMessage acionará normalmente apenas para mensagens informativas e de aviso que são enviadas do servidor.The InfoMessage event will normally fire only for informational and warning messages that are sent from the server. No entanto, quando ocorre um erro real, a execução do método ExecuteNonQuery ou ExecuteReader que iniciou a operação do servidor é interrompida e uma exceção é lançada.However, when an actual error occurs, the execution of the ExecuteNonQuery or ExecuteReader method that initiated the server operation is halted and an exception is thrown.

Se você quiser continuar a processar o restante das instruções em um comando independentemente de qualquer erro gerado pelo servidor, defina a propriedade FireInfoMessageEventOnUserErrors do SqlConnection como true.If you want to continue processing the rest of the statements in a command regardless of any errors produced by the server, set the FireInfoMessageEventOnUserErrors property of the SqlConnection to true. Isso faz a conexão acionar o evento InfoMessage para erros em vez de gerar uma exceção e interromper o processamento.Doing this causes the connection to fire the InfoMessage event for errors instead of throwing an exception and interrupting processing. O aplicativo cliente pode, em seguida, manipular esse evento e responder às condições de erro.The client application can then handle this event and respond to error conditions.

Observação

Um erro com um nível de severidade de 17 ou acima disso faz o servidor parar de processar o comando e deve ser tratado como uma exceção.An error with a severity level of 17 or above that causes the server to stop processing the command must be handled as an exception. Nesse caso, uma exceção é gerada independentemente de como o erro é tratado no evento InfoMessage.In this case, an exception is thrown regardless of how the error is handled in the InfoMessage event.

Trabalhando com o evento StateChangeWorking with the StateChange Event

O evento StateChange ocorre quando o estado de uma conexão é alterado.The StateChange event occurs when the state of a Connection changes. O evento StateChange recebe StateChangeEventArgs que permite que você determine a alteração no estado da conexão usando as propriedades OriginalState e CurrentState .The StateChange event receives StateChangeEventArgs that enable you to determine the change in state of the Connection by using the OriginalState and CurrentState properties. A propriedade OriginalState é uma ConnectionState enumeração que indica o estado da conexão antes de ela ser alterada.The OriginalState property is a ConnectionState enumeration that indicates the state of the Connection before it changed. CurrentState é uma ConnectionState enumeração que indica o estado da conexão após sua alteração.CurrentState is a ConnectionState enumeration that indicates the state of the Connection after it changed.

O exemplo de código a seguir usa o evento StateChange para gravar uma mensagem no console quando o estado da conexão é alterado.The following code example uses the StateChange event to write a message to the console when the state of the Connection changes.

' Assumes connection represents a SqlConnection object.  
  AddHandler connection.StateChange, _  
    New StateChangeEventHandler(AddressOf OnStateChange)  
  
Protected Shared Sub OnStateChange( _  
  sender As Object, args As StateChangeEventArgs)  
  
  Console.WriteLine( _  
  "The current Connection state has changed from {0} to {1}.", _  
  args.OriginalState, args.CurrentState)  
End Sub  
// Assumes connection represents a SqlConnection object.  
  connection.StateChange  += new StateChangeEventHandler(OnStateChange);  
  
protected static void OnStateChange(object sender,   
  StateChangeEventArgs args)  
{  
  Console.WriteLine(  
    "The current Connection state has changed from {0} to {1}.",  
      args.OriginalState, args.CurrentState);  
}  

Consulte tambémSee also