SqlException SqlException SqlException SqlException Class

Definição

A exceção gerada quando o SQL Server retorna um aviso ou erro.The exception that is thrown when SQL Server returns a warning or error. Essa classe não pode ser herdada.This class cannot be inherited.

public ref class SqlException sealed : System::Data::Common::DbException
[System.Serializable]
public sealed class SqlException : System.Data.Common.DbException
type SqlException = class
    inherit DbException
Public NotInheritable Class SqlException
Inherits DbException
Herança
Atributos

Exemplos

O exemplo a seguir gera um SqlException e, em seguida, exibe a exceção.The following example generates a SqlException and then displays the exception.

public static void ShowSqlException(string connectionString)
{
    string queryString = "EXECUTE NonExistantStoredProcedure";
    StringBuilder errorMessages = new StringBuilder();
    
    using (SqlConnection connection = new SqlConnection(connectionString))
    {
        SqlCommand command = new SqlCommand(queryString, connection);
        try
        {
            command.Connection.Open();
            command.ExecuteNonQuery();
        }
        catch (SqlException ex)
        {
            for (int i = 0; i < ex.Errors.Count; i++)
            {
                errorMessages.Append("Index #" + i + "\n" +
                    "Message: " + ex.Errors[i].Message + "\n" +
                    "LineNumber: " + ex.Errors[i].LineNumber + "\n" +
                    "Source: " + ex.Errors[i].Source + "\n" +
                    "Procedure: " + ex.Errors[i].Procedure + "\n");
            }
            Console.WriteLine(errorMessages.ToString());
        }
    }
}
Public Sub ShowSqlException(ByVal connectionString As String)
    Dim queryString As String = "EXECUTE NonExistantStoredProcedure"
    Dim errorMessages As New StringBuilder()

    Using connection As New SqlConnection(connectionString)
        Dim command As New SqlCommand(queryString, connection)

        Try
            command.Connection.Open()
            command.ExecuteNonQuery()

        Catch ex As SqlException
            Dim i As Integer
            For i = 0 To ex.Errors.Count - 1
                errorMessages.Append("Index #" & i.ToString() & ControlChars.NewLine _
                    & "Message: " & ex.Errors(i).Message & ControlChars.NewLine _
                    & "LineNumber: " & ex.Errors(i).LineNumber & ControlChars.NewLine _
                    & "Source: " & ex.Errors(i).Source & ControlChars.NewLine _
                    & "Procedure: " & ex.Errors(i).Procedure & ControlChars.NewLine)
            Next i
            Console.WriteLine(errorMessages.ToString())
        End Try
    End Using
End Sub

Comentários

Essa classe é criada sempre que o .NET Framework Data Provider para SQL Server encontra um erro gerado do servidor.This class is created whenever the .NET Framework Data Provider for SQL Server encounters an error generated from the server. (Erros do lado do cliente são gerados como exceções de tempo de execução de linguagem comum padrão). SqlException sempre contém pelo menos uma instância de SqlError.(Client side errors are thrown as standard common language runtime exceptions.) SqlException always contains at least one instance of SqlError.

As mensagens que têm uma severidade de nível de 10 ou menos são informativas e indicam problemas causados por erros nas informações que um usuário inseriu.Messages that have a severity level of 10 or less are informational and indicate problems caused by mistakes in information that a user has entered. Níveis de severidade de 11 a 16 são gerados pelo usuário e podem ser corrigidos pelo usuário.Severity levels from 11 through 16 are generated by the user, and can be corrected by the user. Os níveis de severidade de 17 a 25 indicam erros de software ou hardware.Severity levels from 17 through 25 indicate software or hardware errors. Quando um nível 17, 18 ou 19 erro ocorrer, você pode continuar trabalhando, embora você não poderá executar uma instrução específica.When a level 17, 18, or 19 error occurs, you can continue working, although you might not be able to execute a particular statement.

O SqlConnection permanece aberto quando o nível de severidade é 19 ou inferior.The SqlConnection remains open when the severity level is 19 or less. Quando o nível de severidade é 20 ou maior, o servidor normalmente fecha o SqlConnection.When the severity level is 20 or greater, the server ordinarily closes the SqlConnection. No entanto, o usuário pode reabrir a conexão e continuar.However, the user can reopen the connection and continue. Em ambos os casos, SqlException é gerada pelo método que executa o comando.In both cases, a SqlException is generated by the method executing the command.

