Introduction to the Office 2003 Research Services Class Library

  • Article

 

Chris Kunicki
OfficeZealot.com

September 2004

Applies to:
     Microsoft Office 2003 Editions

Summary: One of four articles, this article describes using the Microsoft Office 2003 Research Service Class Library (RSCL) Wizard. The wizard includes a pluggable architecture that allows you to add new data providers to the wizard or connect to existing providers. (15 printed pages)

Download Office2003_ResearchServicesDevelopmentExtras.msi.

Contents

Introduction
Requirements
List of Samples
Creating a Research Service with the Research Service Class Library
Using the Research Service Class Library Wizard
Wizard-Generated Code
Handling Requests for Registration
Handling a Search Request
Manually Creating an RSCL-Enabled Research Service without the Research Service Class Library Wizard
Additional Documentation for the Research Service Development Extras Toolkit

Introduction

The Research Services Class Library (RSCL) is an object model wrapper around the XML schema API for Microsoft Office 2003 Research Services, as defined in the Office 2003 Research Services Software Development Kit (SDK).

The RSCL simplifies the creation of Research services by abstracting often-used features of the Microsoft Office 2003 Research task pane into a simple object model wrapper. The wrapper produces the XML defined by the Research Service's XML schemas. Using the Research Services Class Library, you can focus on the business logic of the solution rather than the XML code of Research Services.

This document assumes a basic understanding of the Research Services API and XML schemas as defined in the Office 2003 Research Services Software Development Kit (SDK).

Requirements

The RSCL and samples require:

  • The Microsoft .NET Framework 1.1
  • Microsoft Office 2003 Editions (any version)

List of Samples

RSCL includes several code samples designed as teaching aids to assist in learning the various objects in the RSCL. Each sample provided with RSCL is available in Microsoft Visual C# and Microsoft Visual Basic .NET languages. To reinforce the fundamental concepts of this class library, walk through the included samples while exploring this documentation.

You can find the samples in the following directory:

C# version:

C:\Program Files\Microsoft Office 2003 Developer Resources\Research Service Development Extras\CSharp

Visual Basic .NET version:

C:\Program Files\Microsoft Office 2003 Developer Resources\Research Service Development Extras\VBNET

Table1. List of Samples

Sample Directory Name Description
SimpleSample A simple sample that demonstrates how to use a Document response type
SimpleFormSample A simple sample that demonstrates how to use a Form response type and a Form request object
SimpleContentSample A simple sample that demonstrates how to use a complex Content response type
IBuySpy A detailed example showing many aspects of the RSCL. This sample is migrated from the IBuySpy sample found in the Research Services SDK.
Google A Research service built with RSCL that queries the search engine for http://www.google.com/ using the Google Web service API
Feedster A Research service that queries the search engine for http://www.feedster.com/ specializing in searching Web logs (blogs)
DataDocSample A sample that shows how to bind data to the results returned by RSCL
CookiesTester A simple sample that illustrates how to use HTTP cookies sent from the client and how to respond with cookies to the client from the server

Creating a Research Service with the Research Service Class Library

To simplify the creation of a RSCL-enabled project, the toolkit provides the Research Service Class Library Wizard. The wizard collects information about the new research service and generates the appropriate C# or Visual Basic .NET project and source code.

You can also create the RSCL-enabled research service manually. To learn more about creating a RSCL-enabled research service manually read the section Manually Creating an RSCL-Enabled Research Service without the Research Service Class Library Wizard.

Using the Research Service Class Library Wizard

Complete the following procedure to launch the Research Service Class Library Wizard.

  1. In Microsoft Visual Studio .NET 2003, on the File menu, click New Project. The New Project dialog box appears.
  2. In the New Project dialog box, expand either the Visual Basic Projects or Visual C# Projects folder.
  3. Select the Research Service Wrapper project from the list of project types.
  4. Type a URL for the project, and then click OK. The Research Service Class Library Wizard appears.

The first page of the wizard collects information about the research service provider, as shown in Figure 1.

Figure 1. The wizard collects information about the research service provider

Table 2. Information collected about the research service provider

