Como criar e executar uma instrução SQL que retorna um único valorHow to: Create and Execute an SQL Statement that Returns a Single Value

Note

Este artigo se aplica ao Visual Studio 2015.This article applies to Visual Studio 2015. Se você estiver procurando a documentação do Visual Studio 2017, use o seletor de versão na parte superior esquerda.If you're looking for Visual Studio 2017 documentation, use the version selector at the top left. É recomendável atualizar para o Visual Studio 2017.We recommend upgrading to Visual Studio 2017. Baixe-o aqui.Download it here.

Para executar uma instrução SQL que retorna um único valor, você pode executar uma consulta TableAdapter que está configurada para executar uma instrução SQL (por exemplo, CustomersTableAdapter.CustomerCount()).To execute an SQL statement that returns a single value, you can run a TableAdapter query that is configured to run an SQL statement (for example, CustomersTableAdapter.CustomerCount()).

Se seu aplicativo não usar TableAdapters, chame o ExecuteScalar método em um objeto de comando, definindo seu CommandType propriedade CommandType.If your application does not use TableAdapters, call the ExecuteScalar method on a command object, setting its CommandType property to CommandType. ("Objeto de comando" refere-se ao comando específico para o .NET Framework Data Provider seu aplicativo está usando.("Command object" refers to the specific command for the .NET Framework Data Provider your application is using. Por exemplo, se seu aplicativo estiver usando o .NET Framework Data Provider para SQL Server, o objeto de comando seria SqlCommand.)For example, if your application is using the .NET Framework Data Provider for SQL Server, the command object would be SqlCommand.)

Os exemplos a seguir mostram como executar instruções SQL que retornam valores únicos de um banco de dados usando o TableAdapters ou objetos de comando.The following examples show how to execute SQL statements that return single values from a database using either TableAdapters or command objects. Para obter mais informações sobre como consultar com TableAdapters e comandos, consulte preencher conjuntos de dados usando TableAdapters.For more information on querying with TableAdapters and commands, see Fill datasets by using TableAdapters.

> [!NOTE] > Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obter mais informações, confira Personalizando o IDE.For more information, see Personalizing the IDE.

Executar instruções SQL que retornam valores únicos usando um TableAdapterExecuting SQL Statements that Return Single Values Using a TableAdapter

Este exemplo mostra como criar uma consulta TableAdapter usando o editando TableAdapters, e, em seguida, ele fornece informações sobre como declarar uma instância do TableAdapter e executar a consulta.This example shows how to create a TableAdapter query using the Editing TableAdapters, and then it provides information on how to declare an instance of the TableAdapter and execute the query.

Para criar uma instrução SQL que retornam um único valor usando um TableAdapterTo create an SQL statement returning a single value using a TableAdapter

  1. Abrir em um conjunto de dados do Dataset Designer.Open a dataset in the Dataset Designer. Para obter mais informações, consulte como: abrir um conjunto de dados no Designer de conjunto de dados.For more information, see How to: Open a Dataset in the Dataset Designer.

  2. Se você não tiver uma, crie um TableAdapter.If you do not already have one, create a TableAdapter. Para obter mais informações sobre como criar TableAdapters, consulte criar e configurar TableAdapters.For more information on creating TableAdapters, see Create and configure TableAdapters.

  3. Se você já tiver uma consulta no seu TableAdapter que usa uma instrução SQL para retornar um único valor, em seguida, vá para o próximo procedimento, "para"declarar uma instância do TableAdapter e executar a consulta.If you already have a query on your TableAdapter that uses an SQL statement to return a single value, then skip to the next procedure, "To declare an instance of the TableAdapter and execute the query." Caso contrário, continue com a etapa 4 para criar uma nova consulta que retorna um valor único.Otherwise, continue with step 4 to create a new query that returns a single value.

  4. Clique com botão direito do TableAdapter que você deseja e use o menu de atalho para adicionar uma consulta.Right-click the TableAdapter that you want, and use the shortcut menu to add a query.

    O Assistente de configuração de consulta do TableAdapter é aberta.The TableAdapter Query Configuration Wizard opens.

  5. Deixe o valor padrão de usar instruções SQLe, em seguida, clique em próxima.Leave the default value of Use SQL statements, and then click Next.

  6. Escolha o SELECT que retorna um único valor opção e, em seguida, clique em próxima.Choose the SELECT which returns a single value option, and then click Next.

  7. Digite a instrução SQL ou use o construtor de consultas para auxiliar na criação de uma e, em seguida, clique em próxima.Type your SQL statement, or use the Query Builder to assist with creating one, and then click Next.

  8. Forneça um nome para a consulta.Provide a name for the query.

  9. Conclua o Assistente; a consulta é adicionada ao TableAdapter.Complete the wizard; the query is added to the TableAdapter.

  10. Criar o projeto.Build your project.

