Creating a Custom Task Pane to Consume SharePoint Server 2007 Query Services in Word 2007

Summary:  Create a custom task pane for Microsoft Office Word 2007 to perform a search query by using the Microsoft Office SharePoint Server 2007 Enterprise Search Query Web service.

Applies to:  Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0, Microsoft Office Word 2007, Microsoft Visual Studio 2005, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System Second Edition

Joel Krist, Akona Systems

October 2007

Microsoft Office SharePoint Server 2007 adds several new features and enhancements to Enterprise Search. The new features provide a consistent and familiar search experience, more relevant search results, new functions to search for people and expertise, the ability to index and search data in line-of-business (LOB) applications, and improved manageability and extensibility. Enterprise Search in Office SharePoint Server 2007 exposes its search functionality through an XML Web service, so that you can access Enterprise Search results from client applications and Web applications outside the context of a SharePoint site. This article explains how to create a custom task pane for Microsoft Office Word 2007 that enables you to perform a search query by using the Enterprise Search Query Web service.

Watch the Video Length: 08:13 | Size: 6.0 MB | Type: WMV file

Code It | Read It | Explore It

Download the Code Sample

The following example uses Microsoft Visual Studio 2005 Tools for the 2007 Office system Second Edition to create a custom task pane. The custom task pane presents a simple user interface (UI) that accepts a search keyword from the user, and then displays the results of the search in a DataGridView control. The search results can be inserted into a Word 2007 document by using an Insert button that is displayed in the DataGridView control. The process includes five major steps:

1. Creating a Word 2007 Add-in project in Microsoft Visual Studio 2005.

2. Adding a reference to the Enterprise Search Query Web service to the Add-in project.

3. Adding a user control to the project that implements the custom task pane.

4. Designing the UI for the custom task pane.

5. Adding the Enterprise Search functionality to the custom task pane.

First, create a Word 2007 Add-in project.

1. Start Visual Studio 2005.

2. On the File menu, click New Project.

3. In the New Project dialog box, expand the Visual Basic node or Visual C# node to view the project types. Then expand the Office node, and select 2007 Add-ins.

4. In the Templates pane, select Word Add-in.

5. Name the project SearchTaskPane.

6. Specify a Location for the project, and then click OK.

   Visual Studio 2005 generates a Word Add-in project that contains a file named ThisAddIn.cs or ThisAddIn.vb, depending on the language selected in Step 3.

Web service discovery is the process by which a client locates a Web service and obtains its service description. The process of Web service discovery in Visual Studio 2005 involves querying a Web site to locate the service description, which is an XML document that uses the Web Services Description Language (WSDL). When a Web reference is added to a project, Visual Studio 2005 generates a proxy class that provides a local representation of the Web service, allowing the client code to interface with the Web service. You can access the Web service methods by calling the methods in the proxy class. The proxy class handles the communication between the client application and the Web service.

1. In Solution Explorer, right-click the SearchTaskPane project, and click Add Web Reference.

2. Type the URL of the Enterprise Search Query Web service. By default, the Web service is located at the following URL:

   http://Server_Name/sites/Site_Name/_vti_bin/search.asmx

3. Click Go to retrieve and display the information about the Web service.

4. Specify QueryService for the Web reference name, and click Add Reference to add the Web reference to the project, as shown in Figure 1.

   Visual Studio downloads the service description and generates a proxy class to interface between the application and the Enterprise Search Query Web service.

   Figure 1. Add Web Reference dialog box

   

Note

Search in Windows SharePoint Services also provides a Query Web service for exposing its search functionality. It supports the same Web methods as the Enterprise Search Query Web service, but it returns Search in Windows SharePoint Services results and it is scoped to the containing site or list. The location for the Search in Windows SharePoint Services Query Web service is: http://Server_Name/sites/Site_Name/_vti_bin/spsearch.asmx For more information, see Windows SharePoint Services Query Web Service in the Windows SharePoint Services 3.0 SDK Documentation.

The custom task pane is implemented as a user control.

1. In Solution Explorer, right-click the SearchTaskPane project, and click Add New Item.

2. In the Add New Item dialog box, click User Control, and name the control SearchControl, as shown in Figure 2.

   Figure 2. Add New Item dialog box

   