Information Description
Name Name of the provider. Typically, the provider name is the name of the organization responsible for the research service being built.
Message A message the provider displays to the client when they register the research service.
About Path A URL the client can use to find out more information about the provider.
ID A unique ID for the provider. The provider ID needs to be a GUID. You can either provide your own GUID or click New GUID to generate a new one.

The second page of the wizard collects information about the research service, as shown in Figure 2.

Figure 2. The wizard collects information about the research service

Table 3. Information collected about the research service

Information Description
Name The name of the research service. This name displays in the Research task pane in any Microsoft Office 2003 application.
Description A description of the research service. This description is viewable in the Research Service Properties page accessed through the Research task pane in any Office 2003 application.
Category The Research task pane category for the research service in any Office 2003 application
ID A unique ID for the research service. The research service ID needs to be a GUID. You can either provide your own GUID or click New GUID to generate a new one. Note   This ID must differ from the ProviderID.

The third page of the wizard collects license information to display to the client when they register the research service through the Research task pane in any Office 2003 application, and in the property page for the research service. If Require License is set to yes, the client is required to click a check box accepting the license before they can continue registering the Research service. Figure 3 shows the License Information page of the wizard.

Figure 3. The License Information page gathers licensing information.

The fourth page provides the option to specify a data provider that connects the generated research service to a database. To generate an RSCL-enabled research service not connected to a database select "No Data Provider" in the Data Provider drop down list.

To learn more about connecting the generated research service to a database using the wizard see, Connecting to Databases Using the Office 2003 Research Service Class Library Wizard.

Figure 4. The data provider collection page is straightforward.

The next page provides formatting options and displays only when you select a data provider.

The final page provides a Finish button. Once you click Finish, the wizard generates the project and code for the new research service.

Wizard-Generated Code

The generated project and source code are ready to use. The web.config file holds the information about the provider. ResearchService.asmx is the page the client uses to register and query the new research service. ResearchService.asmx includes a sample query response. You can use this as a starting point for building your own query response.

At this point, the research service compiles and runs. However, because no business logic is provided in the Query() method, you can only register the research service, and it does not return search results. The remaining sections in this white paper discuss the Registration() and Query() methods in which the business logic is contained.

Handling Requests for Registration

Before users can access a research service, they must register the research service with the Microsoft Office System. The research service receives a registration request through the Registration() method. The Registration() method gives you an opportunity to customize the registration information returned to the user.

Note   By default, information about the research service stored in the <RSCL.ResearchService> custom configuration section of the web.config file is returned to the user. Therefore, the Registration() method is optional if you define the <RSCL.ResearchService> custom configuration section in the web.config file. It is a good practice to store common information about the research service provider in the web.config and minimize the use of Registration() method.

Using the Registration() Method

The Registration() method receives a RegistrationRequest object and returns a RegistrationResponse object.

A RegistrationRequest object represents an individual request from a client to use the research service. The RegistrationRequest object provides information about the language abilities of the client computer. You can use it to customize the registration response.

A RegistrationResponse object is returned from Registration() method and contains information about the research service the user is registering to use. For example, RegistrationResponse specifies the name of the research service, a description, and a unique service ID.

Handling a Search Request

Research Services provide an API that connects the Office 2003 Research task pane with a remote Web service designed for searching. A user types in a search request in the Research task pane and it is submitted to the Research service. RSCL exposes the search request and response through the Query() method.

Using the Query() Method

The Query() method receives a QueryRequest object and returns a QueryResponse object.

A QueryRequest object represents an individual search request from the client. The QueryRequest object contains a number of properties to expose information about the user's submitted search. The most common property is QueryRequest.QueryText. This returns the text the user typed in the Search for: textbox in the Research task pane.

A QueryResponse object is returned from the Query() method and contains the results of the search. These results are then displayed in the Research task pane. The Research Service SDK defines three types of results that you can return to the Office System:

  • Document. A simple response type with a title, description, and URL.
  • Content. A rich response type that allows for text, images, hyperlinks, buttons, smart tags, and more.
  • Form. Form controls for collecting complex data. The form controls are similar to the controls used in HTML.

