SqlException Classe

Definição

Namespace:

System.Data.SqlClient

Assembly:

System.Data.dll

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

[System.Serializable]
public sealed class SqlException : System.Data.Common.DbException

[<System.Serializable>]
type SqlException = class
    inherit DbException

Public NotInheritable Class SqlException
Inherits DbException

Herança

Object

Exception

SystemException

ExternalException

DbException

SqlException

Atributos

SerializableAttribute

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 do .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.

Mensagens que têm um nível de gravidade igual a 10 ou menos são informativas e indicam problemas causados por erros nas informações que um usuário inseriu. Os níveis de gravidade 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 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 gravidade é 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 pelo SQL Server, consulte Eventos e erros do Mecanismo de Banco de Dados. A SqlException classe é mapeada para a gravidade do SQL Server.

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, capturar falhas e repetir a transação.

Observe que, a partir do .NET Framework 4.5, SqlException pode retornar um interno Win32Exception.

A classe de exceção de um provedor de dados do .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, os tipos de provedor de dados do .NET Framework podem gerar exceções do .NET Framework, como System.OutOfMemoryException e System.Threading.ThreadAbortException. A recuperação dessas exceções pode não ser possível.

A entrada incorreta pode fazer com que um tipo de provedor de dados do .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 quaisquer 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 de provedor de dados do .NET Framework falhe em um thread de pool de threads sem código de usuário na pilha. Nesse caso, e ao usar chamadas de método assíncronas, 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 foi gerado ao executar um DbBatch, faz referência ao 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 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.
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).

Eventos

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

Confira também

• SqlError
• SqlErrorCollection
• Visão geral do ADO.NET