SqlCommand.ExecuteScalar Método

Definição

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:
 virtual System::Object ^ ExecuteScalar();
public override object ExecuteScalar ();
public object ExecuteScalar ();
override this.ExecuteScalar : unit -> obj
abstract member ExecuteScalar : unit -> obj
override this.ExecuteScalar : unit -> obj
Public Overrides Function ExecuteScalar () As Object
Public 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.

Implementações

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 objeto Stream, XmlReader ou TextReader durante uma operação de streaming. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).

O objeto Stream, XmlReader ou TextReader 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, em seguida, executa-o 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 retorna o novo valor da coluna Identidade se uma nova linha foi inserida, 0 em caso de falha.

static public int AddProductCategory(string newName, string connString)
{
    Int32 newProdID = 0;
    string sql =
        "INSERT INTO Production.ProductCategory (Name) VALUES (@Name); "
        + "SELECT CAST(scope_identity() AS int)";
    using (SqlConnection conn = new SqlConnection(connString))
    {
        SqlCommand cmd = new SqlCommand(sql, conn);
        cmd.Parameters.Add("@Name", SqlDbType.VarChar);
        cmd.Parameters["@name"].Value = newName;
        try
        {
            conn.Open();
            newProdID = (Int32)cmd.ExecuteScalar();
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }
    return (int)newProdID;
}
Public Function AddProductCategory( _
  ByVal newName As String, ByVal connString As String) As Integer
    Dim newProdID As Int32 = 0
    Dim sql As String = _
     "INSERT INTO Production.ProductCategory (Name) VALUES (@Name); " _
       & "SELECT CAST(scope_identity() AS int);"

    Using conn As New SqlConnection(connString)
        Dim cmd As New SqlCommand(sql, conn)
        cmd.Parameters.Add("@Name", SqlDbType.VarChar)
        cmd.Parameters("@Name").Value = newName
        Try
            conn.Open()
            newProdID = Convert.ToInt32(cmd.ExecuteScalar())
        Catch ex As Exception
            Console.WriteLine(ex.Message)
        End Try
    End Using

    Return newProdID
End Function

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

Aplica-se a

Confira também