Para obter informações sobre as mensagens de aviso e informativas enviadas pelo SQL Server, consulte erros e eventos do mecanismo de banco de dados.For information about the warning and informational messages sent by SQL Server, see Database Engine Events and Errors. O SqlException é mapeado para a severidade do SQL Server de classe.The SqlException class maps to SQL Server severity.

Veja a seguir informações gerais sobre o tratamento de exceções.The following is general information on handling exceptions. Seu código deve capturar exceções para impedir que o aplicativo falhando e permitir exibir uma mensagem de erro relevantes para o usuário.Your code should catch exceptions to prevent the application from crashing and to allow displaying a relevant error message to the user. Você pode usar transações de banco de dados para garantir que os dados são consistentes, independentemente do que acontece no aplicativo cliente (incluindo uma falha).You can use database transactions to ensure that the data is consistent regardless of what happens in the client application (including a crash). Recursos como System.Transaction.TransactionScope ou o método BeginTransaction (em OleDbConnection, System.Data.ODBC.ODBCConnection e SqlConnection) Certifique-se de dados consistentes, independentemente de exceções acionado por um provedor.Features like System.Transaction.TransactionScope or the BeginTransaction method (in System.Data.OleDb.OleDbConnection, System.Data.ODBC.ODBCConnection, and System.Data.SqlClient.SqlConnection) ensure consistent data regardless of exceptions raised by a provider. Transações podem falhar, então, detectar falhas e tente a transação novamente.Transactions can fail, so catch failures and retry the transaction.

Observe que a partir do .NET Framework 4.5, SqlException pode retornar uma interna Win32Exception.Note that beginning with .NET Framework 4.5, SqlException can return an inner Win32Exception.

A classe de exceção de um provedor de dados .NET Framework relata erros específicos do provedor.The exception class of a .NET Framework data provider reports provider-specific errors. Por exemplo, System.Data.Odbc tem OdbcException, OLEDB tem OleDbException e System.Data.SqlClient tem SqlException.For example System.Data.Odbc has OdbcException, System.Data.OleDb has OleDbException, and System.Data.SqlClient has SqlException. Para o melhor nível de detalhe do erro, capturar essas exceções e usar os membros dessas classes de exceção para obter detalhes do erro.For the best level of error detail, catch these exceptions and use the members of these exception classes to get details of the error.

Além dos erros específicos do provedor, os tipos de provedor de dados .NET Framework podem gerar exceções do .NET Framework, como System. OutOfMemoryException e System.Threading.ThreadAbortException.In addition to the provider-specific errors, .NET Framework data provider types can raise .NET Framework exceptions such as System.OutOfMemoryException and System.Threading.ThreadAbortException. Recuperação dessas exceções pode não ser possível.Recovery from these exceptions may not be possible.

Uma entrada incorreta pode causar um tipo de provedor de dados .NET Framework gerar uma exceção, como System. ArgumentException ou System. IndexOutOfRangeException.Bad input can cause a .NET Framework data provider type to raise an exception such as System.ArgumentException or System.IndexOutOfRangeException. Chamar um método na hora errada pode elevar System. InvalidOperationException.Calling a method at the wrong time can raise System.InvalidOperationException.

Portanto, em geral, escrever um manipulador de exceção que captura qualquer provedor de exceções específicas, bem como as exceções do common language runtime.So, in general, write an exception handler that catches any provider specific exceptions as well as exceptions from the common language runtime. Eles podem ser dispostos em camadas da seguinte maneira:These can be layered as follows:

try {  
   // code here  
}  
catch (SqlException odbcEx) {  
   // Handle more specific SqlException exception here.  
}  
catch (Exception ex) {  
   // Handle generic ones here.  
}  

ou:Or:

try {  
   // code here  
}  
catch (Exception ex) {  
   if (ex is SqlException) {  
      // Handle more specific SqlException exception here.  
   }  
   else {  
      // Handle generic ones here.  
   }  
}  

Também é possível que uma chamada de método do provedor de dados .NET Framework falhar em um pool de threads sem nenhum código de usuário na pilha.It is also possible for a .NET Framework data provider method call to fail on a thread pool thread with no user code on the stack. Nesse caso e ao usar chamadas de método assíncrono, você deve registrar o UnhandledException eventos para tratar essas exceções e evitar a falha do aplicativo.In this case, and when using asynchronous method calls, you must register the UnhandledException event to handle those exceptions and avoid application crash.

Propriedades

Class Class Class Class

Obtém o nível de gravidade do erro retornado do .NET Framework Data Provider para SQL Server.Gets the severity level of the error returned from the .NET Framework Data Provider for SQL Server.

