SqlCommand.ExecuteScalar Método
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
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
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();