Erste Schritte bei der CLR-Integration

Artikel
07/12/2024

Gilt für: SQL Server

Dieser Artikel bietet einen Überblick über die Namespaces und Bibliotheken, die zum Kompilieren von Datenbankobjekten unter Verwendung der Microsoft SQL Server-Integration mit der .NET Framework Common Language Runtime (CLR) erforderlich sind. Der Artikel zeigt Ihnen auch, wie Sie eine kleine gespeicherte CLR-Prozedur schreiben, kompilieren und ausführen, die in Microsoft Visual C# und Visual Basic geschrieben wurde.

Erforderliche Namespaces

Die Komponenten, die zum Entwickeln grundlegender CLR-Datenbankobjekte erforderlich sind, werden mit SQL Server installiert. Die CLR-Integrationsfunktionalität ist in einer Assembly mit der Bezeichnung System.Data.dll enthalten, die Teil des .NET Framework ist. Diese Assembly befindet sich im globalen Assemblycache (GAC) sowie im .NET Framework-Verzeichnis. Ein Verweis auf diese Assembly wird in der Regel sowohl von Befehlszeilentools als auch von Microsoft Visual Studio automatisch hinzugefügt und muss daher nicht manuell hinzugefügt werden.

Die System.Data.dll-Assembly enthält die folgenden Namespaces, die zum Kompilieren von CLR-Datenbankobjekten erforderlich sind:

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

Tipp

Das Laden von CLR-Datenbankobjekten unter Linux wird unterstützt, muss jedoch mit .NET Framework erstellt werden (SQL Server CLR-Integration unterstützt .NET Core oder .NET 5 und höhere Versionen nicht). Außerdem werden CLR-Assemblys mit dem EXTERNAL_ACCESS oder UNSAFE Berechtigungssatz unter Linux nicht unterstützt.

Schreiben einer gespeicherten "Hallo Welt"-Prozedur

Kopieren Sie den folgenden Visual C# oder Visual Basic-Code, fügen Sie ihn in einen Texteditor ein, und speichern Sie ihn in einer Datei mit dem Namen helloworld.cs oder 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!";
    }
}

Imports System
Imports System.Data
Imports Microsoft.SqlServer.Server
Imports System.Data.SqlTypes
Imports System.Runtime.InteropServices
  
Public Class HelloWorldProc
    \<Microsoft.SqlServer.Server.SqlProcedure> _
    Public Shared  Sub HelloWorld(\<Out()> ByRef text as String)
        SqlContext.Pipe.Send("Hello world!" & Environment.NewLine)
        text = "Hello world!"
    End Sub
End Class

Dieses Programm enthält eine einzelne statische Methode in einer öffentlichen Klasse. Diese Methode enthält die beiden neuen Klassen SqlContext und SqlPipe zum Erstellen von verwalteten Datenbankobjekten für die Ausgabe einer kurzen Textnachricht. Die Methode weist auch die Zeichenfolge "Hallo Welt!" als Wert eines out Parameters zu. Diese Methode kann als gespeicherte Prozedur in SQL Server deklariert und anschließend auf dieselbe Weise wie eine gespeicherte Transact-SQL-Prozedur ausgeführt werden.

Kompilieren Sie dieses Programm als Bibliothek, laden Sie es in SQL Server und führen Sie es als gespeicherte Prozedur aus.

Kompilieren der gespeicherten Prozedur "Hallo Welt"

SQL Server installiert standardmäßig die .NET Framework-Redistributionsdateien. Zu diesen Dateien zählen die Dateien csc.exe und vbc.exe, die Befehlszeilen-Compiler für Visual C# sowie Visual Basic-Programme. Zum Kompilieren des Beispiels müssen Sie die Pfadvariable so ändern, dass sie auf das Verzeichnis mit der Datei csc.exe oder vbc.exe zeigt. Der Standardinstallationspfad von .NET Framework lautet wie folgt.

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

Diese Version enthält die Versionsnummer der installierten Redistributionsdatei von .NET Framework. Zum Beispiel:

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

Nach dem Hinzufügen des .NET Framework-Verzeichnises zum Pfad können Sie die gespeicherte Prozedur in diesem Beispiel mit dem folgenden Befehl in eine Assembly kompilieren. Mit der /target-Option können Sie sie in eine Assembly kompilieren.

Für Visual C#-Quelldateien gilt:

csc /target:library helloworld.cs

Für Visual Basic-Quelldateien gilt:

vbc /target:library helloworld.vb

Mit diesen Befehlen wird der Visual C# - bzw. Visual Basic-Compiler unter Angabe der /target-Option aufgerufen, die festlegt, dass eine Bibliotheks-DLL erstellt werden soll.

Laden und Ausführen der gespeicherten Prozedur "Hallo Welt" in SQL Server

Sobald die Beispielprozedur erfolgreich kompiliert wurde, können Sie sie in SQL Server testen. Öffnen Sie hierzu SQL Server Management Studio und erstellen Sie eine neue Abfrage zum Verbinden einer geeigneten Testdatenbank (z. B. der Beispieldatenbank AdventureWorks).

Die Funktion zum Ausführen von CLR-Code (Common Language Runtime) ist im SQL Server standardmäßig auf OFF gesetzt. Der CLR-Code kann mithilfe der sp_configure gespeicherten Systemprozedur aktiviert werden. Weitere Informationen finden Sie unter Enabling CLR Integration.

Sie müssen die Assembly erstellen, um auf die gespeicherte Prozedur zugreifen zu können. Für dieses Beispiel wird vorausgesetzt, dass Sie die helloworld.dll-Assembly im Verzeichnis C:\ erstellt haben. Fügen Sie die folgende Transact-SQL-Anweisung zur Abfrage hinzu.

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

Nach dem Erstellen der Assembly können Sie mithilfe der CREATE PROCEDURE-Anweisung auf die HelloWorld-Methode zugreifen. Die gespeicherte Prozedur wird hello genannt:

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

Nach dem Erstellen der Prozedur kann diese wie eine normale, in Transact-SQL geschriebene gespeicherte Prozedur ausgeführt werden. Führen Sie den folgenden Befehl aus:

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

Daraufhin sollte im Meldungsfenster von SQL Server Management Studio folgende Ausgabe angezeigt werden.

Hello world!
Hello world!

Entfernen des Beispiels der gespeicherten Prozedur "Hallo Welt"

Wenn Sie die gespeicherte Beispielprozedur ausgeführt haben, können Sie die Prozedur und die Assembly aus der Testdatenbank entfernen.

Entfernen Sie zuerst die Prozedur. Verwenden Sie hierzu den drop procedure-Befehl.

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

Nach dem Löschen der Prozedur können Sie die Assembly entfernen, die den Beispielcode enthält.

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

Nächste Schritte

Weitere Informationen zur CLR-Integration mit SQL Server finden Sie in den folgenden Artikeln:

Teilen über