ClientConnectionId ClientConnectionId ClientConnectionId ClientConnectionId

Representa a ID de conexão do cliente.Represents the client connection ID. Para obter mais informações, consulte Rastreamento de dados no ADO.NET.For more information, see Data Tracing in ADO.NET.

Data Data Data Data

Obtém uma coleção de pares de chave/valor que fornecem informações adicionais definidas pelo usuário sobre a exceção.Gets a collection of key/value pairs that provide additional user-defined information about the exception.

(Inherited from Exception)
Errors Errors Errors Errors

Obtém uma coleção de um ou mais objetos SqlError que fornecem informações detalhadas sobre as exceções geradas pelo Provedor de Dados .NET Framework para SQL Server.Gets a collection of one or more SqlError objects that give detailed information about exceptions generated by the .NET Framework Data Provider for SQL Server.

HelpLink HelpLink HelpLink HelpLink

Obtém ou define um link para o arquivo de ajuda associado a essa exceção.Gets or sets a link to the help file associated with this exception.

(Inherited from Exception)
HResult HResult HResult HResult

Obtém ou define HRESULT, um valor numérico codificado que é atribuído a uma exceção específica.Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.

(Inherited from Exception)
InnerException InnerException InnerException InnerException

Obtém a instância Exception que causou a exceção atual.Gets the Exception instance that caused the current exception.

(Inherited from Exception)
LineNumber LineNumber LineNumber LineNumber

Obtém o número de linha dentro do lote de comandos Transact-SQL ou procedimento armazenado que gerou o erro.Gets the line number within the Transact-SQL command batch or stored procedure that generated the error.

Message Message Message Message

Obtém o texto que descreve o erro.Gets the text describing the error.

Number Number Number Number

Obtém um número que identifica o tipo de erro.Gets a number that identifies the type of error.

Procedure Procedure Procedure Procedure

Obtém o nome do procedimento armazenado ou da RPC (chamada de procedimento remoto) que gerou o erro.Gets the name of the stored procedure or remote procedure call (RPC) that generated the error.

Server Server Server Server

Obtém o nome do computador que está executando uma instância do SQL Server que gerou o erro.Gets the name of the computer that is running an instance of SQL Server that generated the error.

Source Source Source Source

Obtém o nome do provedor que gerou o erro.Gets the name of the provider that generated the error.

StackTrace StackTrace StackTrace StackTrace

Obtém uma representação de cadeia de caracteres de quadros imediatos na pilha de chamadas.Gets a string representation of the immediate frames on the call stack.

(Inherited from Exception)
State State State State

Obtém um código de erro numérico do SQL Server que representa um erro, aviso ou uma mensagem de "nenhum dado foi encontrado".Gets a numeric error code from SQL Server that represents an error, warning or "no data found" message. Para obter mais informações sobre como decodificar esses valores, confira Erros e eventos do Mecanismo de Banco de Dados.For more information about how to decode these values, see Database Engine Events and Errors.

TargetSite TargetSite TargetSite TargetSite

Obtém o método que gerou a exceção atual.Gets the method that throws the current exception.

(Inherited from Exception)

Métodos

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetBaseException() GetBaseException() GetBaseException() GetBaseException()

Quando substituído em uma classe derivada, retorna a Exception que é a causa raiz de uma ou mais exceções subsequentes.When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.

(Inherited from Exception)
GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Serve como a função de hash padrão.Serves as the default hash function.

(Inherited from Object)
GetObjectData(SerializationInfo, StreamingContext) GetObjectData(SerializationInfo, StreamingContext) GetObjectData(SerializationInfo, StreamingContext) GetObjectData(SerializationInfo, StreamingContext)

Define o SerializationInfo com informações sobre a exceção.Sets the SerializationInfo with information about the exception.

GetType() GetType() GetType() GetType()

Obtém o tipo de tempo de execução da instância atual.Gets the runtime type of the current instance.

(Inherited from Exception)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Inherited from Object)
ToString() ToString() ToString() ToString()

Retorna uma cadeia de caracteres que representa o objeto SqlException atual e que inclui a ID de conexão do cliente (para obter mais informações, consulte ClientConnectionId).Returns a string that represents the current SqlException object, and includes the client connection ID (for more information, see ClientConnectionId).

Eventos

SerializeObjectState SerializeObjectState SerializeObjectState SerializeObjectState

Ocorre quando uma exceção é serializada para criar um objeto de estado de exceção que contém dados serializados sobre a exceção.Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception.

(Inherited from Exception)

Aplica-se a

Veja também