SqlException Classe

Definição

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacote:

Microsoft.Data.SqlClient v5.2.0

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 sealed class SqlException : System.Data.Common.DbException

type SqlException = class
    inherit DbException

Public NotInheritable Class SqlException
Inherits DbException

Herança

DbException

SqlException

Exemplos

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

using Microsoft.Data.SqlClient;
using System.Text;

class Program
{
    static void Main()
    {
        string s = GetConnectionString();
        ShowSqlException(s);
        Console.ReadLine();
    }
    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());
            }
        }
    }

    static private string GetConnectionString()
    {
        // To avoid storing the connection string in your code, 
        // you can retrieve it from a configuration file.
        return "Data Source=(local);Initial Catalog=AdventureWorks;"
            + "Integrated Security=SSPI";
    }
}

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

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.
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.
LineNumber	Obtém o número de linha dentro do lote de comandos Transact-SQL ou procedimento armazenado que gerou o erro.
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.
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.

Métodos

GetObjectData(SerializationInfo, StreamingContext)	Define o SerializationInfo com informações sobre a exceção.
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).

Confira também

• SqlError
• SqlErrorCollection