SqlCommand.ExecuteScalar Método

Definição

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacote:

Microsoft.Data.SqlClient v5.2.0

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 -> obj

Public Overrides Function ExecuteScalar () As Object

Retornos

Object

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

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).

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).

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).

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 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();