Introdução à integração do CLR

Artigo
09/04/2023

Aplica-se a: SQL Server

Este artigo fornece uma visão geral dos namespaces e bibliotecas necessários para compilar objetos de banco de dados usando a integração do Microsoft SQL Server com o CLR (Common Language Runtime) do .NET Framework. O artigo também mostra como escrever, compilar e executar um pequeno procedimento armazenado no CLR escrito em Microsoft Visual C# e Visual Basic.

Namespaces obrigatórios

Os componentes necessários para desenvolver objetos de banco de dados CLR básicos são instalados com o SQL Server. A funcionalidade de integração do CLR é exposta em um assembly chamado System.Data.dll, que faz parte do .NET Framework. Esse assembly pode ser localizado no GAC (cache de assembly global), bem como no diretório do .NET Framework. Normalmente uma referência a esse assembly é adicionada automaticamente por ferramentas de linha de comando e pelo Microsoft Visual Studio, por isso não é necessário adicioná-la manualmente.

O assembly System.Data.dll contém os seguintes namespaces, que são necessários para compilar objetos de banco de dados CLR:

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

Dica

Há suporte para o carregamento de objetos de banco de dados CLR no Linux, mas eles devem ser criados com o .NET Framework (a integração do SQL Server CLR não oferece suporte ao .NET Core ou ao .NET 5 e versões posteriores). Além disso, assemblies de CLR com a permissão EXTERNAL_ACCESS ou UNSAFE definida não têm suporte no Linux.

Escrever um procedimento armazenado "Hello World"

Copie e cole o seguinte código Visual C# ou Visual Basic em um editor de texto e salve-o em um arquivo chamado helloworld.cs ou 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

Esse programa contém um único método estático em uma classe pública. Esse método usa duas novas classes, SqlContext e SqlPipe, para criar objetos de banco de dados gerenciados para emitir uma mensagem de texto curta. O método também atribui a string "Hello world!" como o valor de um parâmetro out. Esse método pode ser declarado como procedimento armazenado no SQL Server e executado de maneira igual a um procedimento armazenado Transact-SQL.

Compile esse programa como uma biblioteca, carregue-o no SQL Server e execute-o como um procedimento armazenado.

Compilar o procedimento armazenado "Hello World"

O SQL Server instala os arquivos de redistribuição do .NET Framework por padrão. Esses arquivos incluem csc.exe e vbc.exe, os compiladores de linha de comando para programas Visual C# e Visual Basic. Para compilar nossa amostra, você deve modificar sua variável de caminho de forma a apontar para o diretório que contém csc.exe ou vbc.exe. O caminho a seguir é o caminho de instalação padrão do .NET Framework.

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

Version contém o número da versão do .NET Framework instalado. Por exemplo:

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

Depois de adicionar o diretório do .NET Framework ao seu caminho, você poderá compilar o procedimento armazenado de exemplo em um assembly com o seguinte comando. A opção /target permite compilá-lo em um assembly.

Em arquivos de origem do Visual C#:

csc /target:library helloworld.cs

Em arquivos de origem do Visual Basic:

vbc /target:library helloworld.vb

Esses comandos iniciam o compilador do Visual C# ou do Visual Basic que usa a opção /target para especificar a compilação de uma DLL da biblioteca.

Carregar e executar o procedimento armazenado "Hello World" no SQL Server

Após o término da compilação do exemplo de procedimento, você pode testá-lo no SQL Server. Para fazer isso, abra o SQL Server Management Studio e crie uma consulta nova, conectando-se a um banco de dados de teste satisfatório (por exemplo, o banco de dados de exemplo AdventureWorks).

A capacidade de executar código CLR (Common Language Runtime) é definida por padrão como OFF no SQL Server. O código CLR pode ser habilitado usando o procedimento armazenado do sistema sp_configure. Para obter mais informações, consulte Enabling CLR Integration.

Precisaremos criar o assembly para podermos acessar o procedimento armazenado. Para este exemplo, vamos supor que você tenha criado o assembly helloworld.dll no diretório C:\. Adicione a seguinte instrução Transact-SQL à sua consulta.

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

Após a criação do assembly, poderemos acessar nosso método HelloWorld usando a instrução create procedure. Chamaremos nosso procedimento armazenado de 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

Após a criação do procedimento, ele poderá ser executado como um procedimento armazenado normal escrito em Transact-SQL. Execute o comando a seguir:

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

Isso deve resultar na seguinte saída na janela de mensagens do SQL Server Management Studio.

Hello world!
Hello world!

Remover o exemplo de procedimento armazenado "Hello World"

Quando terminar de executar o exemplo de procedimento armazenado, você poderá remover o procedimento e o assembly do seu banco de dados de teste.

Primeiro, remova o procedimento usando o comando drop procedure.

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

Após o descarte do procedimento, você poderá remover o assembly que contém seu código de exemplo.

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

Próximas etapas

Para obter mais informações sobre a integração do CLR no SQL Server, consulte os seguintes artigos:

Compartilhar via