3. Click Add.

   Visual Studio adds the user control to the project and opens the control in the designer.

The custom task pane that is implemented in this example displays a simple UI that contains a text box, a button, and a data grid view. The data grid view displays a button in Column 1. When you click the button, the path of the returned item is inserted into the Word 2007 document. Figure 3 shows the task pane displaying the results of a search that uses the keyword Inventory.

1. Set the Width and Height properties of the user control to 300 by 400.

2. Add the following controls to the user control.

   Table 1. Control types to add to the user control

   Expand table

   Control Type	Name	Purpose
   TextBox	txtKeyword	Specify query keyword.
   Button	btnDoQuery	Perform the query.
   DataGridView	dgvQueryResults	Display the search results.

3. Size and position the controls so that they appear in the task pane, as shown in Figure 3.

   Figure 3. Custom Task Pane user interface

   

4. Add a button column to the DataGridView control.

   1. Click the arrow in the upper-right corner of the DataGridView control to display the DataGridView Tasks pane, and then click the Edit Columns link.

   2. Click Add.

   3. In the Add Column dialog box, type Insert for the name of the column, select DataGridViewButtonColumn for the type, and clear the Header text, as shown in Figure 4.

      Figure 4. Adding a Button column

      

   4. Click Add to add the column.

5. Add a column to the DataGridView control to display the path of returned search items.

   1. In the Add Column dialog box, type Path for the name of the column, select DataGridViewTextBoxColumn for the type, enter Item Path for the Header text, and select Read Only, as shown in Figure 5.

      Figure 5. Adding a Path column

      

   2. Click Add to add the column.

   3. Click Close to close the Add Column dialog box.

6. In the Edit Columns dialog box, select the Button column. Set the Text property to Insert, set the UseColumnTextForButtonValue property to True, and set the Width property to 50, as shown in Figure 6.

   Figure 6. Setting Button Column properties

   

7. In the Edit Columns dialog box, select the Item Path column. Set the DataPropertyName property to Path, and set the AutoSizeMode property to DisplayedCells, as shown in Figure 7.

   Figure 7. Setting Item Path Column properties

   

8. Click OK.

9. In the DataGridView Tasks pane, clear the Enable Adding, Enable Editing, and Enable Deleting options.

Next, add Enterprise Search functionality to the custom task pane.

1. Double-click the btnDoQuery button to open the source file for the user control.

   Visual Studio 2005 opens the SearchControl.vb or SearchControl.cs source file and displays the btnDoQuery_Click event handler.

2. Add the following Imports statement or using statement to the top of the SearchControl.vb or SearchControl.cs source file. The Imports and using statements make it possible to use the classes and types defined in the Microsoft.Office.Interop.Word namespace without having to use fully qualified namespace paths.

   For the SearchControl.cs file, add the statement after the using statements generated by Visual Studio 2005 when the user control was created.

   Imports Word = Microsoft.Office.Interop.Word
   

3. Set the AutoGenerateColumns property of the DataGridView control to False to prevent it from displaying all columns returned in the search results.

4. If you are implementing the custom task pane using Visual Basic, add a constructor for the SearchControl class. Select SearchControl in the Class Name drop-down list, and then select New in the Method Name drop-down list, as shown in Figure 8.

   Figure 8. Adding a SearchControl constructor

   

5. Add the following code to the constructor of the SearchControl class, after the Visual Studio-generated call to the InitializeComponent method.

   dgvQueryResults.AutoGenerateColumns = False
   

