ExecuteNonQuery

1. Descrição do método

SqlCommand.ExecuteNonQuery()

Cenários de uso: INSERT (inserir), UPDATE (atualizar), DELETE (excluir). Não use para consultas SELECT
Valor de retorno: tipo int, representa o número de linhas afetadas após a execução do SQL

Funcionamento: após executar instruções DML, o banco de dados retorna a quantidade de registros alterados. O programa usa esse número para verificar se a operação teve efeito.

Lógica de negócio baseada no valor retornado

1. INSERT: inserção bem‑sucedida → retorna 1; em caso de falha uma exceção é lançada;
2. UPDATE:

• Registros correspondentes encontrados e modificados → retorna ≥1
• Nenhum registro atende à condição WHERE → retorna 0 (a instrução roda sem erros, mas nenhuma linha é atualizada)

1. DELETE:

• Registros correspondentes excluídos → retorna ≥1
• Não há registros correspondentes → retorna 0

Distinção importante: retornar 0 não significa erro no programa. A sintaxe SQL executa normalmente, apenas não existem dados que atendam aos critérios para serem alterados.

Exemplo de inserção INSERT

private void button2_Click(object sender, EventArgs e)
{
    string connectionString = "Data Source=.;Initial Catalog=db;Integrated Security=True";
    using (SqlConnection conn = new SqlConnection(connectionString))
    {
        conn.Open();
        SqlCommand sqlCom = new SqlCommand();
        sqlCom.Connection = conn;
        // SQL parametrizado contra injeção de SQL
        sqlCom.CommandText = "INSERT INTO [dbo].[Article]([Title]) VALUES(@Title)";
        sqlCom.CommandTimeout = 60;

        SqlParameter param = new SqlParameter("@Title", SqlDbType.NVarChar, 250);
        param.Value = "Este é um novo título" + DateTime.Now;
        param.Direction = ParameterDirection.Input;
        sqlCom.Parameters.Add(param);

        int res = sqlCom.ExecuteNonQuery();
        MessageBox.Show(res.ToString()); 
        // Quando a inserção dá certo res=1
    }
}Code language: JavaScript (javascript)

Vantagem: consultas parametrizadas, evita vulnerabilidades de injeção de SQL causadas por concatenação de strings.

Exemplo de atualização UPDATE

conn.Open();
SqlCommand sqlCom = new SqlCommand();
sqlCom.Connection = conn;
sqlCom.CommandText = "UPDATE [dbo].[Article] SET [Title] = @Title WHERE id = @id";
sqlCom.CommandTimeout = 60;

SqlParameter param = new SqlParameter("@Title", SqlDbType.NVarChar, 250);
param.Value = "Este é um novo título"+DateTime.Now;
param.Direction = ParameterDirection.Input;
sqlCom.Parameters.Add(param);

// Duas formas equivalentes de adicionar parâmetros
//Modo 1: criar objeto e depois adicionar
SqlParameter param2 = new SqlParameter("@id", SqlDbType.Int);
param2.Value = 5;
sqlCom.Parameters.Add(param2);

//Modo 2: inicialização encadeada (forma comentada no código)
//sqlCom.Parameters.Add(new SqlParameter("@id", SqlDbType.Int){Value=5});

int res = sqlCom.ExecuteNonQuery();
MessageBox.Show(res.ToString());Code language: JavaScript (javascript)

• Existe registro com id=5 na tabela → res=1
• Não existe registro com id=5 → res=0
  Exemplo de validação na lógica de negócio:

if(res > 0)
{
    MessageBox.Show("Atualização concluída");
}
else
{
    MessageBox.Show("Registro‑alvo não encontrado, nenhuma atualização foi executada");
}Code language: JavaScript (javascript)

Observações

1. Não confirme sucesso apenas pela ausência de exceções
   O SQL não retornar erro não garante que os dados foram alterados. Por exemplo, quando nenhuma linha corresponde aos filtros de atualização o retorno é 0. Sempre avalie o resultado com a quantidade de linhas afetadas.
2. Não use ExecuteNonQuery para comandos SELECT
   Para SELECT ele retorna apenas -1 e não entrega os dados da consulta. Para ler dados utilize ExecuteReader() / ExecuteScalar().
3. Benefício da sintaxe using
   using(SqlConnection conn) libera automaticamente a conexão com o banco após o bloco finalizar, evitando vazamento de conexões.
4. Nomes dos parâmetros devem combinar exatamente
   No SQL, @Title e @id devem ser idênticos aos nomes usados no SqlParameter. Não diferencia maiúsculas de minúsculas, mas o nome não pode ser diferente.

Comparação dos três métodos SqlCommand

Método	Finalidade	Valor de retorno
ExecuteNonQuery	Inserir / Alterar / Excluir (INSERT/UPDATE/DELETE)	int Número de linhas afetadas
ExecuteScalar	Consulta de uma linha e uma coluna (ex: COUNT, pegar ID autoincremento)	object Valor da primeira linha e primeira coluna
ExecuteReader	Consultas SELECT com múltiplas linhas e colunas	SqlDataReader fluxo de dados

ExecuteNonQuery