Para declarar uma instância do TableAdapter e executar a consultaTo declare an instance of the TableAdapter and execute the query

  1. Declare uma instância do TableAdapter que contém a consulta que você deseja executar.Declare an instance of the TableAdapter that contains the query you want to execute.

    • Para criar uma instância usando as ferramentas de tempo de design, arraste o TableAdapter que você deseja do caixa de ferramentas.To create an instance using design-time tools, drag the TableAdapter that you want from the Toolbox. (Os componentes no seu projeto agora aparecem na caixa de ferramentas sob um título que corresponda ao nome do projeto.) Se o TableAdapter não aparecer na caixa de ferramentas, talvez seja necessário compilar seu projeto.(Components in your project now appear in the Toolbox under a heading that matches your project name.) If the TableAdapter does not appear in the Toolbox, then you may need to build your project.

      -ou--or-

    • Para criar uma instância no código, substitua o código a seguir com os nomes dos seus DataSet e TableAdapter.To create an instance in code, replace the following code with the names of your DataSet and TableAdapter.

      Dim tableAdapter As New DataSetTableAdapters.TableAdapter

      Note

      TableAdapters não são realmente estão localizadas dentro de suas classes de conjunto de dados associado.TableAdapters are not actually located inside their associated dataset classes. Cada conjunto de dados tem uma coleção correspondente de TableAdapters em seu próprio namespace.Each dataset has a corresponding collection of TableAdapters in its own namespace. Por exemplo, se você tiver um conjunto de dados denominado SalesDataSet, em seguida, haveria um SalesDataSetTableAdapters namespace que contém seus TableAdapters.For example, if you have a dataset named SalesDataSet, then there would be a SalesDataSetTableAdapters namespace that contains its TableAdapters.

  2. Chame sua consulta, como você poderia chamar qualquer outro método no código.Call your query as you would call any other method in code. Sua consulta é um método no TableAdapter.Your query is a method on the TableAdapter. Substitua o código a seguir com os nomes de seu TableAdapter e a consulta.Replace the following code with the names of your TableAdapter and query. Você também precisará passar os parâmetros necessários para sua consulta e fazer algo com o valor de retorno (por exemplo, atribuí-lo a uma variável).You also need to pass in any parameters required by your query and do something with the return value (for example, assign it to a variable). Se você não tiver certeza se sua consulta exigir parâmetros, ou que parâmetros requer, em seguida, verifique o IntelliSense para a assinatura necessária da consulta.If you are not sure if your query requires parameters, or what parameters it requires, then check IntelliSense for the required signature of the query. Dependendo se sua consulta usa parâmetros ou não, o código seria semelhante a um dos exemplos a seguir:Depending on whether your query takes parameters or not, the code would look similar to one of the following examples:

    TableAdapter.Query()

    TableAdapter.Query(Parameters)

  3. Provavelmente, você precisará atribuir o valor retornado pela consulta para uma variável.You will likely need to assign the value returned by the query to a variable. Consultas TableAdapter que retornam um único valor retornam um tipo de dados com base na consulta (em oposição ao ExecuteScalar método, que retorna um objeto).TableAdapter queries that return a single value return a data type based on the query (as opposed to the ExecuteScalar method, which returns an object). Por exemplo, se sua consulta do TableAdapter seleciona uma única coluna cujo tipo de dados é um inteiro, o valor retornado da consulta é um inteiro.For example, if your TableAdapter query selects a single column whose data type is an integer, then the return value of the query is an integer. Se a coluna permitir valores nulos, o valor de retorno é um dos tipos anuláveis (por exemplo, Nullable(Of Integer)).If the column allows null values, the return value is one of the nullable types (for example, Nullable(Of Integer)). Para obter mais informações sobre tipos anuláveis, consulte Nullable.For more information on nullable types, see Nullable. O código completo para declarar uma instância de um TableAdapter e executar uma consulta deve ser semelhante ao seguinte (Este exemplo pressupõe que o retorno de valor é um inteiro; ajuste seu código de acordo com o tipo de dados retornado pela consulta):The complete code to declare an instance of a TableAdapter and execute a query should look similar to the following (this example assumes the return value is an integer; adjust your code according to the data type returned by your query):

    NorthwindDataSetTableAdapters.CustomersTableAdapter tableAdapter = 
        new NorthwindDataSetTableAdapters.CustomersTableAdapter();
    
    int returnValue = (int)tableAdapter.GetCustomerCount();
    
    Dim tableAdapter As New NorthwindDataSetTableAdapters.CustomersTableAdapter()
    
    Dim returnValue As Integer
    returnValue = CType(tableAdapter.GetCustomerCount(), Integer)
    

