SqlException Classe

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
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, 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 Provedor de Dados de .NET Framework para SQL Server encontra um erro gerado no servidor.This class is created whenever the .NET Framework Data Provider for SQL Server encounters an error generated from the server. (Os erros do lado do cliente são lançados como exceções de Common Language Runtime padrão.) SqlException sempre contém pelo menos uma instância do 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 um nível de severidade de 10 ou menos são informativas e indicam problemas causados por erros nas informações inseridas por um usuário.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. Os 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 ocorre um erro de nível 17, 18 ou 19, você pode continuar trabalhando, embora talvez não seja possível executar uma determinada instrução.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 superior, 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 por SQL Server, consulte mecanismo de banco de dados eventos e erros.For information about the warning and informational messages sent by SQL Server, see Database Engine Events and Errors. A SqlException classe é mapeada para SQL Server severidade.The SqlException class maps to SQL Server severity.

Veja a seguir as informações gerais sobre como lidar com exceções.The following is general information on handling exceptions. Seu código deve capturar exceções para impedir que o aplicativo falhe e para permitir a exibição de uma mensagem de erro relevante 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 as transações de banco de dados para garantir que eles sejam 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 System. Data. OleDb. OleDbConnection, System. Data. ODBC. ODBCConnection e System. Data. SqlClient. SqlConnection) garantem dados consistentes, independentemente das exceções geradas 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. As transações podem falhar, portanto, falhas de captura e repetição da transação.Transactions can fail, so catch failures and retry the transaction.

Observe que, começando com .NET Framework 4,5, SqlException pode retornar um interno 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, System. Data. 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 obter o melhor nível de detalhes do erro, Capture essas exceções e use 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, .NET Framework tipos de provedor de dados podem gerar .NET Framework exceções 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. A recuperação dessas exceções pode não ser possível.Recovery from these exceptions may not be possible.

Entrada inadequada pode fazer com que um .NET Framework tipo de provedor de dados gere 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 gerar System. InvalidOperationException.Calling a method at the wrong time can raise System.InvalidOperationException.

Portanto, em geral, grave um manipulador de exceção que captura quaisquer exceções específicas de provedor, bem como exceções da 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 de provedor de dados .NET Framework falhe em um thread de pool de threads sem 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 evento para lidar com 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

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

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

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

(Herdado de Exception)
ErrorCode

Obtém o HRESULT do erro.Gets the HRESULT of the error.

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

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.

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

(Herdado de Exception)
InnerException

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

(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.Indicates whether the error represented by this DbException could be a transient error, i.e. if retrying the triggering operation may succeed without any other change.

(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.Gets the line number within the Transact-SQL command batch or stored procedure that generated the error.

Message

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

Message

Obtém uma mensagem que descreve a exceção atual.Gets a message that describes the current exception.

(Herdado de Exception)
Number

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

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

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

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

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.For database providers which support it, contains a standard SQL 5-character return code indicating the success or failure of the database operation. 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.The first 2 characters represent the class of the return code (e.g. error, success), while the last 3 characters represent the subclass, allowing detection of error scenarios in a database-portable way.

Para provedores de banco de dados que não são compatíveis ou para cenários de erro inaplicáveis, contém null.For database providers which don't support it, or for inapplicable error scenarios, contains null.

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

(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".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

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

(Herdado de Exception)

Métodos

Equals(Object)

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

(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.When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.

(Herdado de Exception)
GetHashCode()

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

(Herdado de Object)
GetObjectData(SerializationInfo, StreamingContext)

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

GetObjectData(SerializationInfo, StreamingContext)

Quando substituído em uma classe derivada, define o SerializationInfo com informações sobre a exceção.When overridden in a derived class, sets the SerializationInfo with information about the exception.

(Herdado de Exception)
GetType()

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

(Herdado de Exception)
MemberwiseClone()

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

(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).Returns a string that represents the current SqlException object, and includes the client connection ID (for more information, see ClientConnectionId).

ToString()

Retorna uma cadeia de caracteres que contém o HRESULT do erro.Returns a string that contains the HRESULT of the error.

(Herdado de ExternalException)
ToString()

Cria e retorna uma representação de cadeia de caracteres da exceção atual.Creates and returns a string representation of the current exception.

(Herdado de Exception)

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.Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception.

(Herdado de Exception)

Aplica-se a

Confira também