Introdução

Entre as classes mais utilizadas do .NET Framework encontra-se a SqlCommand, presente no namespace System.Data.SqlClient. Esta classe é responsável por executar instruções SQL em bancos de dados SQL Server, podendo ser usada tanto para consultas como para instruções “não query”, como updates, inserts e execução de procedures.

Nesse artigo iremos conhecer um pouco mais essa classe, principais métodos e propriedades, juntamente com alguns exemplos práticos de uso.

Principais propriedades

CommandText: essa propriedade do tipo string representa a instrução SQL a ser executada, como um SELECT, UPDATE, INSERT ou o nome de um stored procedure existente.

CommandTimeout: trata-se de um valor inteiro que representa o tempo máximo, em segundos, que o SqlCommand deve levar para executar uma instrução. Caso nenhum valor seja definido, o padrão assumido é de 30 segundos.

CommandType: a propriedade CommandType define o tipo de instrução a ser executada pelo SqlCommand. Os valores possíveis para essa propriedade vêm de uma enumeração chamada CommandType que possui os seguintes valores.

  • Text: para instruções DML comuns como selects e inserts. Este é o valor padrão assumido.
  • TableDirect: caso seja usada, a propriedade CommandText deve contar apenas o nome de uma tabela. Quando o comando é executado, todas as linhas e colunas dessa tabela são retornadas.
  • StoredProcedure: usado para executar stored procedures. Nesse caso o CommandText deve apenas ser o nome do procedimento.

Connection: um objeto do tipo SqlConnection (classe contida no mesmo namespace), que representa e possui os dados da conexão atual com o banco de dados.

Parameters: esta é uma coleção de objetos do tipo SqlParameter e, assim como a maioria das coleções, possui métodos como Add, Remove, etc. Os parâmetros dessa lista devem corresponder àqueles definidos no CommandText (identificados por @ antes do nome). Mais adiante teremos exemplos de uso dessa propriedade.

Principais métodos

BeginExecuteNonQuery: inicia a execução assíncrona de uma instrução SQL que não seja uma consulta.

BeginExecuteReader: inicia a execução assíncrona de uma consulta ao banco de dados.

BeginExecuteXmlReader: inicia a execução assíncrona da instrução SQL, retornando um objeto do tipo XmlReader na função de callback.

Cancel: tenta cancelar a execução do comando.

EndExecuteNonQuery: finaliza a execução assíncrona da instrução SQL “não consulta”.

EndExecuteReader: finaliza a execução assíncrona da instrução de consulta ao banco.

EndExecuteXmlReader: finaliza a execução assíncrona da instrução cujo retorno será um XmlReader.

ExecuteNonQuery: executa uma instrução SQL que não seja uma consulta.

ExecuteNonQueryAsync: versão assíncrona do método ExecuteNonQuery, que faz uso do recurso awaitable, inserido no .NET 4.5.

ExecuteReader: efetua uma consulta ao banco de dados, retornando um objeto do tipo SqlDataReader com os registros resutlantes.

ExecuteReaderAsync: versão assíncrona do método ExecuteReader.

ExecuteScalar: executa a instrução SQL e retorna o valor da primeira coluna do primeiro registro resultante. Também possui a versão assíncrona (ExecuteScalarAsyc).

ExecuteXmlReader: executa a instrução SQL, retornando um XmlReader com os resultados. Sua versão assíncrona é a ExecuteXmlReaderAsync.

ResetCommandTimeOut: “reseta” a propriedade CommandTimeout para seu valor padrão de 30 segundos.

Exemplos práticos

A seguir temos alguns exemplos práticos de uso da classe SqlCommand, aplicando algumas das propriedades e métodos previamente apresentados nesse artigo. Como os exemplos não requerem nenhum recurso visual avançado, serão desenvolvidos em uma aplicação console.

Listagem 1: Executando uma instrução SQL definida pelo usuário

static void Main(string[] args)
{
    SqlConnection conexao = new SqlConnection("Data Source=SERVIDOR; Initial Catalog=BANCO; User Id=USUARIO; Password=SENHA;");
    SqlCommand cmd = new SqlCommand();
    cmd.Connection = conexao;
    Console.WriteLine("Informe a instrução SQL a ser executada:");
    string SQL = Console.ReadLine();
    try
    {
        cmd.CommandText = SQL;
        conexao.Open();
        cmd.ExecuteNonQuery();
        Console.WriteLine("Comando executado com sucesso.");
    }
    catch
    {
        Console.WriteLine("Erro ao executar SQL.");
    }
    Console.ReadLine();
}

O resultado desse código é mostrado na figura a seguir.

Resultado da Listagem 1

Figura 1: Resultado da Listagem 1

O próximo exemplo mostra uma consulta, onde o usuário informa o código de um serviço (tabela de teste chamada TbTABELA_SERVICOS) e, caso ele seja localizado no banco, sua descrição é exibida na tela.

Listagem 2: Exemplo de consulta ao banco de dados

static void Main(string[] args)
{
    SqlConnection conexao = new SqlConnection("Data Source=SERVIDOR; Initial Catalog=BANCO; User Id=USUARIO; Password=SENHA;");
    SqlCommand cmd = new SqlCommand();
    cmd.Connection = conexao;
    Console.WriteLine("Informe o código do serviço a ser localizado:");
    try
    {
        cmd.CommandText = "SELECT TabDESCRICAO FROM TbTABELA_SERVICOS WHERE TabCODIGO = @codigo";
        string codigo = Console.ReadLine();
        cmd.Parameters.AddWithValue("codigo", codigo);
        conexao.Open();
        SqlDataReader result = cmd.ExecuteReader();
        if (result.Read())
        {            
            Console.WriteLine("Descrição do serviço: " + result.GetString(0));
        }
        else
        {
            Console.WriteLine("O serviço não foi localizado.");
        }
    }
    catch(Exception ex)
    {
        Console.WriteLine("Erro ao executar SQL."+ex.Message);
    }
    Console.ReadLine();
}
Resultado da Listagem 1

Figura 2: Resultado da Listagem 2

Nesse segundo exemplo, recebemos do usuário o valor do código do serviço que ele deseja localizar e passamos para a instrução SQL através do parâmetro @codigo. Em seguida, adicionamos um SqlParameter ao SQlCommand através do método AddWithValue da propriedade Parameteres. Esse método recebe o nome do parâmetro (sem o arroba @) e seu valor, que no caso foi lido do console.

Conclusão

São várias as possibilidades e formas de se trabalhar com a classe SqlCommand, peça fundamental do ADO.NET. Com ele podemos efetuar uma série de manipulações dos dados de um banco SQL Server, obtendo vários tipos de resultados.

Finalizamos então este breve artigo. Caso surjam dúvidas, críticas ou sugestões, a seção de comentários está aberta logo abaixo.

Até a próxima oportunidade.