The QueryResponse object can return each of these result types and can even return multiple result types in one response. To return a result type through a QueryResponse object, an object of the type ResponseWriter is sent as a parameter to the QueryResponse.WriteResponse method. RSCL includes five ResponseWriter objects.

  • DocumentResponseWriter. Defines a document result, which typically consists of a title, a description, and a link. See the SimpleSample sample to see how to use DocumentResponseWriter.
  • ContentResponseWriter. Defines rich content and actions that you can return as results in the query response. See the SimpleContentSample sample to see how to use ContentResponseWriter.
  • FormResponseWriter. Forms enable a research service to interact with the user by providing extensive data entry choices. For example, Research Services support labels, text boxes, drop-down lists, check boxes, and more. See the SimpleFormSample sample to see how to use FormResponseWriter. Also, see the IBuySpy sample for a complex example of FormResponseWriter.
  • DatabaseDocumentResponseWriter. DatabaseDocumentResponseWriter derives from DocumentResponseWriter and returns a group of results based on the data contained in an ADO.NET DataTable object. See the DataDocSample sample to see how to use DatabaseDocumentResponseWriter.
  • ResponseWriter. ResponseWriter is the base object for all response writers. You can use ResponseWriter to return generic user-defined XML.

The following is an excerpt from the SimpleSample sample that illustrates how the Query() method is used in Visual Basic .NET:

     Public Overloads Overrides Function Query(ByVal request _
        As QueryRequest) As QueryResponse

        Dim response As New QueryResponse
        Dim doc As New DocumentResponseWriter

        Select Case request.QueryText.ToLower()
           Case "word"
              doc.WriteItem("Word - Office Online", _
                        "Useful resources for Word 2003", _
                        "http://office.microsoft.com/word", _
                        "Go to Office Online")
           Case "excel"
              doc.WriteItem("Excel - Office Online", _
                        "Useful resources for Excel 2003", _
                        "http://office.microsoft.com/Excel", _
                        "Go to Office Online")
           Case Else
              doc.WriteItem("Example Search Terms for this Sample are", _
              "Word and Excel.")
        End Select

        response.WriteReponse(doc)
        Return response
     End Function

In C:

    public override QueryResponse Query(QueryRequest request)
    {
        QueryResponse response = new QueryResponse();
        DocumentResponseWriter doc = new DocumentResponseWriter(); 

        switch (request.QueryText.ToLower().Trim())
        {
            case "word":
                doc.WriteItem("Word - Office Online", 
                            "Useful resources for Word 2003", 
                            "http://office.microsoft.com/word", 
                            "Go to Office Online");
                break;
            case "excel":
                doc.WriteItem("Excel - Office Online", 
                            "Useful resources for Excel 2003", 
                            "http://office.microsoft.com/Excel", 
                            "Go to Office Online");
                break;
            default:
                doc.WriteItem("Example Search Terms for this Sample are",
                            "Word and Excel.");
                break;
        }
        
        response.WriteReponse(doc);
        return response;
    }

SimpleSample Code Walkthrough:

  • A QueryResponse object named response is instantiated and is returned to the client.
  • A DocumentResponseWriter object named doc is instantiated. This variable holds the results of type Document that are returned to the client.
  • A request.QueryText contains the value of the search term sent to the research service. Using request.QueryText, you can formulate a response based on the business logic of the solution.
  • The WriteItem method of the doc object is used to add Document items to the response.
  • The doc variable is passed as a parameter to the WriteReponse method of the response object.
  • The response object is returned from the Query() method.

This concludes the walkthrough of building a simple RSCL-enabled research service. We recommend that you work through the RSCL samples to become familiar with the abilities of the Research Services Class Library.

Manually Creating an RSCL-Enabled Research Service without the Research Service Class Library Wizard

Creating a research service with RSCL is similar to developing a standard Web service with Visual Studio .NET.

In Visual Studio .NET, create an ASP.NET Web Service project using either C# or VB.NET in the New Project Wizard.

After you create the project, add a reference to the RSCL.dll assembly. By default, the RSCL.dll file is found in the directory, install_path\bin\release.

Note   If the RSCL.dll assembly is not compiled yet, go to install_path\Classlibrary and open the RSCL.s file in the Visual Studio .NET solution file. Then, compile the project. After compiling, you can link to the RSCL.dll assembly file.

Next, make the changes described in the next section to Service1.asmx created by the ASP.NET Web Service New Project Wizard.

Step 1: Include the RSCL namespaces to use in this code file

