SqlException 類別

定義

命名空間:

System.Data.SqlClient

組件:

System.Data.dll

當 SQL Server 傳回警告或錯誤時，所擲回的例外狀況。 此類別無法獲得繼承。

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

繼承

Object

Exception

SystemException

ExternalException

DbException

SqlException

屬性

SerializableAttribute

範例

下列範例會產生 SqlException ，然後顯示例外狀況。

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

備註

每當 .NET Framework Data Provider for SQL Server 遇到從伺服器產生的錯誤時，就會建立這個類別。 (客戶端錯誤會擲回為標準 Common Language Runtime exceptions.) SqlException 一律包含至少一個 實例 SqlError。

嚴重性層級為 10 或更少的郵件為參考性，並指出使用者輸入之資訊中錯誤所造成的問題。 從 11 到 16 的嚴重性層級是由用戶產生，而且可由使用者更正。 17 到 25 的嚴重性層級表示軟體或硬體錯誤。 發生層級 17、18 或 19 錯誤時，您可以繼續運作，雖然您可能無法執行特定語句。

當嚴重性層級為 19 或低於 19 時，SqlConnection 仍保持開啟。 當嚴重性層級為 20 或更新時，伺服器通常會關閉 SqlConnection。 但是，使用者可以再次開啟連線，然後繼續進行。 在這兩個情況中，SqlException 皆由執行該命令的方法所產生。

如需 SQL Server 所傳送之警告和參考訊息的相關信息，請參閱 Database Engine 事件和錯誤。 類別 SqlException 對應至 SQL Server 嚴重性。

以下是處理例外狀況的一般資訊。 您的程式代碼應該攔截例外狀況，以防止應用程式當機，並允許向使用者顯示相關的錯誤訊息。 您可以使用資料庫交易來確保不論用戶端應用程式中發生什麼情況，都一致， (包括當機) 。 System.Transaction.TransactionScope 或 BeginTransaction 方法等功能 (System.Data.OleDb.OleDbConnection、System.Data.ODBC.ODBCConnection 和 System.Data.SqlClient.SqlConnection) 不論提供者所引發的例外狀況為何，都能確保一致的數據。 交易可能會失敗，因此攔截失敗並重試交易。

請注意，從 .NET Framework 4.5 開始， SqlException 可以傳回內部 Win32Exception。

.NET Framework 數據提供者的例外狀況類別會報告提供者特定的錯誤。 例如，System.Data.Odbc 有 OdbcException、System.Data.OleDb 有 OleDbException，而 System.Data.SqlClient 有 SqlException。 若要獲得最佳的錯誤詳細數據層級，請攔截這些例外狀況，並使用這些例外狀況類別的成員來取得錯誤的詳細數據。

除了提供者特定的錯誤之外，.NET Framework 數據類型還可以引發 .NET Framework 例外狀況，例如 System.OutOfMemoryException 和 System.Threading.ThreadAbortException。 無法從這些例外狀況復原。

不正確的輸入可能會導致 .NET Framework 數據類型引發例外狀況，例如 System.ArgumentException 或 System.IndexOutOfRangeException。 在錯誤時間呼叫方法可能會引發 System.InvalidOperationException。

因此，一般而言，撰寫例外狀況處理程式，以攔截任何提供者特定的例外狀況，以及 Common Language Runtime 的例外狀況。 這些可以分層，如下所示：

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

或：

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

您也可以讓 .NET Framework 數據提供者方法呼叫在線程集區線程上失敗，而堆疊上沒有用戶程序代碼。 在此情況下，在使用異步方法呼叫時，您必須註冊 UnhandledException 事件來處理這些例外狀況，並避免應用程式當機。

屬性

BatchCommand	如果在執行 DbBatch時擲回這個DbException值，則參考觸發例外狀況的特定 DbBatchCommand 。 (繼承來源 DbException)
Class	取得從 .NET Framework Data Provider for SQL Server 傳回的錯誤之嚴重性層級。
ClientConnectionId	表示用戶端連接 ID。 如需詳細資訊，請參閱 ADO.NET 中的資料追蹤。
Data	取得鍵值組的集合，這些鍵值組會提供關於例外狀況的其他使用者定義資訊。 (繼承來源 Exception)
DbBatchCommand	在衍生類別中覆寫時，如果在執行 DbBatch時擲回，DbException則會參考觸發例外狀況的特定 DbBatchCommand 。 (繼承來源 DbException)
ErrorCode	取得錯誤的 HRESULT。 (繼承來源 ExternalException)
Errors	取得一個或多個 SqlError 物件的集合，這些物件可提供有關 .NET Framework Data Provider for SQL Server 產生的例外狀況之詳細資訊。
HelpLink	取得或設定與這個例外狀況相關聯的說明檔連結。 (繼承來源 Exception)
HResult	取得或設定 HRESULT，它是指派給特定例外狀況的編碼數值。 (繼承來源 Exception)
InnerException	取得造成目前例外狀況的 Exception 執行個體。 (繼承來源 Exception)
IsTransient	指出此 DbException 所代表的錯誤是否可能是暫時性錯誤，亦即，重試觸發作業是否可能會成功，而不需要任何其他變更。 (繼承來源 DbException)
LineNumber	取得 Transact-SQL 命令批次內的行號或產生錯誤的預存程序 (Stored Procedure)。
Message	取得描述目前例外狀況的訊息。 (繼承來源 Exception)
Number	取得識別錯誤類型的值。
Procedure	取得產生錯誤之預存程序或遠端程序呼叫 (RPC) 的名稱。
Server	取得執行 SQL Server 之執行個體 (會產生錯誤) 的電腦名稱。
Source	取得產生錯誤之提供者的名稱。
SqlState	針對支援的資料庫提供者，包含標準 SQL 5 字元傳回碼，指出資料庫作業成功或失敗。 前 2 個字元代表傳回碼的類別 (例如錯誤、成功)，而最後 3 個字元代表子類別，允許以資料庫可移植的方式偵測錯誤案例。 針對不支援的資料庫提供者，或不適用的錯誤案例，包含 null。 (繼承來源 DbException)
StackTrace	取得呼叫堆疊上即時運算框架的字串表示。 (繼承來源 Exception)
State	從 SQL Server 取得表示錯誤、警告或「找不到資料」訊息的數值錯誤碼。 如需有關如何將這些值解碼的詳細資訊，請參閱資料庫引擎事件與錯誤。
TargetSite	取得擲回目前例外狀況的方法。 (繼承來源 Exception)

方法

Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetBaseException()	在衍生類別中覆寫時，傳回一或多個後續的例外狀況的根本原因 Exception。 (繼承來源 Exception)
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetObjectData(SerializationInfo, StreamingContext)	使用例外狀況的相關資訊來設定 SerializationInfo。
GetType()	取得目前執行個體的執行階段類型。 (繼承來源 Exception)
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
ToString()	傳回字串，代表目前的SqlException物件，並包含用戶端連線識別碼 (如需詳細資訊，請參閱ClientConnectionId)。

事件

SerializeObjectState

當例外狀況序列化，以建立包含例外狀況相關序列化資料的例外狀況狀態物件時，就會發生此事件。 (繼承來源 Exception)

另請參閱

• SqlError
• SqlErrorCollection
• ADO.NET 概觀 \(部分機器翻譯\)