IBuySpy Sample

IBuySpy.com is a fictitious retailer of spying supplies that operates an online store. The IBuySpy research service illustrates how a corporation's custom research service can enable employees and customers to access and interact with important corporate data from the familiar environment of Microsoft® Office 2003.

Installing the research service

To install the IBuySpy research service, follow the three primary steps:

1. Configure the research service.

   Requirements

   • Microsoft Office 2003
   • Microsoft .NET Framework 1.0 or later
   • Microsoft .NET Framework 1.0 Software Development Kit, or a later release
   • Microsoft Visual Studio® .NET 2002 (to modify and rebuild the Web service if necessary)
   • Microsoft Internet Information Services (IIS) 5.0 or later

   Note  IIS should be installed before you set up the Microsoft .NET Framework SDK and Microsoft Visual Studio .NET. If you have installed or re-installed IIS after setting up the Microsoft .NET Framework SDK, you will experience unexpected behavior when you try to view ASP.NET pages. To fix this, register ASP.NET with IIS again by running the aspnet_regiis.exe utility. For more information, see Knowledge Base article 306005 , "HOWTO: Repair IIS Mapping After You Remove and Reinstall IIS."

   Configure the research service

   1. Do one of the following:

      • If you have installed the Research SDK on the computer that hosts the IIS server ServerName, go to step 2.

      • If you have installed the Research SDK on a computer other than ServerName, do the following:

        1. Create a folder named IBuySpyResearchPane on ServerName. This is the research service folder.

           Note  To avoid access problems when running running the IBuySpy Web service, do not place the IBuySpyResearchPane folder in the My Documents folder.

        2. The source files, run-time files, and a sample document are located at Drive:\Program Files\Microsoft Office 2003 Developer Resources\Microsoft Office 2003 Research Service SDK\Samples\IBuySpy Sample, where Drive is the drive where you have installed the SDK.

           Folder structure

           Root Folder	Sub Folder	Description
           \IBuySpyResearchPane		Root folder for the XML Web service and source code.
           	\bin	Assembly file for the research service.
           	\data	Microsoft Jet database that stores the product catalog.
           	\images	Product images and company logo.
           	\xml	XML wrapper files used by the source code.
           \SmartTag		Root folder for the smart tag DLL and source code.
           \Documents		Sample document Customer letter.doc.

           On the computer that the SDK is installed on, copy the contents of the IBuySpyResearchPane folder to the IBuySpyResearchPane folder on ServerName.

   2. Make sure the default Web site in Internet Information Services (IIS) is running on the server computer ServerName.

      • In Microsoft Windows® Control Panel, click Administrative Tools, and then click Internet Information Services.
      • In the left-hand pane, expand the node containing the name of your Web server, ServerName.
      • Expand Web Sites.
      • Right-click the Default Web Site node, then click Start. If Start is inactive, that means IIS is already running.

   3. Map the research service folder to a virtual directory.

      To map the research service folder to a virtual directory named IBuySpyService on ServerName:

      1. From the Microsoft Windows® Start menu, click Control Panel, and then double-click Administrative Tools.
      2. Double-click Internet Information Services.
      3. In the Internet Information Services folder tree, expand the folders for the local computer, the Web Sites directory, and the Default Web Site.
      4. Create a new virtual directory named IBuySpyService by right-clicking Default Web Site, and then selecting New and Virtual Directory. Follow the instructions in the Virtual Directory Creation Wizard.

   4. By default, the IBuySpy research service assumes that the client computer is the same computer as ServerName and is configured to use http://localhost/ as its server. To change the setup so that the service can be accessed from a different computer, edit the Web.config file that is located in the research service folder. Edit the value attribute of the add element

      <add key="ServerPath" value="http://localhost"/>
      

      by changing it to the name of your server. For example:

      <add key="ServerPath" value="http://www.MyServerName.com"/>
      

   5. If you use a firewall to gain access to the Internet, check with your organization's network administrator to see if there is any special firewall client software that needs to be installed, or any special connectivity settings that need to be made.

2. Configure the smart tag.

   The research service uses a client-side smart tag to provide a richer set of features for interactions with Office documents. If the smart tag is not installed, the research service will function normally, but the smart tag menu items will not be available.

   To install the smart tag on the client computer:

   1. Do one of the following:

      • If you have installed the Research Service SDK on this client computer, go to step 2 below.

      • If you have installed the Research Service SDK on a computer other than the client computer, do the following:

        1. Create a folder named IBuySpy Sample on the client computer.
        2. From the computer that the SDK is installed on, copy the contents of the IBuySpy Sample folder (under Drive:\Program Files\Microsoft Office 2003 Developer Resources\Microsoft Office 2003 Research Service SDK\Samples) to the IBuySpy Sample folder on the client computer.

   2. On the client computer, open a command prompt and navigate to IBuySpy Sample\SmartTag.

   3. Register the smart tag DLL by using the following command-line command:

      regsvr32 ProductSmartTag.dll
      

   4. A message box will appear stating, "DllRegisterServer in productsmarttag.dll succeeded." Click OK.

   5. To notify Office that this smart tag is available, type the following command at the command line:

      regedit RegistrySetup.reg
      

      You will be prompted to confirm that you want to import this information into the registry. Click Yes.

   6. A message box will appear stating, "Information in registrysetup.reg has been successfully entered into the registry." Click OK.

   7. To make the newly-installed smart tag available and active, close and reopen any applications in which you want to use the smart tag.

3. Add the research service to the Research task pane.

   Before you can search on the IBuySpy research service for the first time, you must add the research service to the Research task pane by using the URL http://ServerName/IBuySpyService/Registration.asmx. For more information about adding a research service, see Adding Services through the Office User Interface.