In Visual Basic .NET:

     Imports Microsoft.Samples.Office.ResearchService
     Imports Microsoft.Samples.Office.ResearchService.Registration
     Imports Microsoft.Samples.Office.ResearchService.Query

In C:

     using Microsoft.Samples.Office.ResearchService;
     using Microsoft.Samples.Office.ResearchService.Registration;
     using Microsoft.Samples.Office.ResearchService.Query;

Step 2: Change Service1 class to derive from ResearchWebService

In Visual Basic .NET, change:

     Public Class Service1
          Inherits System.Web.Services.WebService

to:

     Public Class Service1
          Inherits ResearchWebService

In C, change:

     public class Service1 : System.Web.Services.WebService

to:

     public class Service1 : ResearchWebService

The ResearchWebService base class derives from System.Web.Services.WebService. This gives ResearchWebService all the abilities of a Web service with the extra plumbing needed by the research service's API.

Step 3: Create the two default methods required by a research service

In Visual Basic .NET:

    Public Overloads Overrides Function Registration(ByVal request _
    As RegistrationRequest) As RegistrationResponse

    End Function
    
    Public Overloads Overrides Function Query(ByVal request _
        As QueryRequest) As QueryResponse

    End Function

In C:

    public override RegistrationResponse Registration(RegistrationRequest
request)
    {
        return base.Registration(request);
    }

    public override QueryResponse Query(QueryRequest request)
    {
        return base.Query(request);
    }

The Registration() method receives a RegistrationRequest object that represents an Office 2003 client request to use the research service. The Registration() method returns a RegistrationResponse object that contains the information the client needs to use the research service.

After the Office 2003 client registers to use the research service, the user can send search requests. Search requests are sent to the Query() method of the research service. QueryRequest represents the search request that the user submitted and a QueryResponse is returned to the client with results of the search.

Step 4: Configure the web.config file

RSCL centralizes commonly used information in the ASP.NET web.config file in a custom configuration section. The use of the web.config file is optional, although most developers use it because it reduces the amount of code used in a RSCL research service.

In the web.config file, after the opening <configuration> node, include the following XML:

<configSections>
    <section name="RSCL.ResearchService" type=
    "Microsoft.Samples.Office.ResearchService.Config.RSCLConfigLoader,RSCL,1.1.4322.573,
    Culture=neutral, PublicKeyToken=null" />
</configSections>

<!-- RSCL web.config section -->
<RSCL.ResearchService>
    <Provider>
        <Name>Provider Name</Name>
        <Message>Provider Welcome Message</Message>
        <ID>Unique GUID for the provider</ID>
    </Provider>
    <Service>
        <Name>Service Name that appears in Office Research Task Pane</Name>
        <Description>Description of research service</Description>
        <Category>RESEARCH_GENERAL</Category>
        <License>License Text here</License>
        <ID>Unique GUID for the provider</ID>
    </Service>
</RSCL.ResearchService>

The <configSections> defines a section handler and is required for ASP.NET to recognize the <RSCL.ResearchService>.

The <ID> node for both the provider and research service require unique GUIDs. Visual Studio .NET includes a tool to generate GUIDs, named Create GUID, which****is found on the Tools menu in Visual Studio .NET.

The <Category> node defines the category under which the Research service shows in the Research task pane in the Microsoft Office System. The available categories are documented in the Microsoft.Search.Types.xsd schema file included with the Office 2003 Research Services Software Development Kit (SDK).

Also note, if you use this custom configuration section, the Registration() method as defined in the previous step is optional. If it is there, RSCL pulls the information from the web.config file by default. You can use the Registration() method to override any values stored in the web.config file.

Additional Documentation for the Research Service Development Extras Toolkit

Read the following articles for more information about the Research Service Development Extras Toolkit:

About the Author

Chris Kunicki is a longtime enthusiast of Office development and has been evangelizing Office as an important platform for building solutions for many years. As the founder of OfficeZealot.com, a leading Web site on Office solutions development, Chris builds enterprise solutions, designs tools for developers, delivers presentations, and writes extensively on the topic of Microsoft Office. Find out more about Chris and Office at www.OfficeZealot.com or send him an e-mail message at chris@officezealot.com.

© Microsoft Corporation. All rights reserved.