Executar instruções SQL que retornam valores únicos usando um objeto de comandoExecuting SQL Statements that Return Single Values Using a Command Object

O exemplo a seguir mostra como criar um comando e executar uma instrução SQL que retorna um único valor.The following example shows how to create a command and execute an SQL statement that returns a single value. Para obter informações sobre como definir e obter valores de parâmetro para um comando, consulte como: definir e obter parâmetros para objetos de comando.For information on setting and getting parameter values for a command, see How to: Set and Get Parameters for Command Objects.

Este exemplo usa o SqlCommand do objeto e requer:This example uses the SqlCommand object and requires:

  • Referências para o System, System.Data, e System.Xml namespaces.References to the System, System.Data, and System.Xml namespaces.

  • Uma conexão de dados denominado SqlConnection1.A data connection named SqlConnection1.

  • Uma tabela denominada Customers na fonte de dados que SqlConnection1 se conecta ao.A table named Customers in the data source that SqlConnection1 connects to. (Caso contrário, você precisa de uma instrução SQL válida para sua fonte de dados).(Otherwise, you need a valid SQL statement for your data source).

Para executar uma instrução SQL que retornam um único valor usando um DataCommandTo execute an SQL statement returning a single value using a DataCommand

  • Adicione o seguinte código para um método que você deseja executar o código.Add the following code to a method that you want to execute the code from. Retorna um único valor chamando o ExecuteScalar método de um comando (por exemplo, ExecuteScalar).You return a single value by calling the ExecuteScalar method of a command (for example, ExecuteScalar). Os dados são retornados em um Object.The data is returned in an Object.

    SqlConnection sqlConnection1 = new SqlConnection("Your Connection String");
    SqlCommand cmd = new SqlCommand();
    Object returnValue;
    
    cmd.CommandText = "SELECT COUNT(*) FROM Customers";
    cmd.CommandType = CommandType.Text;
    cmd.Connection = sqlConnection1;
    
    sqlConnection1.Open();
    
    returnValue = cmd.ExecuteScalar();
    
    sqlConnection1.Close();
    
    Dim sqlConnection1 As New SqlConnection("Your Connection String")
    Dim cmd As New SqlCommand
    Dim returnValue As Object
    
    cmd.CommandText = "SELECT COUNT(*) FROM Customers"
    cmd.CommandType = CommandType.Text
    cmd.Connection = sqlConnection1
    
    sqlConnection1.Open()
    
    returnValue = cmd.ExecuteScalar()
    
    sqlConnection1.Close()
    

Segurança do .NET Framework.NET Framework Security

O aplicativo requer permissão para acessar o banco de dados e executar a instrução SQL.The application requires permission to access the database and execute the SQL statement.

Consulte tambémSee Also

System.Data.SqlClient.SqlCommand.ExecuteScalar
System.Data.OleDb.OleDbCommand.ExecuteScalar
System.Data.Odbc.OdbcCommand.ExecuteScalar
System.Data.OracleClient.OracleCommand.ExecuteScalar
Como: criar consultas TableAdapter How to: Create TableAdapter Queries
Como: editar consultas TableAdapter How to: Edit TableAdapter Queries
Como: preencher um conjunto de dados com dados How to: Fill a dataset with data
Preencher conjuntos de dados usando TableAdapters Fill datasets by using TableAdapters
Como: definir e obter parâmetros para objetos de comandoHow to: Set and Get Parameters for Command Objects