SqlCommand.ExecuteScalar Método

Definição

Executa a consulta e retorna a primeira coluna da primeira linha no conjunto de resultados retornado pela consulta.Executes the query, and returns the first column of the first row in the result set returned by the query. Colunas ou linhas adicionais são ignoradas.Additional columns or rows are ignored.

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.The first column of the first row in the result set, or a null reference (Nothing in Visual Basic) if the result set is empty. Retorna no máximo 2033 caracteres.Returns a maximum of 2033 characters.

Implementações

Exceções

Um SqlDbType diferente de Binary ou varbinary foi usado quando Value foi definido como Stream .A SqlDbType other than Binary or VarBinary was used when Value was set to Stream. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).For more information about streaming, see SqlClient Streaming Support.

- ou --or-

Um SqlDbType diferente de Char, nchar, nvarchar, varchar ou XML foi usado quando Value foi definido como TextReader .A SqlDbType other than Char, NChar, NVarChar, VarChar, or Xml was used when Value was set to TextReader.

- ou --or-

Um SqlDbType diferente de Xml foi usado quando Value foi definido como XmlReader.A SqlDbType other than Xml was used when Value was set to XmlReader.

Exceção ao executar o comando em uma linha bloqueada.An exception occurred while executing the command against a locked row. Essa exceção não é gerada quando o Microsoft .NET Framework versão 1.0 é utilizado.This exception is not generated when you are using Microsoft .NET Framework version 1.0.

- ou --or-

Ocorreu um tempo limite durante uma operação de streaming.A timeout occurred during a streaming operation. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).For more information about streaming, see SqlClient Streaming Support.

O SqlConnection foi fechado ou removido durante uma operação de streaming.The SqlConnection closed or dropped during a streaming operation. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).For more information about streaming, see SqlClient Streaming Support.

Ocorreu um erro em um objeto Stream, XmlReader ou TextReader durante uma operação de streaming.An error occurred in a Stream, XmlReader or TextReader object during a streaming operation. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).For more information about streaming, see SqlClient Streaming Support.

O objeto Stream, XmlReader ou TextReader foi fechado durante uma operação de streaming.The Stream, XmlReader or TextReader object was closed during a streaming operation. Para saber mais sobre o streaming, consulte SqlClient Streaming Support (Suporte de streaming do SqlClient).For more information about streaming, see SqlClient Streaming Support.

Exemplos

O exemplo a seguir cria um SqlCommand e, em seguida, executa-o usando ExecuteScalar .The following example creates a SqlCommand and then executes it using 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.The example is passed a string representing a new value to be inserted into a table, and a string to use to connect to the data source. A função retornará o novo valor da coluna de identidade se uma nova linha tiver sido inserida, 0 em caso de falha.The function returns the new Identity column value if a new row was inserted, 0 on failure.

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 de agregação) de um banco de dados.Use the ExecuteScalar method to retrieve a single value (for example, an aggregate value) from a database. 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 .This requires less code than using the ExecuteReader method, and then performing the operations that you need to generate the single value using the data returned by a SqlDataReader.

Uma ExecuteScalar consulta típica pode ser formatada como no exemplo de C# a seguir:A typical ExecuteScalar query can be formatted as in the following C# example:

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

Aplica-se a