THROW (Transact-SQL)

適用于:SQL Server (所有支援的版本) Azure SQL Database Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)

引發例外狀況,並將執行傳送至 TRY 的 CATCH 區塊...CATCH 建構。

主題連結圖示Transact-SQL 語法慣例

Syntax

THROW [ { error_number | @local_variable },  
        { message | @local_variable },  
        { state | @local_variable } ]   
[ ; ]  

注意

若要檢視 SQL Server 2014 與更早版本的 Transact-SQL 語法,請參閱舊版文件

引數

error_number
這是代表例外狀況的常數或變數。 error_numberint,必須大於或等於 50000,並小於或等於 2147483647。

message
即描述例外狀況的字串或變數。 messagenvarchar(2048)

state
這是介於 0 和 255 之間的常數或變數,表示要與訊息相關聯的狀態。 statetinyint

備註

THROW 陳述式之前的陳述式後面必須接著分號 (;) 陳述式結束字元。

如果沒有 TRY...CATCH 建構,就會終止陳述式批次。 系統會設定引發例外狀況的行號和程序。 嚴重性設為 16。

如果指定不含參數的 THROW 陳述式,它必須出現在 CATCH 區塊內。 這會導致引發攔截到的例外狀況。 THROW 陳述式中發生的任何錯誤都會導致陳述式批次終止。

% 是 THROW 陳述式訊息文字中的保留字元,而且必須逸出。 重複兩遍 % 字元使 % 返回為訊息文字的一部分,例如 ' 增加超過 15%%的原始值。 '

RAISERROR 和 THROW 之間的差異

下表列出 RAISERROR 和 THROW 語句之間的差異。

RAISERROR 陳述式 THROW 陳述式
如果將 msg_id 傳遞給 RAISERROR,則識別碼必須定義在 sys.messages 中。 error_number 參數不需要定義在 sys.messages 中。
msg_str 參數可以包含 printf 格式化樣式。 message 參數不接受 printf 樣式格式。
severity 參數指定例外狀況的嚴重性。 沒有任何 severity 參數。 當使用 THROW 起始例外狀況時,嚴重性一律設為 16。 不過,使用 THROW 重新擲回現有的例外狀況時,嚴重性會設定為該例外狀況的嚴重性層級。
不接受 SET XACT_ABORT 如果SET XACT_ABORT為 ON,則會回復交易。

範例

A. 使用 THROW 引發例外狀況

下列範例示範如何使用 THROW 陳述式引發例外狀況。

THROW 51000, 'The record does not exist.', 1;  

以下為結果集。

Msg 51000, Level 16, State 1, Line 1  
 
The record does not exist.

B. 使用 THROW 再次引發例外狀況

下列範例示範如何使用 THROW 語句再次引發最後擲回的例外狀況。

USE tempdb;  
GO  
CREATE TABLE dbo.TestRethrow  
(    ID INT PRIMARY KEY  
);  
BEGIN TRY  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
--  Force error 2627, Violation of PRIMARY KEY constraint to be raised.  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
END TRY  
BEGIN CATCH  
  
    PRINT 'In catch block.';  
    THROW;  
END CATCH;  
  

以下為結果集。

In catch block. 
Msg 2627, Level 14, State 1, Line 1  
Violation of PRIMARY KEY constraint 'PK__TestReth__3214EC272E3BD7D3'. Cannot insert duplicate key in object 'dbo.TestRethrow'.  
The statement has been terminated.

C. 搭配 THROW 使用 FORMATMESSAGE

下列範例示範如何使用 FORMATMESSAGE 函數搭配 THROW 來擲回自訂的錯誤訊息。 此範例會先使用 sp_addmessage 來建立使用者定義的錯誤訊息。 因為 THROW 陳述式不允許在 message 參數中使用替代參數 (而 RAISERROR 允許),所以 FORMATMESSAGE 函式會用來傳遞錯誤訊息 60000 所預期的三個參數值。

EXEC sys.sp_addmessage  
     @msgnum   = 60000  
    ,@severity = 16  
    ,@msgtext  = N'This is a test message with one numeric parameter (%d), one string parameter (%s), and another string parameter (%s).'  
    ,@lang = 'us_english';   
GO  
  
DECLARE @msg NVARCHAR(2048) = FORMATMESSAGE(60000, 500, N'First string', N'second string');   
  
THROW 60000, @msg, 1;  

以下為結果集。

Msg 60000, Level 16, State 1, Line 2  
This is a test message with one numeric parameter (500), one string parameter (First string), and another string parameter (second string).

後續步驟

在下列文章中深入了解相關概念: