IDbCommand.ExecuteScalar Método

Definição

Namespace:

System.Data

Assembly:

System.Data.Common.dll

Executa a consulta e retorna a primeira coluna da primeira linha no conjunto de resultados retornado pela consulta. Colunas ou linhas extra são ignoradas.

public:
 System::Object ^ ExecuteScalar();

public object? ExecuteScalar ();

abstract member ExecuteScalar : unit -> obj

Public Function ExecuteScalar () As Object

Retornos

Object

A primeira coluna da primeira linha no conjunto de resultados.

Exemplos

O exemplo a seguir cria uma instância da classe derivada, SqlCommande a executa usando ExecuteScalar. O exemplo é passado uma cadeia de caracteres que é uma instrução Transact-SQL que retorna um resultado agregado e uma cadeia de caracteres a ser usada para se conectar à fonte de dados.

public void CreateSqlCommand(
    string queryString, SqlConnection connection)
{
    SqlCommand command = new
        SqlCommand(queryString, connection);
    command.Connection.Open();
    command.ExecuteScalar();
    connection.Close();
}

Public Sub CreateSqlCommand( _
    queryString As String, connection As SqlConnection)

    Dim command As New SqlCommand(queryString, connection)
    command.Connection.Open()
    command.ExecuteScalar()
    connection.Close()
End Sub

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

Uma consulta típica ExecuteScalar pode ser formatada como no exemplo de C# a seguir:

CommandText = "select count(*) as NumberOfRegions from region";  
Int32 count = (int) ExecuteScalar();  

Se a primeira coluna da primeira linha no conjunto de resultados não for encontrada, uma referência nula (Nothing no Visual Basic) será retornada. Se o valor no banco de dados for null, a consulta retornará DBNull.Value.