Compartilhar via

Introdução à integração do CLR

  • Artigo

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 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 CLR escrito em C# e visual Basic .NET.

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 encontrado no GAC (Cache de Assembly Global) e no diretório do .NET Framework. Normalmente, uma referência a esse assembly é adicionada automaticamente pelas ferramentas de linha de comando e pelo Visual Studio, portanto, não há necessidade de adicioná-lo 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 carregar objetos de banco de dados CLR no Linux, mas eles devem ser criados com o .NET Framework (a integração clr do SQL Server não dá suporte ao .NET Core ou ao .NET 5 e versões posteriores). Além disso, não há suporte para assemblies CLR com o conjunto de permissões EXTERNAL_ACCESS ou UNSAFE no Linux.

Escrever um procedimento armazenado "Hello World"

Copie e cole o seguinte código C# ou Visual Basic .NET 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!";
    }
}

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 C# e Visual Basic .NET. 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 comando a seguir. A opção /target permite compilá-lo em um assembly.

Para arquivos de origem em C#:

csc /target:library helloworld.cs

Para arquivos de origem do Visual Basic .NET:

vbc /target:library helloworld.vb

Esses comandos iniciam o compilador C# ou Visual Basic .NET usando a opção /target para especificar a criação de uma DLL de biblioteca.

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

Depois que o procedimento de exemplo for compilado com êxito, você poderá 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 AdventureWorks2022).

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, confira habilitar a integração de CLR.

Precisamos criar o assembly para acessar o procedimento armazenado. Para este exemplo, presumimos que você criou 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

Depois que o assembly for criado, agora podemos acessar nosso método HelloWorld usando a instrução CREATE PROCEDURE. Chamamos nosso procedimento armazenado de hello:

CREATE PROCEDURE hello
(@i NCHAR (25) OUTPUT)
AS EXTERNAL NAME helloworld.HelloWorldProc.HelloWorld;

Nota

No exemplo anterior, se a classe HelloWorldProc estiver dentro de um namespace (chamado MyNS), a última linha na instrução create procedure será EXTERNAL NAME helloworld.[MyNS.HelloWorldProc].HelloWorld;.

Depois que o procedimento é criado, ele pode ser executado como um procedimento armazenado normal escrito no Transact-SQL. Execute o comando a seguir:

DECLARE @J AS NCHAR (25);
EXECUTE hello @J OUTPUT;
PRINT @J;

Esta é a saída esperada.

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;

Depois que o procedimento for removido, você poderá remover o assembly que contém o código de exemplo.

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

Conteúdo relacionado