6. Add the following code to the body of the btnDoQuery_Click event handler.

   ' The string containing the keyword to use in the search.
   Dim keywordString As String = txtKeyword.Text
   
   ' The XML string containing the query request information 
   ' for the Web service.
   Dim qXMLString As String = _
       "<QueryPacket xmlns='urn:Microsoft.Search.Query'>" + _
       "<Query><SupportedFormats><Format revision='1'>" + _
       "urn:Microsoft.Search.Response.Document:Document</Format>" + _
       "</SupportedFormats><Context>" + _
       "<QueryText language='en-US' type='STRING'>" + _
       keywordString + _
       "</QueryText></Context>" + _
       "<IncludeRelevantResults>true</IncludeRelevantResults>" + _
       "</Query></QueryPacket>"
   
   ' Create an instance of the Web service proxy class.
   Dim queryService As QueryService.QueryService = _
       New SearchTaskPane.QueryService.QueryService()
   queryService.Credentials = _
       System.Net.CredentialCache.DefaultCredentials
   
   ' Perform the query and bind the results to the DataViewGrid.
   Try
       Dim queryResults As System.Data.DataSet = _
           queryService.QueryEx(qXMLString)
       dgvQueryResults.DataSource = queryResults.Tables(0)
   Catch ex As Exception
       MessageBox.Show(ex.Message)
   End Try
   

7. Add an event handler for the DataGridView control CellContentClick event so that the task pane can respond when the Insert button is clicked. Switch to the design view of SearchControl.vb or SearchControl.cs and select the dgvQueryResults DataGridView control. Display the control's Events property page, and then double-click the CellContentClick event.

   Visual Studio 2005 switches to the SearchControl.vb or SearchControl.cs code file and displays the dgvQueryResults_CellContentClick event handler. Add the following code to the definition of the dgvQueryResults_CellContentClick method.

   If TypeOf dgvQueryResults.Columns(e.ColumnIndex) Is _
       DataGridViewButtonColumn And e.RowIndex <> -1 Then
   
       Dim myRange As Word.Range = _
           Globals.ThisAddIn.Application.ActiveDocument.Content
       Dim resultPath As String = _
           dgvQueryResults.Rows(e.RowIndex).Cells("Path").Value.ToString()
   
       Try
           myRange.InsertAfter(resultPath)
       Catch
           MessageBox.Show( _
               "The result's path cannot be added to the document.")
       End Try
   End If
   

8. Modify the Word add-in so that the custom task pane appears automatically. Open the ThisAddIn.cs or ThisAddIn.vb file.

   1. Add the following variable declaration to the ThisAddIn class.

      Private ctpSearch As Microsoft.Office.Tools.CustomTaskPane = Nothing
      

   2. Add the following code to the ThisAddIn_Startup handler to create an instance of the custom task pane and add it to the collection of custom task panes that belong to the add-in.

      ctpSearch = Me.CustomTaskPanes.Add( _
          New SearchControl(), "Specify a Search Keyword")
      ctpSearch.Visible = True
      

   3. Add the following code to the ThisAddIn_Shutdown handler to remove the custom task pane from the collection of custom task panes in the add-in.

      Me.CustomTaskPanes.Remove(ctpSearch)
      

Press CTRL+F5 to build and run the application. An instance of Word 2007 starts, and the custom task pane is docked on the right side of the document. Specify a search keyword and click Do Query. The search results are displayed in the DataGridView control. Click Insert for a search result item to insert the path of the item into the Word document.

Note
Visual Studio 2005 created the SearchTaskPaneSetup project when the SearchTaskPane Word 2007 Add-in project was created. You can use the SearchTaskPaneSetup project to install the task pane add-in on a non-development environment computer. For more information about deploying add-ins, see Deploying Application-Level Add-ins.

This article explores how to create a custom task pane for Word 2007 that lets you perform a search query by using the Enterprise Search Query Web service. The following steps were performed:

1. Creating a Word Add-in project in Visual Studio 2005.

2. Adding a reference to the Enterprise Search Query Web service to the project.

3. Adding a user control to the project that implements the custom task pane.

4. Designing the UI of the custom task pane.

5. Adding the Enterprise Search functionality to the custom task pane.

Note
The code and procedures in this article show how to work with Enterprise Search in Office SharePoint Server 2007. However, you can use the same technique to work with Search in Windows SharePoint Services 3.0.

• Creating Word 2007 Templates Programmatically

• Creating Custom Task Panes Using Visual Studio 2005 Tools for the Office System SE

• Blog: Microsoft Visual Studio 2005 Tools for the Microsoft Office System

• Enterprise Search Query Web Service Overview

• How to: Submit a Keyword Query to Enterprise Search from a Client Application

• Windows SharePoint Services Query Web Service

• Comparisons of SharePoint Search Versions