SqlCommand.ExecuteScalar Método
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Executa a consulta e retorna a primeira coluna da primeira linha no conjunto de resultados retornado pela consulta. Colunas ou linhas adicionais são ignoradas.
public:
override System::Object ^ ExecuteScalar();public override object ExecuteScalar ();override this.ExecuteScalar : unit -> objPublic Overrides Function ExecuteScalar () As ObjectRetornos
A primeira coluna da primeira linha no conjunto de resultados ou uma referência nula ( Nothing no Visual Basic) se o conjunto de resultados estiver vazio. Retorna no máximo 2033 caracteres.
Exceções
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 .
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).
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).
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).
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 ExecuteScalar. O exemplo é passado uma cadeia de caracteres que representa um novo valor a ser inserido em uma tabela e uma cadeia de caracteres a ser usada para se conectar à fonte de dados. A função retornará o novo valor da coluna Identidade se uma nova linha tiver sido inserida, 0 em caso de falha.
using System;
using System.Data;
using Microsoft.Data.SqlClient;
public class Sample
{
public void CreateSqlCommand(
string queryString, SqlConnection connection)
{
SqlCommand command = new
SqlCommand(queryString, connection);
command.Connection.Open();
command.ExecuteScalar();
connection.Close();
}
Comentários
Use o ExecuteScalar método para recuperar um único valor (por exemplo, um valor agregado) de um banco de dados. Isso requer menos código do que usar o ExecuteReader método e, em seguida, executar as operações necessárias para gerar o valor único usando os dados retornados por um SqlDataReader.
Uma consulta típica ExecuteScalar pode ser formatada como no exemplo de C# a seguir:
cmd.CommandText = "SELECT COUNT(*) FROM dbo.region";
Int32 count = (Int32) cmd.ExecuteScalar();