Vincular dados a controles em soluções do Office

Você pode vincular controles do Windows Forms e controles de host em um documento do Microsoft Office Word ou planilha do Microsoft Office Excel a uma fonte de dados para que os controles exibam automaticamente os dados. Você pode vincular dados a controles em projetos de nível de aplicativo e de documento.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de suplemento VSTO. Consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Os controles de host estendem objetos que estão nos modelos de objeto do Word e do Excel, como controles de conteúdo no Word e intervalos nomeados no Excel. Para obter mais informações, consulte Visão geral sobre itens de host e controles de host.

Tanto o Windows Forms quanto os controles de host usam o modelo de vinculação de dados do Windows Forms, que oferece suporte à vinculação de dados simples e à vinculação de dados complexos a fontes de dados, como conjuntos de dados e tabelas de dados. Para obter informações completas sobre o modelo de vinculação de dados no Windows Forms, consulte Associação de dados e Windows Forms.

Vinculação de dados simples

A vinculação de dados simples existe quando uma propriedade de controle está vinculada a um único elemento de dados, como um valor em uma tabela de dados. Por exemplo, o NamedRange controle tem uma Value2 propriedade que pode ser vinculada a um campo em um conjunto de dados. Quando o campo no conjunto de dados é alterado, o valor no intervalo nomeado também é alterado. Todos os controles de host, exceto o controle, oferecem suporte à associação de XMLNodes dados simples. O XMLNodes controle é uma coleção e, portanto, não oferece suporte à vinculação de dados.

Para executar a vinculação de dados simples a um controle de host, adicione um Binding à DataBindings propriedade do controle. Um Binding objeto representa a associação simples entre um valor de propriedade do controle e o valor de um elemento de dados.

O exemplo a seguir demonstra como vincular a Value2 propriedade a um elemento de dados em um projeto de nível de documento.

C#

Binding binding1 = new Binding("Value2", ds, "Customers.Names", true);
namedRange1.DataBindings.Add(binding1);

VB

Dim binding1 As New Binding("Value2", ds, "Customers.Names", True)
namedRange1.DataBindings.Add(binding1)

Para obter instruções passo a passo que demonstram a associação de dados simples, consulte Demonstra Passo a passo: vinculação de dados simples em um projeto de nível de documento para um projeto de nível de documento e Passo a passo: vinculação de dados simples no projeto de suplemento VSTO para um projeto de suplemento VSTO.

Vinculação de dados complexos

A associação de dados complexa existe quando uma propriedade de controle está vinculada a mais de um elemento de dados, como várias colunas em uma tabela de dados. O ListObject controle para Excel é o único controle de host que oferece suporte à associação de dados complexos. Há também muitos controles do Windows Forms que oferecem suporte à associação de dados complexos, como o DataGridView controle.

Para executar a associação de dados complexa, defina a DataSource propriedade do controle como um objeto de fonte de dados que é suportado pela associação de dados complexa. Por exemplo, a DataSourceListObject propriedade do controle pode ser vinculada a várias colunas em uma tabela de dados. Todos os dados na tabela de dados aparecem no ListObject controle e, à medida que os dados na tabela de dados são alterados, os ListObject também são alterados. Para obter uma lista das fontes de dados que você pode usar para associação de dados complexos, consulte Fontes de dados com suporte no Windows Forms.

O exemplo de código a seguir cria um DataSet com dois DataTable objetos e preenche uma das tabelas com dados. Em seguida, o código vincula o ListObject à tabela que contém dados. Este exemplo é para um projeto de nível de documento do Excel.

C#

private void ListObject_DataSourceAndMember()
{
    // Create a DataSet and two DataTables.
    DataSet ordersDataSet = new DataSet("ordersDataSet");
    DataTable tableCustomers = new DataTable("Customers");
    DataTable tableProducts = new DataTable("Products");
    ordersDataSet.Tables.Add(tableCustomers);
    ordersDataSet.Tables.Add(tableProducts);

    // Add a data to the Customers DataTable.
    tableCustomers.Columns.Add(new DataColumn("LastName"));
    tableCustomers.Columns.Add(new DataColumn("FirstName"));
    DataRow dr = tableCustomers.NewRow();
    dr["LastName"] = "Chan";
    dr["FirstName"] = "Gareth";
    tableCustomers.Rows.Add(dr);

    // Create a list object.
    Microsoft.Office.Tools.Excel.ListObject list1 = 
        this.Controls.AddListObject(
        this.Range["A1"], "Customers");

    // Bind the list object to the Customers table.
    list1.AutoSetDataBoundColumnHeaders = true;
    list1.DataSource = ordersDataSet;
    list1.DataMember = "Customers";
}

VB

