SqlCommand.ExecuteNonQuery Método

Definição

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacote:

Microsoft.Data.SqlClient v5.2.0

Executa uma instrução Transact-SQL na conexão e retorna o número de linhas afetadas.

public:
 override int ExecuteNonQuery();

public override int ExecuteNonQuery ();

override this.ExecuteNonQuery : unit -> int

Public Overrides Function ExecuteNonQuery () As Integer

Retornos

Int32

O número de linhas afetadas.

Exceções

InvalidCastException

Um SqlDbType diferente de Binary ou VarBinary foi usado quando Value foi definido como Stream . Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

- ou -

Um SqlDbType diferente de Char, NChar, NVarChar, VarChar ou Xml foi usado quando Value foi definido como TextReader .

-ou-

Um SqlDbType diferente de Xml foi usado quando Value foi definido como XmlReader .

SqlException

Exceção ao executar o comando em uma linha bloqueada. Essa exceção não é gerada quando o Microsoft .NET Framework versão 1.0 é utilizado.

- ou -

Ocorreu um tempo limite durante uma operação de streaming. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

IOException

Ocorreu um erro em um Stream objeto ou TextReaderXmlReader durante uma operação de streaming. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

InvalidOperationException

O SqlConnection foi fechado ou removido durante uma operação de streaming. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

ObjectDisposedException

O Stream objeto ou TextReaderXmlReader foi fechado durante uma operação de streaming. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

Exemplos

O exemplo a seguir cria um SqlCommand e o executa usando ExecuteNonQuery. O exemplo é passado uma cadeia de caracteres que é uma instrução Transact-SQL (como UPDATE, INSERT ou DELETE) e uma cadeia de caracteres a ser usada para se conectar à fonte de dados.

// <Snippet1>
using System;
using System.Data;
using Microsoft.Data.SqlClient;

namespace SqlCommandCS
{
    class Program
    {
        static void Main()
        {
            string str = "Data Source=(local);Initial Catalog=Northwind;"
                + "Integrated Security=SSPI";
            string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
            CreateCommand(qs, str);
        }
        private static void CreateCommand(string queryString,
            string connectionString)
        {
            using (SqlConnection connection = new SqlConnection(
                       connectionString))
            {
                SqlCommand command = new SqlCommand(queryString, connection);
                command.Connection.Open();
                command.ExecuteNonQuery();
            }
        }
    }
}
// </Snippet1>

Comentários

Você pode usar o ExecuteNonQuery para executar operações de catálogo (por exemplo, consultando a estrutura de um banco de dados ou criando objetos de banco de dados, como tabelas), ou para alterar os dados em um banco de dados sem usar um DataSet executando instruções UPDATE, INSERT ou DELETE.

Embora o não retorne linhas, todos os ExecuteNonQuery parâmetros de saída ou valores retornados mapeados para parâmetros são preenchidos com dados.

Para instruções UPDATE, INSERT e DELETE, o valor retornado é o número de linhas afetadas pelo comando. Para todos os outros tipos de instruções, o valor retornado é -1. Quando um gatilho existe em uma tabela sendo inserida ou atualizada, o valor retornado inclui o número de linhas afetadas pela operação de inserção ou atualização e o número de linhas afetadas pelo gatilho ou gatilhos. Quando SET NOCOUNT ON é definido na conexão (antes ou como parte da execução do comando ou como parte de um gatilho iniciado pela execução do comando), as linhas afetadas por instruções individuais param de contribuir para a contagem de linhas afetadas retornadas por esse método. Se nenhuma instrução for detectada que contribua para a contagem, o valor retornado será -1. Se ocorrer uma reversão, o valor retornado também será -1.