Searching the research service

The IBuySpy research service, IBuySpy.com Product Information, is integrated with a product catalog, and lets you browse different categories in the catalog. When you click a specific category, all of the products within that category are listed in the Research task pane.

Use the sample customer letter (Customer Letter.doc in Drive:\Program Files\Microsoft Office 2003 Developer Resources\Office 2003 Research Service SDK\Samples\IBuySpy Sample\Documents), to search the product catalog and insert product information.

Product Search and Details

Customer Letter.doc is a response letter that needs to be written to a customer that liked Counterfeit Creation Wallet, which is one of IBuySpy.com's products. Use the research service to search for related products to suggest to this customer. Without Research services, you would need to open another application or Web page to look up the product information, and manually copy and paste the information into the letter. But with this service, the process is integrated directly with Microsoft Office Word 2003.

1. Open Customer Letter.doc in Word.
2. While holding down the ALT key, click products in the document. This opens the Research task pane.
3. Under Search for, type wallets.
4. Select the IBuySpy.com Product Information research service if it has not been selected yet.
5. Click Protection on the Research task pane.
6. Scroll to view the products listed.

Inserting Product Information

The Research task pane page lists products that are related to "wallets." For example, the Bullet Proof Facial Tissue is listed, and may be of interest to the customer.

In the product details, there is a set of actions that are available from directly within the Research task pane. These actions make it easy to insert product information.

1. Under Bullet Proof Facial Tissue, click Product Details.
2. Move the insertion point in the Customer Letter document to the white space immediately following the text "…of the following related products."
3. Click Insert Model Name and Description from the actions menu.
4. Click Insert Product Image from the actions menu.

Advanced product search

The advanced product search allows you to search through the entire product catalog using criteria such as specific product categories, price ranges, and whether the items are in stock.

1. Click Advanced product search.
2. Type 500 in the Product low price (Optional) control.
3. Type 1500 in the Product high price (Optional) control.
4. Click Only show items in stock.
5. Click Go.

Design of the research service

In the Search namespace, the IBuySpy research service specifies the Web methods: Registration, Query, and Status. The pages http://ServerName/IBuySpyService/Registration.asmx and http://ServerName/IBuySpyService/Query.asmx provide brief descriptions of each of the methods and hyperlinks to the formal definitions of these methods.

Registration

This method is called when you first add the IBuySpy research service to the task pane. At this point, it sends a registration request. This method always returns a registration response, and Office adds this research service to its lists of services. The registration response supports the Microsoft.Search.Registration.Response Schema.

Note that the QueryPath element refers to:

http://ServerName/IBuySpyService/Query.asmx

This is the pointer to the Query Web method for this research service.

Query

QueryProcessor class

The bulk of the processing done in this solution is handled by the QueryProcessor class. It has the following class structure:

Public Class QueryProcessor
    Inherits System.Web.Services.WebService
<WebMethod()> Public Function Query(ByVal queryXml As String) As String
Private Function Response_ProductDetails(…) As String
Private Function Response_ProductSummaryForCategory(…) As String
Private Function Response_CategoryListAsForm(..) As String
Private Function Response_ProductKeywordSearch(…) As String
Private Function Response_NoResults(…) As String
<WebMethod()> Public Function Status() As String
End Class

The public function Query that is marked with <WebMethod()> is the other key Web method for this research service. Each request from the client is passed into this function and stored in the queryXml parameter.

Query parses queryXml for search terms, form-based requests, and other search parameters specified by the user. Query then determines which results to return by calling the remaining functions that have the Response_ prefix. These functions are marked as Private. They simply serve as utility functions that enable the Query function to respond to the user request.

The following table describes how each of these methods are used:

XMLTextWriter object

The Query function uses the XMLTextWriter object. This object provides a highly efficient and lightweight way of constructing a well-formed XML document. Since the response from the Query interface is based on schema-structured XML, it is important to have a well-formed XML document, otherwise the Research task pane is likely to show an empty pane. The query response supports the Microsoft.Search.Response Schema.

Most of the Response_ routines create an XML writer with the following code:

Dim ioMemStream As New MemoryStream()
Dim outputXmlWriter As New XmlTextWriter(ioMemStream, Nothing)

With this object, the query response can be constructed. For example:

While productDetailsData.Read
    .WriteStartElement("P")
    .WriteStartElement("Char")
    .WriteAttributeString("bold", "true")
    .WriteString("Hologram Cufflinks"))
    .WriteEndElement()  
    .WriteStartElement("Char")
    .WriteAttributeString("light", "true")
    .WriteString("THNKDKE1")
    .WriteEndElement()
    .WriteEndElement()
End While

The following XML is created:

<P>
<Char bold="true">Hologram Cufflinks</Char>
<Char light="true">THNKDKE1</Char>
</P>

At first glance, this may appear to be a lot of code to create a simple XML string. However, a typical response packet can be 50 to 100 lines of XML. This can be cumbersome to manage with generic string-handling routines. The XMLTextWriter object provides both a memory-efficient way of constructing this XML response packet and an easy way to create and manage code.

urn:Microsoft.Search namespace

The Registration and Query Web methods wrap a Registration or Query response into the body of a SOAP message. These methods are specified with a directive that defines the namespace used for the SOAP message:

<WebService(Namespace:="urn:Microsoft.Search")>

The Research task pane responds only to SOAP messages with this namespace.

Status

This method returns the status of the server that hosts the research service.

For more information about the research service schemas, see XML Schemas Overview.