Private Sub ListObject_DataSourceAndMember()
    ' Create a DataSet and two DataTables.
    Dim ordersDataSet As New DataSet("ordersDataSet")
    Dim tableCustomers As New DataTable("Customers")
    Dim tableProducts As New DataTable("Products")
    ordersDataSet.Tables.Add(tableCustomers)
    ordersDataSet.Tables.Add(tableProducts)

    ' Add a data to the Customers DataTable.
    tableCustomers.Columns.Add(New DataColumn("LastName"))
    tableCustomers.Columns.Add(New DataColumn("FirstName"))
    Dim dr As DataRow = tableCustomers.NewRow()
    dr("LastName") = "Chan"
    dr("FirstName") = "Gareth"
    tableCustomers.Rows.Add(dr)

    ' Create a list object.
    Dim List1 As Microsoft.Office.Tools.Excel.ListObject = _
        Me.Controls.AddListObject(Me.Range( _
        "A1"), "Customers")

    ' Bind the list object to the Customers table.
    List1.AutoSetDataBoundColumnHeaders = True
    List1.DataSource = ordersDataSet
    List1.DataMember = "Customers"

End Sub

Para obter uma explicação passo a passo que demonstra a associação de dados complexa, consulte Demonstra Passo a passo: vinculação de dados complexos em um projeto de nível de documento para um projeto de nível de documento.

Exibir dados em documentos e pastas de trabalho

Em projetos de nível de documento, você pode usar a janela Fontes de Dados para adicionar controles vinculados a dados a seus documentos ou pastas de trabalho facilmente, da mesma forma que você a usa para o Windows Forms. Para obter mais informações sobre como usar a janela Fontes de Dados, consulte Vincular controles do Windows Forms a dados no Visual Studio e Adicionar novas fontes de dados.

Arraste controles da janela Fontes de Dados

Um controle é criado no documento quando você arrasta um objeto para ele a partir da janela Fontes de Dados . O tipo de controle criado depende se você está vinculando uma única coluna de dados ou várias colunas de dados.

Para o Excel, um controle é criado na planilha para cada campo individual e um NamedRangeListObject controle é criado para cada intervalo de dados que inclui várias linhas e colunas. Você pode alterar esse padrão selecionando a tabela ou campo na janela Fontes de Dados e escolhendo um controle diferente na lista suspensa.

Um ContentControl controle é adicionado aos documentos. O tipo de controle de conteúdo depende do tipo de dados do campo selecionado.

Vincular dados em projetos de nível de documento em tempo de design

Os tópicos a seguir mostram exemplos de vinculação de dados em tempo de design:

• Como: preencher planilhas com dados de um banco de dados

• Como preencher documentos com dados de um banco de dados

• Como: preencher documentos com dados de objetos

• Como: preencher documentos com dados de serviços

• Como: percorrer registros de banco de dados em uma planilha

Vincular dados em projetos de suplemento VSTO

Em projetos de suplemento VSTO, você pode adicionar controles somente em tempo de execução. Os tópicos a seguir mostram exemplos de vinculação de dados em tempo de execução:

• Demonstra Passo a passo: Vinculação de dados simples no projeto de suplemento VSTO

Atualizar dados vinculados a controles de host

A vinculação de dados entre uma fonte de dados e um controle de host envolve uma atualização de dados bidirecional. Na associação de dados simples, as alterações na fonte de dados são refletidas automaticamente no controle de host, mas as alterações no controle de host exigem uma chamada explícita para atualizar a fonte de dados. O motivo é que, em alguns casos, as alterações em um campo vinculado a dados não são aceitas, a menos que sejam acompanhadas por alterações em outro campo vinculado a dados. Por exemplo, você pode ter dois campos, um para idade e outro para anos de experiência. A experiência não pode exceder a idade. Um usuário não pode atualizar a idade de 50 para 25 e, em seguida, a experiência de 30 para 10, a menos que ele ou ela faça as alterações ao mesmo tempo. Para resolver esse problema, os campos com vinculação de dados simples não são atualizados até que as atualizações sejam enviadas explicitamente pelo código.

Para atualizar uma fonte de dados a partir de controles de host que permitem a associação de dados simples, você deve enviar atualizações para a fonte de dados na memória (como a DataSet ou DataTable) e para o banco de dados back-end, se sua solução usar uma.

Você não precisa atualizar explicitamente a fonte de dados na memória ao executar a vinculação de dados complexos usando o ListObject controle. Nesse caso, as alterações são enviadas automaticamente para a fonte de dados na memória sem código adicional.

Para obter mais informações, consulte Como: atualizar uma fonte de dados com dados de um controle de host.

Conteúdo relacionado

• Vinculação de dados e Windows Forms
• Como: Criar um controle de associação simples em um Windows Form
• Associar controles do Windows Forms a dados no Visual Studio
• Salvar dados novamente no banco de dados
• Atualizar dados usando um TableAdapter
• Dados de cache
• Dados em soluções do Office