THROW (Transact-SQL)

  • 發行項

適用於：Microsoft Fabric倉儲中的 SQL ServerAzure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse AnalyticsAnalytics Platform System （PDW）SQL 分析端點

引發例外狀況，並將執行轉移至 TRY...CATCH 建構的 CATCH 區塊。

Transact-SQL 語法慣例

Syntax

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

注意

若要檢視 SQL Server 2014 （12.x） 和舊版的 Transact-SQL 語法，請參閱 舊版檔。

引數

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

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

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

備註

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. 使用 FORMATMESSAGE 搭配 THROW

下列範例示範如何使用 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).

後續步驟

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