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:
Configure the research service.
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
If you have installed the Research SDK on a computer other than ServerName, do the following:
Note To avoid access problems when running running the IBuySpy Web service, do not place the IBuySpyResearchPane folder in the My Documents folder.
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.
Map the research service folder to a virtual directory.
To map the research service folder to a virtual directory named IBuySpyService on ServerName:
<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"/>
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:
regsvr32 ProductSmartTag.dll
regedit RegistrySetup.reg
You will be prompted to confirm that you want to import this information into the registry.
Click Yes.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.
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.
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.
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.
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.
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.
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:
Function | Description |
---|---|
Response_ProductDetails | Returns details on a specific product. |
Response_ProductSummaryForCategory | Returns a summary for all products in a certain category. |
Response_CategoryListAsForm | Returns a form that contains a drop-down list of available product categories. |
Response_ProductKeywordSearch | Returns a response to a keyword search against model name and product description in the product database. |
Response_NoResults | Returns a generic page for any searches that produced no matching results. This function ensures that a user is never left without guidance on what to search for. |
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.
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.