Walkthrough: Bind to data from a service in a VSTO Add-in project

Applies to: Visual Studio Visual Studio for Mac

You can bind data to host controls in VSTO Add-in projects. This walkthrough demonstrates how to add controls to a Microsoft Office Word document, bind the controls to data retrieved from the MSDN Content Service, and respond to events at run time.

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

This walkthrough illustrates the following tasks:

• Adding a RichTextContentControl control to a document at run time.

• Binding the RichTextContentControl control to data from a web service.

• Responding to the Entering event of a RichTextContentControl 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 Personalize the IDE.

Prerequisites

You need the following components to complete this walkthrough:

• An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.

• Word 2013 or Word 2010.

Create a new project

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

To create a new project

1. Create a Word VSTO Add-in project with the name MTPS Content Service, 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 project to Solution Explorer.

Add a web service

For this walkthrough, use a web service called the MTPS Content Service. This web service returns information from a specified MSDN article in the form of an XML string or plain text. A later step shows how to display the returned information in a content control.

To add the MTPS content service to the project

1. On the Data menu, click Add New Data Source.

2. In the Data Source Configuration Wizard, click Service, and then click Next.

3. In the Address field, type the following URL:

   http://services.msdn.microsoft.com/ContentServices/ContentService.asmx

4. Click Go.

5. In the Namespace field, type ContentService, and click OK.

6. In the Add Reference Wizard dialog box, click Finish.

Add a content control and bind to data at run time

In VSTO Add-in projects, you add and bind controls at run time. For this walkthrough, configure the content control to retrieve data from the web service when a user clicks inside the control.

To add a content control and bind to data

1. In the ThisAddIn class, declare the variables for the MTPS Content Service, the content control, and the data binding.

   private ContentService.getContentRequest request;
   private ContentService.ContentServicePortTypeClient proxy;
   private ContentService.requestedDocument[] document;
   private ContentService.getContentResponse response;
   private ContentService.appId appId;
   private Microsoft.Office.Tools.Word.RichTextContentControl richTextContentControl;
   private System.ComponentModel.Container components;
   private System.Windows.Forms.BindingSource primaryDocumentsBindingSource;
   

   Private request As ContentService.getContentRequest
   Private proxy As ContentService.ContentServicePortTypeClient
   Private document As ContentService.requestedDocument()
   Private response As ContentService.getContentResponse
   Private appId As ContentService.appId
   Private WithEvents richTextContentControl As Microsoft.Office.Tools.Word.RichTextContentControl
   Private components As System.ComponentModel.Container
   Private primaryDocumentsBindingSource As System.Windows.Forms.BindingSource
   

2. Add the following method to the ThisAddIn class. This method creates a content control at the beginning of the active document.

   private void AddRichTextControlAtRange()
   {
       Word.Document currentDocument = this.Application.ActiveDocument;
       currentDocument.Paragraphs[1].Range.InsertParagraphBefore();
   
       Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);
   
       richTextContentControl = extendedDocument.Controls.AddRichTextContentControl(
           currentDocument.Paragraphs[1].Range, "richTextContentControl");
       richTextContentControl.PlaceholderText =
           "Click here to download MSDN Library information about content controls.";
   }
   

   Private Sub AddRichTextControlAtRange()
   
       Dim currentDocument As Word.Document = Me.Application.ActiveDocument
       currentDocument.Paragraphs(1).Range.InsertParagraphBefore()
   
   
       Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)
   
   
       richTextContentControl = extendedDocument.Controls.AddRichTextContentControl _
           (currentDocument.Paragraphs(1).Range, "richTextControl2")
       richTextContentControl.PlaceholderText = _
           "Click here to download MSDN Library information about content controls."
   End Sub
   

3. Add the following method to the ThisAddIn class. This method initializes the objects needed to create and send a request to the web service.

   private void InitializeServiceObjects()
   {
       request = new ContentService.getContentRequest();
       proxy = new ContentService.ContentServicePortTypeClient();
       document = new ContentService.requestedDocument[1];
       response = new ContentService.getContentResponse();
       appId = new ContentService.appId();
       components = new System.ComponentModel.Container();
       primaryDocumentsBindingSource = new System.Windows.Forms.BindingSource(this.components);
   }
   

   Private Sub InitializeServiceObjects()
       request = New ContentService.getContentRequest()
       proxy = New ContentService.ContentServicePortTypeClient()
       document = New ContentService.requestedDocument(0) {}
       response = New ContentService.getContentResponse()
       appId = New ContentService.appId()
       components = New System.ComponentModel.Container()
       primaryDocumentsBindingSource = New System.Windows.Forms.BindingSource(components)
   End Sub
   

4. Create an event handler to retrieve the MSDN Library document about content controls when a user clicks inside of the content control and bind the data to the content control.

   void richTextContentControl_Entering(object sender, ContentControlEnteringEventArgs e)
   {
       document[0] = new ContentService.requestedDocument();
       document[0].type = ContentService.documentTypes.primary;
       document[0].selector = "Mtps.Xhtml";
   
       request.contentIdentifier = "ed59e522-dd6e-4c82-8d49-f5dbcfcc950d";
       request.locale = "en-us";
       request.version = "VS.90";
       request.requestedDocuments = document;
   
       response = proxy.GetContent(appId, request);
       primaryDocumentsBindingSource.DataSource =
           response.primaryDocuments[0].Any.InnerText;
       richTextContentControl.DataBindings.Add("Text",
           primaryDocumentsBindingSource.DataSource, "", true,
           System.Windows.Forms.DataSourceUpdateMode.OnValidation);
   }
   

   Private Sub richTextContentControl_Entering _
       (ByVal sender As Object, ByVal e As ContentControlEnteringEventArgs) _
       Handles richTextContentControl.Entering
   
       document(0) = New ContentService.requestedDocument()
       With document(0)
           .type = ContentService.documentTypes.primary
           .selector = "Mtps.Xhtml"
       End With
   
       With request
           .contentIdentifier = "ed59e522-dd6e-4c82-8d49-f5dbcfcc950d"
           .locale = "en-us"
           .version = "VS.90"
           .requestedDocuments = document
       End With
   
       response = proxy.GetContent(appId, request)
   
       primaryDocumentsBindingSource.DataSource = _
           response.primaryDocuments(0).Any.InnerText
       richTextContentControl.DataBindings.Add("Text", _
           primaryDocumentsBindingSource.DataSource, "", True, _
           System.Windows.Forms.DataSourceUpdateMode.OnValidation)
   End Sub
   

5. Call the AddRichTextControlAtRange and InitializeServiceObjects methods from the ThisAddIn_Startup method. For C# programmers, add an event handler.

   private void ThisAddIn_Startup(object sender, System.EventArgs e)
   {
       AddRichTextControlAtRange();
       InitializeServiceObjects();
       this.richTextContentControl.Entering += richTextContentControl_Entering;
   }
   

   Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
       AddRichTextControlAtRange()
       InitializeServiceObjects()
   End Sub
   

Test the Add-in

When you open Word, the RichTextContentControl control appears. The text in the control changes when you click inside it.

To test the VSTO Add-in

1. Press F5.

2. Click inside of the content control.

   Information is downloaded from the MTPS Content Service and displayed inside the content control.

See also

• Bind data to controls in Office solutions