Walkthrough: Simple Data Binding in an Application-Level Project

Article
02/04/2013

You can bind data to host controls and Windows Forms controls in application-level projects. This walkthrough demonstrates how to add controls to a Microsoft Office Word document and bind the controls to data at run time.

Applies to: The information in this topic applies to application-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

Adding a ContentControl to a document at run time.
Creating a BindingSource that connects the control to an instance of a dataset.
Enabling the user to scroll through the records and view them in the control.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

An edition of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information, see [Configuring a Computer to Develop Office Solutions](bb398242\(v=vs.100\).md).

Word 2007 or Word 2010.
Access to a running instance of SQL Server 2005 or SQL Server 2005 Express that has the AdventureWorksLT sample database attached to it. You can download the AdventureWorksLT database from the CodePlex Web site. For more information about attaching a database, see the following topics:
- To attach a database by using SQL Server Management Studio or SQL Server Management Studio Express, see How to: Attach a Database (SQL Server Management Studio).
- To attach a database by using the command line, see How to: Attach a Database File to SQL Server Express.

Creating a New Project

The first step is to create a Word add-in project.

To create a new project

Create a Word add-in project with the name Populating Documents from a Database, using either Visual Basic or C#.

For more information, see How to: Create Office Projects in Visual Studio.

Visual Studio opens the ThisAddIn.vb or ThisAddIn.cs file and adds the Populating Documents from a Database project to Solution Explorer.
If your project targets the .NET Framework 4, add a reference to the Microsoft.Office.Tools.Word.v4.0.Utilities.dll assembly. This reference is required to programmatically add Windows Forms controls to the document later in this walkthrough.

Creating a Data Source

Use the Data Sources window to add a typed dataset to your project.

To add a typed dataset to the project

On the Data menu, click Add New Data Source.

The Data Source Configuration Wizard opens.
Click Database, and then click Next.
If you have an existing connection to the AdventureWorksLT database, choose this connection and click Next.

Otherwise, click New Connection, and use the Add Connection dialog box to create the new connection. For more information, see How to: Connect to Data in a Database.
In the Save the Connection String to the Application Configuration File page, click Next.
In the Choose Your Database Objects page, expand Tables and select Customer (SalesLT).
Click Finish.

The AdventureWorksLTDataSet.xsd file is added to Solution Explorer. This file defines the following items:
- A typed dataset named AdventureWorksLTDataSet. This dataset represents the contents of the Customer (SalesLT) table in the AdventureWorksLT database.
- A TableAdapter named CustomerTableAdapter. This TableAdapter can be used to read and write data in the AdventureWorksLTDataSet. For more information, see TableAdapter Overview.
You will use both of these objects later in this walkthrough.

Creating Controls and Binding Controls to Data

The interface for viewing database records in this walkthrough is very basic, and it is created right inside the document. One ContentControl displays a single database record at a time, and two Button controls enable you to scroll back and forth through the records. The content control uses a BindingSource to connect to the database.

For more information about binding controls to data, see Binding Data to Controls in Office Solutions.

To create the interface in the document

In the ThisAddIn class, declare the following controls to display and scroll through the Customer table of the AdventureWorksLTDataSet database.

Private adventureWorksDataSet As AdventureWorksLTDataSet
Private customerTableAdapter As AdventureWorksLTDataSetTableAdapters.CustomerTableAdapter
Private customerBindingSource As System.Windows.Forms.BindingSource
Private customerContentControl As Microsoft.Office.Tools.Word.RichTextContentControl
Private WithEvents button1 As Microsoft.Office.Tools.Word.Controls.Button
Private WithEvents button2 As Microsoft.Office.Tools.Word.Controls.Button

private AdventureWorksLTDataSet adventureWorksDataSet;
private AdventureWorksLTDataSetTableAdapters.CustomerTableAdapter customerTableAdapter;
private System.Windows.Forms.BindingSource customerBindingSource;
private Microsoft.Office.Tools.Word.RichTextContentControl customerContentControl;
private Microsoft.Office.Tools.Word.Controls.Button button1;
private Microsoft.Office.Tools.Word.Controls.Button button2;

In the ThisAddIn_Startup method, add the following code to initialize the dataset, fill the dataset with information from the AdventureWorksLTDataSet database.

Me.adventureWorksDataSet = New AdventureWorksLTDataSet()
Me.customerTableAdapter = New AdventureWorksLTDataSetTableAdapters.CustomerTableAdapter()
Me.customerTableAdapter.Fill(Me.adventureWorksDataSet.Customer)
Me.customerBindingSource = New System.Windows.Forms.BindingSource()

this.adventureWorksDataSet = new AdventureWorksLTDataSet();
this.customerTableAdapter = new AdventureWorksLTDataSetTableAdapters.CustomerTableAdapter();
this.customerTableAdapter.Fill(this.adventureWorksDataSet.Customer);
this.customerBindingSource = new System.Windows.Forms.BindingSource();

