CLR 整合使用者入門

  • 發行項

適用於：SQL Server

本文章概要說明在使用與 .NET Framework Common Language Runtime (CLR) 整合的 Microsoft SQL Server 編譯資料庫物件時，所需的命名空間和程式庫。 此外，本文章還會為您示範如何撰寫、編譯及執行以 Microsoft Visual C# 與 Visual Basic 撰寫的小型 CLR 預存程序。

必要命名空間

開發基本 CLR 資料庫物件所需的元件會與 SQL Server 一起安裝。 CLR 整合功能會在稱為 System.Data.dll (.NET Framework 的一部分) 的組件中公開。 此組件可以在全域組件快取 (GAC) 及 .NET Framework 目錄中找到。 命令列工具及 Microsoft Visual Studio 通常會自動加入此組件的參考，因此不需要手動加入。

System.Data.dll 組件包含下列編譯 CLR 資料庫物件所需的命名空間：

  • System.Data
  • System.Data.Sql
  • Microsoft.SqlServer.Server
  • System.Data.SqlTypes

提示

支援在 Linux 上載入 CLR 資料庫物件，但這些物件必須用 .NET Framework 建置 (SQL Server CLR 整合不支援 .NET Core 或 .NET 5 和更新版本)。 此外，Linux 不支援具有 EXTERNAL_ACCESS 或 UNSAFE 權限集合的 CLR 組件。

撰寫 "Hello World" 預存程序

將下列 Visual C# 或 Visual Basic 程式碼複製並貼至文字編輯器中，然後將其儲存在名為 helloworld.cs 或 helloworld.vb 的檔案中。

using System;
using System.Data;
using Microsoft.SqlServer.Server;
using System.Data.SqlTypes;
  
public class HelloWorldProc
{
    [Microsoft.SqlServer.Server.SqlProcedure]
    public static void HelloWorld(out string text)
    {
        SqlContext.Pipe.Send("Hello world!" + Environment.NewLine);
        text = "Hello world!";
    }
}

此程式包含公用類別上的單一靜態方法。 此方法會使用 SqlContext 和 SqlPipe 這兩個新類別來建立受控資料庫物件以輸出簡短的文字訊息。 此方法也會將 "Hello world!" 字串指派為 out 參數的值。 此方法可以宣告為 SQL Server 中的預存程序，然後以與 Transact-SQL 預存程序相同的方法執行。

將此程式編譯為程式庫，並將其載入 SQL Server，然後做為預存程序來執行它。

編譯 "Hello World" 預存程序

依預設，SQL Server 會安裝 .NET Framework 轉散佈檔案。 這些檔案包括 csc.exe 和 vbc.exe，Visual C# 與 Visual Basic 程式的命令列編譯器。 若要編譯此範例，您必須修改路徑變數，使其指向包含 csc.exe 或 vbc.exe 的目錄。 以下路徑為 .NET Framework 的預設安裝路徑。

C:\Windows\Microsoft.NET\Framework\(version)

Version 包含已安裝之 .NET Framework 的版本號碼。 例如：

C:\Windows\Microsoft.NET\Framework\v4.8.0

將 .NET Framework 目錄加入路徑後，您就可以使用下列命令將預存程序範例編譯為組件。 /target 選項可讓您將其編譯為組件。

若為 Visual C# 來源檔案：

csc /target:library helloworld.cs

若為 Visual Basic 來源檔案：

vbc /target:library helloworld.vb

這些命令會啟動 Visual C# 或 Visual Basic 編譯器，並使用 /target 選項來指定要建立程式庫 DLL。

在 SQL Server 中載入並執行 "Hello World" 預存程序

成功編譯範例程序後，您就可以在 SQL Server 中對其進行測試。 若要執行此動作，請連接至適用的測試資料庫 (例如 AdventureWorks 範例資料庫)，然後開啟 SQL Server Management Studio 並建立新查詢。

在 SQL Server 中，執行 Common Language Runtime (CLR) 程式碼的功能預設為 OFF。 您可以使用 sp_configure 系統預存程序來啟用 CLR 程式碼。 如需詳細資訊，請參閱 Enabling CLR Integration。

我們必須先建立組件，才能存取預存程序。 在此範例中，我們假設您已在 C:\ 目錄中建立 helloworld.dll 組件。 將下列 Transact-SQL 陳述式加入至查詢。

CREATE ASSEMBLY helloworld from 'C:\helloworld.dll' WITH PERMISSION_SET = SAFE

組件建立完成後，您就可以使用 create procedure 陳述式存取 HelloWorld 方法。 我們將該預存程序稱為 hello：

CREATE PROCEDURE hello
@i nchar(25) OUTPUT
AS
EXTERNAL NAME helloworld.HelloWorldProc.HelloWorld;
-- if the HelloWorldProc class is inside a namespace (called MyNS),
-- the last line in the create procedure statement would be
-- EXTERNAL NAME helloworld.[MyNS.HelloWorldProc].HelloWorld

程序建立完成後，就可以使用與執行 Transact-SQL 中撰寫的一般預存程序一樣的方法來執行它。 執行下列命令：

DECLARE @J NCHAR(25);
EXEC hello @J out;
PRINT @J;

這將在 SQL Server Management Studio 訊息視窗中產生下列輸出。

Hello world!
Hello world!

移除 "Hello World" 預存程序範例

完成該範例預存程序的執行後，您就可以從測試資料庫中移除該程序及組件。

首先，使用 drop procedure 命令移除該程序。

IF EXISTS (SELECT name FROM sysobjects WHERE name = 'hello')
   DROP PROCEDURE hello;

程序一旦刪除後，您就可以移除包含範例程式碼的組件。

IF EXISTS (SELECT name FROM sys.assemblies WHERE name = 'helloworld')
   DROP ASSEMBLY helloworld;

下一步

如需有關 SQL Server 中 CLR 整合的詳細資訊，請查看下列文章：