SqlCommand.ExecuteScalar Método

Definição

Namespace:

System.Data.SqlClient

Assembly:

System.Data.SqlClient.dll

Pacote:

System.Data.SqlClient v4.8.6

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 Streamcomo . 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 foi definido TextReadercomo Value .

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

ObjectDisposedException

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

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 seguinte exemplo em C#:

cmd.CommandText = "SELECT COUNT(*) FROM dbo.region";
Int32 count = (Int32) cmd.ExecuteScalar();

Confira também

• Conectando e recuperando dados em ADO.NET
• Usando o provedor de dados .NET Framework para SQL Server
• Visão geral do ADO.NET