Add the following code to the ThisAddIn_Startup method. This generates a host item that extends the document. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Dim currentDocument As Word.Document = Me.Application.ActiveDocument

' Use the following line of code in projects that target the .NET Framework 4.
Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)

' In projects that target the .NET Framework 3.5, use the following line of code instead.
' Dim extendedDocument As Document = currentDocument.GetVstoObject()

Word.Document currentDocument = this.Application.ActiveDocument;

// Use the following line of code in projects that target the .NET Framework 4.
Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);

// In projects that target the .NET Framework 3.5, use the following line of code instead.
// Document extendedDocument = currentDocument.GetVstoObject();

Define several ranges at the beginning of the document. These ranges identify where to insert text and place controls.

extendedDocument.Paragraphs(1).Range.InsertParagraphBefore()
extendedDocument.Paragraphs(1).Range.InsertParagraphBefore()
extendedDocument.Paragraphs(1).Range.Text = "The companies listed in the AdventureWorksLT database:   "
extendedDocument.Paragraphs(2).Range.Text = "  "

Dim range1 As Word.Range = extendedDocument.Paragraphs(2).Range.Characters.First
Dim range2 As Word.Range = extendedDocument.Paragraphs(2).Range.Characters.Last
Dim range3 As Word.Range = extendedDocument.Paragraphs(1).Range.Characters.Last

extendedDocument.Paragraphs[1].Range.InsertParagraphBefore();
extendedDocument.Paragraphs[1].Range.InsertParagraphBefore();
extendedDocument.Paragraphs[1].Range.Text = 
    "The companies listed in the AdventureWorksLT database:   \n";
extendedDocument.Paragraphs[2].Range.Text = "  "; 

Word.Range range1 = extendedDocument.Paragraphs[2].Range.Characters.First;
Word.Range range2 = extendedDocument.Paragraphs[2].Range.Characters.Last;
Word.Range range3 = extendedDocument.Paragraphs[1].Range.Characters.Last;

Add the interface controls to the previously defined ranges.

Me.button1 = extendedDocument.Controls.AddButton(range1, 60, 15, "1")
Me.button1.Text = "Previous"
Me.button2 = extendedDocument.Controls.AddButton(range2, 60, 15, "2")
Me.button2.Text = "Next"

Me.customerContentControl = extendedDocument.Controls.AddRichTextContentControl(range3, _
    "richTextContentControl1")

this.button1 = extendedDocument.Controls.AddButton(range1, 60, 15, "1");
this.button1.Text = "Previous";
this.button2 = extendedDocument.Controls.AddButton(range2, 60, 15, "2");
this.button2.Text = "Next";

this.customerContentControl = extendedDocument.Controls.AddRichTextContentControl(
    range3, "richTextContentControl1");

Bind the content control to AdventureWorksLTDataSet by using the BindingSource. For C# developers, add two event handlers for the Button controls.

Me.customerBindingSource.DataSource = Me.adventureWorksDataSet.Customer
Me.customerContentControl.DataBindings.Add("Text", Me.customerBindingSource, _
    "CompanyName", True, Me.customerContentControl.DataBindings.DefaultDataSourceUpdateMode)

this.customerBindingSource.DataSource = this.adventureWorksDataSet.Customer;
this.customerContentControl.DataBindings.Add("Text", this.customerBindingSource, 
    "CompanyName", true, this.customerContentControl.DataBindings.DefaultDataSourceUpdateMode);

this.button1.Click += new EventHandler(button1_Click);
this.button2.Click += new EventHandler(button2_Click);

Add the following code to navigate through the database records.

Private Sub button1_Click(ByVal sender As Object, ByVal e As EventArgs) _
    Handles button1.Click
    Me.customerBindingSource.MovePrevious()
End Sub

Private Sub button2_Click(ByVal sender As Object, ByVal e As EventArgs) _
    Handles button2.Click
    Me.customerBindingSource.MoveNext()
End Sub

void button1_Click(object sender, EventArgs e)
{
    this.customerBindingSource.MovePrevious();
}

void button2_Click(object sender, EventArgs e)
{
    this.customerBindingSource.MoveNext();
}

Testing the Add-In

When you open Word, the content control displays data from the AdventureWorksLTDataSet dataset. Scroll through the database records by clicking the Next and Previous buttons.

To test the add-in

Press F5.

A content control named customerContentControl is created and populated with data. At the same time, a dataset object named adventureWorksLTDataSet and a BindingSource named customerBindingSource are added to the project. The ContentControl is bound to the BindingSource, which in turn is bound to the dataset object.
Click the Next and Previous buttons to scroll through the database records.

Share via

Walkthrough: Simple Data Binding in an Application-Level Project

Prerequisites

Creating a New Project

To create a new project

Creating a Data Source

To add a typed dataset to the project

Creating Controls and Binding Controls to Data

To create the interface in the document

Testing the Add-In

To test the add-in

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources