SqlException Classe

Definição

A exceção gerada quando o SQL Server retorna um aviso ou erro. Essa classe não pode ser herdada.

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

Exemplos

O exemplo a seguir gera um SqlException e exibe a exceção.

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 provedor de dados .NET Framework para SQL Server encontra um erro gerado do servidor. (Os erros do lado do cliente são gerados como exceções padrão do Common Language Runtime.) SqlException sempre contém pelo menos uma instância de SqlError.

As mensagens que têm um nível de severidade de 10 ou menos são informativas e indicam problemas causados por erros nas informações que um usuário inseriu. Os níveis de severidade de 11 a 16 são gerados pelo usuário e podem ser corrigidos pelo usuário. Os níveis de severidade de 17 a 25 indicam erros de software ou hardware. Quando ocorre um erro de nível 17, 18 ou 19, você pode continuar trabalhando, embora talvez não seja possível executar uma instrução específica.

O SqlConnection permanece aberto quando o nível de severidade é 19 ou inferior. Quando o nível de severidade é 20 ou maior, o servidor normalmente fecha o SqlConnection. No entanto, o usuário pode reabrir a conexão e continuar. Em ambos os casos, SqlException é gerada pelo método que executa o comando.

Para obter informações sobre o aviso e as mensagens informativas enviadas por SQL Server, consulte Eventos e erros do Mecanismo de Banco de Dados. A SqlException classe mapeia para SQL Server gravidade.

Veja a seguir informações gerais sobre como lidar com exceções. Seu código deve capturar exceções para evitar que o aplicativo falhe e permitir a exibição de uma mensagem de erro relevante para o usuário. Você pode usar transações de banco de dados para garantir que os dados sejam consistentes independentemente do que acontece no aplicativo cliente (incluindo uma falha). Recursos como System.Transaction.TransactionScope ou o método BeginTransaction (em System.Data.OleDb.OleDbConnection, System.Data.ODBC.ODBCConnection e System.Data.SqlClient.SqlConnection) garantem dados consistentes, independentemente das exceções geradas por um provedor. As transações podem falhar, portanto, capture falhas e repita a transação.

Observe que, começando com .NET Framework 4.5, SqlException pode retornar um interno Win32Exception.

A classe de exceção de um provedor de dados .NET Framework relata erros específicos do provedor. Por exemplo, System.Data.Odbc tem OdbcException, System.Data.OleDb tem OleDbException e System.Data.SqlClient tem SqlException. Para obter o melhor nível de detalhes de erro, capture essas exceções e use os membros dessas classes de exceção para obter detalhes do erro.

Além dos erros específicos do provedor, .NET Framework tipos de provedor de dados podem gerar exceções .NET Framework, como System.OutOfMemoryException e System.Threading.ThreadAbortException. A recuperação dessas exceções pode não ser possível.

A entrada inválida pode fazer com que um tipo de provedor de dados .NET Framework gere uma exceção, como System.ArgumentException ou System.IndexOutOfRangeException. Chamar um método na hora errada pode gerar System.InvalidOperationException.

Portanto, em geral, escreva um manipulador de exceção que captura exceções específicas do provedor, bem como exceções do Common Language Runtime. Eles podem ser em camadas da seguinte maneira:

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

Ou:

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 falhe em um thread do pool de threads sem código de usuário na pilha. Nesse caso, e ao usar chamadas de método assíncrono, você deve registrar o UnhandledException evento para lidar com essas exceções e evitar a falha do aplicativo.

Propriedades

BatchCommand

Se isso DbException tiver sido gerado ao executar um DbBatch, referencia o específico DbBatchCommand que disparou a exceção.

(Herdado de DbException)
Class

Obtém o nível de gravidade do erro retornado do .NET Framework Data Provider para SQL Server.

ClientConnectionId

Representa a ID de conexão do cliente. Para obter mais informações, consulte Rastreamento de dados no ADO.NET.

Data

Obtém uma coleção de pares de chave/valor que fornecem informações definidas pelo usuário adicionais sobre a exceção.

(Herdado de Exception)
DbBatchCommand

Quando substituído em uma classe derivada, se isso DbException tiver sido gerado ao executar um DbBatch, referencia o específico DbBatchCommand que disparou a exceção.

(Herdado de DbException)
ErrorCode

Obtém o HRESULT do erro.

(Herdado de ExternalException)
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.

HelpLink

Obtém ou define um link para o arquivo de ajuda associado a essa exceção.

(Herdado de Exception)
HResult

Obtém ou define HRESULT, um valor numérico codificado que é atribuído a uma exceção específica.

(Herdado de Exception)
InnerException

Obtém a instância Exception que causou a exceção atual.

(Herdado de Exception)
IsTransient

Indica se o erro representado pela DbException pode ser transitório, ou seja, se a repetição da operação de acionamento pode ter sucesso sem nenhuma outra alteração.

(Herdado de DbException)
LineNumber

Obtém o número de linha dentro do lote de comandos Transact-SQL ou procedimento armazenado que gerou o erro.

Message

Obtém o texto que descreve o erro.

Message

Obtém uma mensagem que descreve a exceção atual.

(Herdado de Exception)
Number

Obtém um número que identifica o tipo de erro.

Procedure

Obtém o nome do procedimento armazenado ou da RPC (chamada de procedimento remoto) que gerou o erro.

Server

Obtém o nome do computador que está executando uma instância do SQL Server que gerou o erro.

Source

Obtém o nome do provedor que gerou o erro.

SqlState

Para provedores de banco de dados compatíveis, contém um código de retorno SQL padrão de 5 caracteres que indica o êxito ou a falha da operação de banco de dados. Os dois primeiros caracteres representam a classe do código de retorno (por exemplo, erro ou êxito), enquanto os três últimos caracteres representam a subclasse, permitindo a detecção de cenários de erro em uma forma portátil de banco de dados.

Para provedores de banco de dados que não são compatíveis ou para cenários de erro inaplicáveis, contém null.

(Herdado de DbException)
StackTrace

Obtém uma representação de cadeia de caracteres de quadros imediatos na pilha de chamadas.

(Herdado de Exception)
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". Para obter mais informações sobre como decodificar esses valores, confira Erros e eventos do Mecanismo de Banco de Dados.

TargetSite

Obtém o método que gerou a exceção atual.

(Herdado de Exception)

Métodos

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.

(Herdado de Object)
GetBaseException()

Quando substituído em uma classe derivada, retorna a Exception que é a causa raiz de uma ou mais exceções subsequentes.

(Herdado de Exception)
GetHashCode()

Serve como a função de hash padrão.

(Herdado de Object)
GetObjectData(SerializationInfo, StreamingContext)

Define o SerializationInfo com informações sobre a exceção.

GetObjectData(SerializationInfo, StreamingContext)
Obsoleto.

Quando substituído em uma classe derivada, define o SerializationInfo com informações sobre a exceção.

(Herdado de Exception)
GetType()

Obtém o tipo de runtime da instância atual.

(Herdado de Exception)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
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).

ToString()

Retorna uma cadeia de caracteres que contém o HRESULT do erro.

(Herdado de ExternalException)
ToString()

Cria e retorna uma representação de cadeia de caracteres da exceção atual.

(Herdado de Exception)

Eventos

SerializeObjectState
Obsoleto.

Ocorre quando uma exceção é serializada para criar um objeto de estado de exceção que contém dados serializados sobre a exceção.

(Herdado de Exception)

Aplica-se a

Confira também