Como depurar objetos de banco de dados CLR

Aplica-se a: SQL Server

O Microsoft SQL Server fornece suporte para depurar objetos Transact-SQL e CLR (Common Language Runtime) no banco de dados. Os principais aspectos da depuração no SQL Server são a facilidade de configuração e uso, e a integração do depurador do SQL Server com o depurador do Microsoft Visual Studio. Além disso, a depuração funciona entre idiomas. Os usuários podem entrar diretamente em objetos CLR do Transact-SQL e vice-versa. O depurador Transact-SQL no SQL Server Management Studio não pode ser usado para depurar objetos de banco de dados gerenciados, mas você pode depurar os objetos por meio dos depuradores do Visual Studio. A depuração de objetos de banco de dados gerenciados no Visual Studio oferece suporte a todos os recursos de depuração comuns, tais como as instruções de "depuração parcial" e "depuração completa" dentro de rotinas executadas no servidor. Os depuradores podem definir pontos de interrupção, inspecionar a pilha de chamadas, inspecionar variáveis e modificar valores de variáveis durante a depuração.

Permissões e restrições de depuração

A depuração é uma operação altamente privilegiada e, portanto, apenas os membros da função de servidor fixa sysadmin têm permissão para fazer isso no SQL Server.

As seguintes restrições se aplicam durante a depuração:

• A depuração de rotinas de CLR é restrita a uma instância de depurador de cada vez. Essa limitação se aplica pois a execução do código de CLR inteira fica congelada quando um ponto de interrupção é atingido; a execução só prossegue quando o depurador sai do ponto de interrupção. Porém, você pode continuar depurando o Transact-SQL em outras conexões. Embora a depuração do Transact-SQL não congele outras execuções no servidor, ela pode colocar outras conexões em espera quando mantém um bloqueio.

• Conexões existentes não podem ser depuradas, apenas as conexões novas, pois o SQL Server exige informações sobre o cliente e o ambiente do depurador para poder fazer a conexão.

Devido às restrições anteriores, recomendamos que o Transact-SQL e o código CLR sejam depurados em um servidor de teste, e não em um servidor de produção.

Visão geral

A depuração no SQL Server segue um modelo por conexão. Um depurador só pode detectar e depurar atividades para a conexão do cliente à qual ele está anexado. Como a funcionalidade do depurador não é limitada pelo tipo de conexão, pode-se depurar conexões do protocolo TDS e HTTP. Porém, o SQL Server não permite a depuração de conexões existentes. A depuração oferece suporte a todos os recursos de depuração comuns dentro de rotinas executadas no servidor. A interação entre um depurador e o SQL Server ocorre através do COM (Component Object Model) distribuído.

Para obter mais informações e cenários sobre depuração de procedimentos armazenados gerenciados, funções, gatilhos, tipos definidos pelo usuário e agregações, consulte Depuração de banco de dados com a integração do CLR no SQL Server na documentação do Visual Studio.

O protocolo de rede TCP/IP deve estar habilitado na instância do SQL Server para que o Visual Studio seja usado no desenvolvimento remoto, na depuração e no desenvolvimento. Para obter mais informações sobre como habilitar o protocolo TCP/IP no servidor, consulte Configurar protocolos de cliente.

Etapas de depuração

Use as etapas a seguir para depurar um objeto de banco de dados CLR no Microsoft Visual Studio:

1. Abra o Microsoft Visual Studio e crie um projeto do SQL Server. Você pode usar a instância SQL LocalDB que vem com o Visual Studio.

2. Crie um novo tipo de SQL CLR (C#):

   1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar, Novo Item....
   2. Na janela Adicionar Novo Item, selecione Procedimento Armazenado SQL CLR C#, Função Definida pelo Usuário SQL CLR C#, Tipo Definido pelo Usuário SQL CLR C#, Gatilho SQL CLR C#, Agregado SQL CLR C# ou Classe.
   3. Especifique um nome para o arquivo de origem do novo tipo e, em seguida, selecione Adicionar.

3. Adicione código para o tipo novo no editor de texto. Para ver o código de exemplo de um exemplo de procedimento armazenado, consulte a seção Exemplo a seguir neste artigo.

4. Adicione um script que testa o tipo:

   1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar, Script.....
   2. Na janela Adicionar Novo Item, selecione Script (Não em compilação) e especifique um nome, como Test.sql. Selecione o botão Adicionar.
   3. No Gerenciador de Soluções, clique duas vezes no nó Test.sql para abrir o arquivo de origem do script de teste padrão.
   4. Adicione o script de teste (que invoque o código a ser depurado) no editor de texto. Consulte o exemplo na próxima seção para ver um exemplo de script.

5. Coloque um ou mais pontos de interrupção no código fonte. Clique com o botão direito do mouse em uma linha de código no editor de texto na função ou rotina que você deseja depurar. Selecione Ponto de Interrupção, Inserir Ponto de Interrupção. O ponto de interrupção é adicionado, destacando a linha de código em vermelho.

6. No menu Depurar, selecione Iniciar Depuração para compilar, implantar e testar o projeto. O script de teste em Test.sql é executado, e o objeto de banco de dados gerenciado é chamado.

7. Quando a seta amarela (que indica o ponteiro de instruções) aparece no ponto de interrupção, a execução do código é interrompida. Em seguida, você pode depurar seu objeto de banco de dados gerenciado:

   1. Use Depuração Parcial no menu Depurar para avançar o ponteiro de instruções até a próxima linha de código.
   2. Use a janela Locais para observar o estado dos objetos atualmente destacados pelo ponteiro de instruções.
   3. Adicione variáveis à janela Inspeção. Você pode observar o estado das variáveis monitoradas durante toda a sessão de depuração, mesmo quando a variável não estiver na linha de código atualmente destacada pelo ponteiro de instruções.
   4. Selecione Continuar no menu Depurar para avançar o ponteiro de instruções até o próximo ponto de interrupção ou para concluir a execução da rotina se não houver mais pontos de interrupção.

Código de exemplo

O exemplo a seguir retorna a versão do SQL Server para o chamador.

using System.Data.SqlClient;
using Microsoft.SqlServer.Server;

public class StoredProcedures
{
    [Microsoft.SqlServer.Server.SqlProcedure]
    public static void GetVersion()
    {
        using (var connection = new SqlConnection("context connection=true"))
        {
            connection.Open();
            var command = new SqlCommand("select @@version", connection);
            SqlContext.Pipe.ExecuteAndSend(command);
        }
    }
}

Exemplo de script de teste

O script de teste a seguir mostra como invocar o procedimento armazenado GetVersion definido no exemplo anterior.

EXEC GetVersion  

Próximas etapas

Para obter mais informações sobre a depuração de código gerenciado usando o Visual Studio, consulte Depuração de código gerenciado na documentação do Visual Studio.

Para obter mais informações, consulte Conceitos de programação da integração do Common Language Runtime