Partilhar via

Introdução à integração 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 necessá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 CLR é exposta em um assembly chamado System.Data.dll, que faz parte do .NET Framework. Esse assembly pode ser encontrado no GAC (Global Assembly Cache) e no diretório .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á-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

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

Escreva 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!";
    }
}

Este 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 gerar uma mensagem de texto curta. O método também atribui a cadeia de caracteres "Hello world!" como o valor de um parâmetro out. Esse método pode ser declarado como um procedimento armazenado no SQL Server e, em seguida, executado da mesma maneira que um procedimento armazenado Transact-SQL.

Compile este 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 nosso exemplo, você deve modificar sua variável de caminho para 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)

Versão 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 .NET Framework ao seu caminho, você pode compilar o procedimento armazenado de exemplo em um assembly com o seguinte comando. A opção /target permite compilá-lo em um assembly.

Para arquivos de origem 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 biblioteca DLL.

Carregue e execute 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 nova consulta, conectando-se a um banco de dados de teste adequado (por exemplo, o banco de dados de exemplo AdventureWorks2022).

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

Precisamos criar o assembly para que possamos acessar o procedimento armazenado. Para este exemplo, assumimos 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 é criado, agora podemos acessar nosso método HelloWorld usando a instrução CREATE PROCEDURE. Chamamos nosso procedimento armazenado hello:

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

Observação

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 em Transact-SQL. Execute o seguinte comando:

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

Aqui está a saída esperada.

Hello world!
Hello world!

Remova o exemplo de procedimento armazenado "Hello World"

Quando terminares de executar o procedimento armazenado de exemplo, poderás remover o procedimento e o assembly da tua base 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 descartado, 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