Developing Office Solutions

Although the Office 2003 System offers several collaboration features for end users that do not require any separate development, in order to create more complicated solutions, you will need to roll up your sleeves and write some code. Office 2003 development is a broad and deep topic, and complete coverage is beyond the scope of this book. In this section, however, we'll investigate several key topics that can be integrated with an organizational solution based on SharePoint products and technologies.

XML Support

One of the greatest challenges in creating business solutions based on documents has always been navigating the document structure. In the past, developers have been limited to using bookmarks and the clumsy Range object to locate key portions of a document through code. Microsoft has attempted to address this problem by providing XML structural support in the Office system. This support includes both native XML structures and the ability to use external schemas to define document structure. Imposing an XML schema on a document causes it to be well formed and therefore much easier to manipulate through code.

Both Microsoft Word and Excel have the ability to save documents in XML format directly from the product menu. In Microsoft Word, however, this ability is taken even further through the use of a native XML structure called WordML. WordML is a detailed XML format that preserves all native Word document formatting. In this way, you can utilize well-formed XML within Word documents to easily locate document sections with standard XML processing tools.

In addition to the built-in structure of WordML, you can define your own XML schemas and impose those schemas upon a Word document. The value of this approach is that you can make the schema as simple or as complex as you need, and you do not have to impose the schema upon the entire document. Instead, you can select parts of the document and insert nodes that will enforce document structure.

Before you can insert nodes into a document, you must define an XML schema and attach it to a document. Your custom XML schema is defined in an XML Schema Document (XSD) document according to the schema definition expected by Word. A discussion of the complete schema definition is beyond the scope of this book, but you can reference it by downloading the Word developer SDK from msdn.microsoft.com . Nonetheless, creating a basic schema can be straightforward and requires little more than the definition of a set of nodes. Listing 8-1 shows a simple schema definition for an address label.

Listing 8-1: A Simple Schema

 <?xml version="1.0" encoding="utf-8" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"     xmlns="urn:schemas-microsoft-com.DataLan.Address"     targetNamespace="urn:schemas-microsoft-com.DataLan.Address"     elementFormDefault="qualified"     attributeFormDefault="unqualified"     id="AddressInfo">     <xsd:element name="Address1" type="xsd:string"/>     <xsd:element name="Address2" type="xsd:string"/>     <xsd:element name="City" type="xsd:string"/>     <xsd:element name="State" type="xsd:string"/>     <xsd:element name="Zip" type="xsd:string"/> </xsd:schema> 

 

Notice that the schema defines a set of fields for the address label and the data type for each field. In this case, I have defined a string for each field, but you can also use types such as integer and boolean . These types are used by Word to validate the structure of the document after the schema is attached. The designer can attach schemas to documents directly from the Word menu.

Here is how to attach a schema:

1. From the menu in Microsoft Word, select Tools Templates and Add-Ins.

2. In the Templates and Add-Ins dialog, select the XML Schema tab.

3. On the XML Schema tab, click the Add Schema button.

4. Navigate to the XSD file containing the schema you want to load and click Open.

Once the schema is attached to a document, you can insert nodes from the task pane. The top of the task pane has a drop-down menu that allows you to access the XML structure of the document. In this view, you are shown the available node definitions and can select to insert them. You can also choose to make the XML structure visible in the document or hide the nodes. Figure 8-6 shows a mailing label in Microsoft Word built using the schema from Listing 8-1.

Figure 8-6: XML schema visible in Word

A schema can be immediately helpful to an end user . For example, when you are collaborating to create a document, you can easily use the node definitions to assign tasks to others. Additionally, an attached schema will be used to validate the document structure. Whenever the entered data violates the schema definition, an error will appear in the document as well as in the task pane. Figure 8-7 shows an error when a user enters the wrong data type in a field.

Figure 8-7: Displaying schema errors

Along with providing structure and validation, an XML schema makes it much easier to write programs that manipulate document sections. Developers can access the document sections through the node definitions to create workflow applications or automate processing. This even includes documents that can fill in their own information.

Smart Documents

With the release of Office 2003, Microsoft has tried to make document-centric development more attractive by enhancing the Smart Document capability originally introduced in Office XP. Smart documents are documents that have a level of situational and contextual awareness. This means, for example, that a document table with a list of products knows that it is associated with a product catalog. Furthermore, the information contained in the table is accessible to programmers in a standardized schema embodied in XML.

The primary characteristic of smart documents is that they present a set of controls to a user based on the XML node that is currently active. These controls typically appear in the task pane and offer information necessary to complete the active section of the document. Figure 8-8 shows a typical smart document with controls visible in the task pane.

Figure 8-8: Accessing smart document controls

Smart documents are a combination of an XML schema and programming code developed in C# or VB.NET. They are deployed to end users through an XML expansion pack, which is a combination of a manifest, an assembly, and a schema. The manifest is an XML file that tells the Office product what files make up the smart document solution. The assembly is the encapsulation of the smart document functionality. The schema is the same type of schema discussed earlier. Creating smart documents is about as difficult as creating a basic web part. Not only must you create the functionality and XML files, you must also deal with code access security issues.

Preparing the Environment

Before you can begin to create smart documents, you must create a development environment. Although you should already have Visual Studio installed, you must also install the primary Interop assemblies (PIA) for the target Office product and Smart Tags. Developing smart documents requires the PIAs because Office is still a Component Object Model (COM)-based product. As a result, you must install the PIAs in order to use the .NET environment with the Office suite.

To install required programmability support, you will need to take these steps:

1. Log in to SPSPortal as a local administrator.

2. Place the Microsoft Office 2003 setup disc in the drive.

3. When prompted by the setup routine, choose to perform a Custom Install.

4. Click Next .

5. On the Custom Setup screen, check the "Choose advanced customization of applications" box.

6. Click Next.

7. On the Advance Customization screen, expand the tree and choose to install .NET Programmability Support for each Office product.

8. Expand the tree for Office Tools and choose to install Microsoft Forms 2.0 .NET Programmability Support and Smart Tag .NET Programmability Support. Figure 8-9 shows the selections.

   
   Figure 8-9: Installing programmability support

9. Click Next.

10. Review the installation options and click the Install button.

Along with the PIAs, you should also install the Office 2003 Smart Document SDK. This SDK not only contains valuable documentation, but also several tools that you will need to successfully build smart documents. In particular, smart documents run as partially trusted code, so you will have to modify configuration files on the client to trust them. The Office 2003 Smart Document SDK contains a graphical tool that makes it much easier to modify the .NET configuration for a client.

Note

Do not confuse the client configuration required for smart documents with the server configuration you performed for SPS. Although both client and server use .NET security, the client configuration affects how local code runs and is not related to the code access security configuration of the server where SPS runs.

Relating Schema and Functionality

Once you have set up the development environment, you can begin a new smart document project. The functionality of smart documents is created as a .NET assembly that implements an interface to allow interaction between the assembly and the associated Office product. Therefore, every smart document begins as a class library project in Visual Studio.

In order to participate in the smart document life cycle, a class library must implement the ISmartDocument interface. This interface is contained in the primary Interop assembly for Smart Tags in the namespace Microsoft.Office. Interop.SmartTag . Therefore, you need to set a reference to the Microsoft Smart Tags 2.0 Type Library, which is located under the COM tab in the Add Reference dialog in Visual Studio.

The functionality of the smart document is embodied in the assembly, but it is related to the document itself through the XML schema. The smart document examines the document schema first and then associates the assembly functionality with the nodes according to the design of your code. As an example, suppose you wanted to create an address label using a smart document that connected to a Microsoft Customer Relationship Management (MSCRM) system on the back end. Your smart document would exist in Word with functionality to search for a company name and then fill in the rest of the label. Listing 8-2 shows a schema that defines just the company name and a single address field for simplicity.

Listing 8-2: A Schema for Address Labels

 <?xml version="1.0" encoding="utf-8" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"     xmlns="urn:schemas-microsoft-com.DataLan.SmartLabelSD"     targetNamespace="urn:schemas-microsoft-com.DataLan.SmartLabelSD"     elementFormDefault="qualified"     attributeFormDefault="unqualified"     id="CompanyName">     <xsd:element name="CompanyName" type="xsd:string"/>     <xsd:element name="AddressBody" type="xsd:string"/> </xsd:schema> 

 

When coupling the assembly functionality to the document, Word calls into the assembly through the ISmartDocument interface using information from the schema. This process begins through a call to SmartDocInitialize , which is the initializing routine for the document. In this method, you can perform any functions that are required before any other processing.

Building Control Sets

Once the document is initialized , most of the subsequent calls to the assembly are used to construct the control set that will appear in the task pane of Word. Frankly, the process is ugly, but it is effective. Essentially the entire user interface is built through late binding with your assembly, providing all the required information Word needs to populate the task pane. This process begins when Word calls SmartDocXmlTypeCount , from which you simply return the number of nodes contained in the XML schema that have controls associated with them. In this example, you will perform a lookup for the company name and return two address lines, which may be pasted into a document. Therefore you return the integer value of 2.

After Word has determined how many nodes it must deal with, it calls the assembly again to determine which nodes will have controls associated with them. This is accomplished by successive calls to the SmartDocXmlTypeName property. Word will call this function the same number of times as the value returned from SmartDocXmlTypeCount . Your job is to return the fully qualified reference to the nodes that will have controls associated with them. The order of the nodes is unimportant in this method; just return one reference for each call as shown in the following code.

 public string get_SmartDocXmlTypeName(int XMLTypeID) {     if (XMLTypeID ==1)     {return "urn:schemas-microsoft-com.DataLan.SmartLabelSD#CompanyName";}     if (XMLTypeID ==2)     {return "urn:schemas-microsoft-com.DataLan.SmartLabelSD#AddressBody";}     else {return null;} } 

Once the node references are passed, Word requests a friendly caption for each control set. This is accomplished by successive calls to the SmartDocXmlTypeCaption property. Because the node references have been given to Word, the subsequent call order is now important. This is because the smart document infrastructure has established a list of nodes for which it will build controls sets. In this example, you will always provide information about the CompanyName node first. The following code shows how to return friendly captions for each control set.

 public string get_SmartDocXmlTypeCaption(int XMLTypeID, int LocaleID) {     if (XMLTypeID ==1){return "Company Name";}     if (XMLTypeID ==2){return "Company Address";}     else {return null;} } 

After the control set is given a caption, the smart document infrastructure queries to find out how many individual controls are associated with each control set. This is done through a call to the ControlCount property. The infrastructure sends in the fully qualified node and expects to receive a number in return. The following code shows an example.

 public int get_ControlCount(string XMLTypeName) {     if(XMLTypeName=="urn:schemas-microsoft-com.DataLan.SmartLabelSD#CompanyName")     {return 3;}     if(XMLTypeName=="urn:schemas-microsoft-com.DataLan.SmartLabelSD#AddressBody")     {return 2;}     else {return 0;} } 

Before the actual control set can be built, the smart document infrastructure needs to assign each individual control a unique identifier across all control sets. This is accomplished by repeated calls to the ControlID property. This property is called for each control that will be part of the smart document. The calls are made by passing in the fully qualified node reference and an index number. The index is simply the count order for a control set and is not unique, so you must create a unique number for it.

In this example, the Company Name control set has three controls and the Company Address control set has two controls. When these control sets are built, the smart document infrastructure calls the ControlID and passes in the ControlIndex and XMLTypeName . Your code must respond with a unique ControlID . Table 8-1 details the unique ControlID returned for each possible combination of arguments.

Table 8-1: ControlID Return Values

CONTROL INDEX	XMLTYPENAME	CONTROLID RETURNED
1	urn:schemas-microsoft-com. DataLan.SmartLabelSD#CompanyName	10
2	urn:schemas-microsoft-com. DataLan.SmartLabelSD#CompanyName	20
3	urn:schemas-microsoft-com. DataLan.SmartLabelSD#CompanyName	30
1	urn:schemas-microsoft-com. DataLan.SmartLabelSD#AddressBody	100
2	urn:schemas-microsoft-com. DataLan.SmartLabelSD#AddressBody	200

Generating the unique values is a simple process of operating a mathematical function on the index. In this case, you are simply multiplying the index by 10 for the first control set and 100 for the second. The following code shows how it is done.

 public int get_ControlID(string XMLTypeName, int ControlIndex) {     if(XMLTypeName=="urn:schemas-microsoft-com.DataLan.SmartLabelSD#CompanyName")     {return 10*ControlIndex;}     if(XMLTypeName=="urn:schemas-microsoft-com.DataLan.SmartLabelSD#AddressBody")     {return 100*ControlIndex;}     else {return 0;} } 

Along with a unique identifier, the controls are also given unique names that can be associated with the document schema. For each ControlID created in the previous step, a name is requested through a call to the ControlNameFromID property. In this example, you simply append the ControlID to the base URI of the schema. The following code shows how it is done.

 public string get_ControlNameFromID(int ControlID) {     return "urn:schemas-microsoft-com.DataLan.SmartLabelSD" + ControlID.ToString(); } 

The next step in building the control sets is to provide a caption for each individual control. These are generated by your code when the ControlCaptionFromID property is called. The smart document infrastructure calls this property for each unique ControlID you defined earlier. Your code then responds with a friendly caption for each control. At this point, you have to decide which ControlID will be for what control. You need to remember this throughout the rest of the project to ensure that the correct control type is rendered with the caption when you create the controls later. The following code shows how to generate the captions.

 public string get_ControlCaptionFromID(int ControlID, string ApplicationName, int LocaleID, string Text, string Xml, object Target) {     if(ControlID==10){return "Search Text";}     //TextBox     if(ControlID==20){return "Search";}          //Button     if(ControlID==30){return "Companies";}       //List     if(ControlID==100){return "Addresses";}      //List     if(ControlID==200){return "Insert";}         //Button     else {return null;} } 

Now that the captions are generated, you have to define the actual control type for each ControlID . This is accomplished by repeated calls to the ControlTypeFromID property. The process is similar to defining captions, except you return an enumerated type of Microsoft.Office.Interop.SmartTag.C_TYPE that defines each control type. Using this enumeration, you can define any basic control you might need. The following code shows how to define the controls.

 public C_TYPE get_ControlTypeFromID(int ControlID, string ApplicationName, int LocaleID) {     if(ControlID==10){return C_TYPE.C_TYPE_TEXTBOX;}     if(ControlID==20){return C_TYPE.C_TYPE_BUTTON;}     if(ControlID==30){return C_TYPE.C_TYPE_LISTBOX;}     if(ControlID==100){return C_TYPE.C_TYPE_TEXTBOX;}     if(ControlID==200){return C_TYPE.C_TYPE_BUTTON;}     else {return 0;} } 

Working with Control Sets

Once the control sets are defined, you may want to populate them with some initial values. These values are the ones that will appear in the controls whenever their related schema section becomes active in the document. At the very least, you will want to assign button captions through the PopulateOther method, but other methods exist in the interface for each type of possible control.

All of the population methods work in essentially the same way. The ControlID is passed in along with several arguments that can be set to populate the appropriate control. For example, C_TYPE_BUTTON controls and C_TYPE_TEXTBOX controls can have a Text argument passed in. For C_TYPE_LISTBOX controls and C_TYPE_COMBO controls, you set the value of a list item by using a 1-based array named List . The following code shows a simple example of setting button captions and list items.

 if(ControlID==20){Text="Lookup";} if(ControlID==100){Text=addressBody;} if(ControlID==200)      {          List[1] = "Item 1";          List[2] = "Item 2";          List[3] = "Item 3";      } 

When the user interacts with controls in the set, they cause events that are handled by methods in the ISmartDocument interface. In keeping with the programming model you have seen throughout this discussion, events are handled in a common location for all controls of the same type. In order to distinguish which control actually caused the event, the event methods receive the ControlID of the firing control. Using conditional programming, you can take action based on the ControlID and the event fired .

Deploying Smart Documents

Smart documents are deployed through the use of a manifest file that specifies every file contained in the solution. A manifest file is an XML document that contains information about the assembly, document schema, and other related documents, such as templates necessary to run your smart document. Office 2003 refers to this set of documents and assemblies as an XML expansion pack. Listing 8-3 shows a complete manifest file that defines an XML expansion pack.

Listing 8-3: A Manifest File

 <?xml version="1.0" encoding="UTF-8" standalone="no"?> <manifest xmlns="http://schemas.microsoft.com/office/xmlexpansionpacks/2003">     <version>1.0</version>     <updateFrequency>20160</updateFrequency>     <uri>urn:schemas-microsoft-com.DataLan.SmartLabel</uri>     <solution>         <solutionID>{1F5E8807-262A-4992-A0D0-05033C41EFC0}</solutionID>         <type>smartDocument</type>         <alias lcid="1033">Smart Label</alias>         <documentSpecific>False</documentSpecific>         <targetApplication>Word.Application.11</targetApplication>         <file>             <type>solutionActionHandler</type>             <version>1.0</version>             <filePath>Address.dll</filePath>             <CLSNAME>Address.SmartLabel</CLSNAME>             <managed/>             <runFromServer>True</runFromServer>         </file>     </solution>     <solution>         <solutionID>schema</solutionID>         <type>schema</type>         <alias lcid="1033">Smart Label</alias>         <file>             <type>schema</type>             <version>1.0</version>             <filePath>SmartLabel.xsd</filePath>         </file>     </solution> </manifest> 

 

The manifest file consists of information that defines the XML expansion pack as a whole and each constituent of the pack. This information is loaded directly from Word and must be completely accurate for the solution to run. Unfortunately, the manifest file must be created by hand, so it is important to understand the various elements that make up the XML structure. Table 8-2 lists the key elements and a brief explanation of each.

Table 8-2: Elements of the Manifest File

ELEMENT	DESCRIPTION
<version>	The version of the solution.
<updateFrequency>	The interval for update checks in minutes.
<uri>	The schema associated with the solution.
<solutionID>	A Globally Unique Identifier (GUID) uniquely identifying the solution.
<type>	The type of solution or file.
<alias>	A friendly name that appears in Office referencing the solution.
<documentSpecific>	If true, this means that this solution is intimately associated with a particular document type and should never be allowed to attach to other documents.
<targetApplication>	The target for the solution.
<filePath>	The complete path to the solution.
<CLSNAME>	The fully qualified name of the assembly.
<managed>	This indicates this smart document solution is .NET based.
<runFromServer>	This determines if a solution is downloaded to the client or run in place on the server.
* A complete listing of every possible element is available in the Office 2003 Smart Document SDK.

Once a proper manifest file is created, you can deploy the contents of the file to a central location. Users may then load the XML expansion pack by selecting Tools Templates and Add-Ins from the Word menu. In the Templates and Add-Ins dialog, the XML Expansion Packs tab allows new packs to be added.

Security Considerations

Even though you correctly create a manifest, schema, and assembly for your XML expansion pack, the solution will not run on a client machine unless it is trusted. Office 2003 has a special security component for managed add-ins called the Visual Studio Tools for Office loader. This loader handles the security for partially trusted code that runs as part of an Office product. The loader works with the .NET security classes to verify the evidence of an assembly before it is allowed to run.

Configuring the client to trust your smart document is similar to configuring SPS to trust a web part, but client configuration poses a separate set of challenges. When you configured code access security on the server, the configuration could be done once centrally for all portal users. Smart documents require the configuration of each client machine that will use the solution. The simplest way to set up configuration for each user to trust your smart documents is to use a strong name for your assembly and digitally sign both the assembly and the manifest.

Generating a strong name for the assembly is identical to generating one for a web part. Digitally signing the assembly, however, requires that you have a digital certificate installed specifically for signing code. If the certificate is installed, you can use the SignCode.exe utility to apply the certificate to your assembly. You should use the same certificate to sign the manifest as well. The Office 2003 Smart Document SDK ships with a tool that allows you to sign the manifest.

If you do not have a digital certificate suitable for signing code, you still have a couple of options with which to configure security. Your first option is to create your own test certificate for signing using the MakeCert.exe tool that ships with Visual Studio. The second option ”and the one I will use in the examples ” involves modifying the security settings to trust your smart documents based on their file location and disabling the XML signature check.

Disabling the signature check for manifest files is a matter of altering a registry key; however, if you have the Office 2003 Smart Document SDK installed, you may use the utility available on the program menu. Configuring trust for the smart documents is accomplished by running one of several wizards also provided by the Office 2003 Smart Document SDK. These wizards allow you to adjust security for the machine as a whole or just for a particular assembly by selecting Start Administrative Tools Microsoft .NET Framework 1.1 Wizards.

Research Library

Using document workspaces through SharePoint Services helps end users assign tasks and assemble documents more easily when those documents are primarily built by teams . However, these collaboration features do not help the individual locate the actual information required to create the document. Smart documents certainly help in this area, but smart documents provide only specific information associated with a document field or section. What is missing from the solution is a general tool that can bring back various types of information. This is where the Research Library comes into play. The Research Library is a general-purpose search tool that can search for information in reference books, line-of-business systems, the Internet, and even SPS. Out of the box, the Research Library provides access to several sources of information like a dictionary and thesaurus.

The Research Library is available in most of the Office 2003 products and is accessible by selecting Tools Research from the menu. Using the Research Library is straightforward regardless of the source you want to search. The end user simply selects a service and types a search string into the task pane. The Research Library then searches the selected service for responses to the search string. The responses vary depending upon the service. The Research Library might display definitions, alternative word choices, Internet hyperlinks , or any other kind of appropriate information. In many cases, you can then insert the information directly into your document. Figure 8-10 shows the Research Library after a typical search.

Figure 8-10: The Research Library

The initial set of services that ship with Office 2003 are only moderately interesting, but the true value of the Research Library lies in the fact that you can extend the library to include SharePoint Services sites or even your own custom services. This is possible because the Research Library architecture is based on web services. The web services communicate with the Research Library through a set of XML documents. As long as the correct documents are exchanged, you can integrate any system with the library. In fact, SPS supports the required XML schemas so that it can be searched using the library.

To search a SharePoint Services site, follow these steps:

1. Open the Research Library in Microsoft Word by selecting Tools Research from the menu.

2. At the bottom of the research pane, click the Research Options link.

3. In the Research Options dialog, click the Add Services button.

4. In the Address box, type the URL http://spsportal/_vti_bin/search.asmx .

5. Click Add.

6. Close the Research Options dialog.

7. In the research pane, select the SPS source from under the All Intranet Sites and Portals section.

8. Type a search string into the Search For box and click the green arrow.

Building a Research Service

Building your own research service allows you to integrate systems directly with the Research Library. To construct a research service, you must build a web service to support registering the service with the library and responding to queries from the library. Both of these activities are accomplished by passing request/ response XML documents between the library and the service.

The request/response paradigm allows you to treat the research pane like a web browser. The difference is that the information is passed as a payload in an XML stream. The schemas defining these streams are all documented in the Research Library SDK. The SDK itself is not required to create or deploy a research service, but the schema references are critical to creating the exact presentation and behavior you want.

Registering a Service

When an end user wants to add a new source to the Research Library, they must provide a URL that refers to a web service capable of registering the source with the library. The Research Library expects the web service to expose a function named Registration . This function must accept a single String argument and return a String result. The registration request is made when the library passes an XML stream to the Registration method. The method then responds with a properly formatted XML stream that defines the new research service. Listing 8-4 shows a typical response from a research service.

Listing 8-4: Registration Response XML Stream

 <?xml version="1.0" encoding="utf-8" ?> <ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response"> <Status>SUCCESS</Status> <Providers> <Provider>     <Message>This is a research library for the CRM system</Message>     <Id>{BC907F3F-D894-42ef-BBC6-C9EE5C0AE46D}</Id>     <Name>CRM</Name>     <QueryPath>http://spsportal/myService/query.asmx</QueryPath>     <RegistrationPath> http://spsportal/myService/registration.asmx     </RegistrationPath>     <AboutPath> http://spsportal/myService/about.asmx </AboutPath>     <Type>SOAP</Type>     <Services>         <Service>             <Id>{351B0D21-9767-4677-9880-361AA722EA1A}</Id>             <Name>Company Lookup</Name>             <Description>Returns address information</Description>             <Copyright></Copyright>             <Display>On</Display>             <Category>BUSINESS_BUSINESS</Category>         </Service>     </Services> </Provider> </Providers> </ProviderUpdate> 

 

The XML response to the Registration method could be completely hard-coded in a single XML document because none of the values in the stream needs to be calculated. In practical applications, the location of the web service is likely to change when moving from development to production, so you typically have to modify the stream at runtime. In most cases, this means changing the path associated with the <QueryPath> , <RegistrationPath> , and <AboutPath> elements. The rest of the elements are generally fixed. Table 8-3 lists the key elements in the registration response stream with a brief description.

Table 8-3: Elements in the Registration Response Stream

ELEMENT	DESCRIPTION
<ProviderUpdate>	The outer envelope of the response. Must refer to the urn:Microsoft.Search.Registration.Response namespace.
<Status>	The result of the registration. May be SUCCESS , ERROR , or ERROR_NOT_COMPATIBLE .
<Providers>	Contains multiple provider registrations.
<Provider>	Contains the detailed registration information for a provider.
<Message>	A message that will appear when the service is registered.
<Id>	A GUID uniquely identifying a provider or service.
<Name>	The name of a provider or service.
<RegistrationPath>	The complete URL to a web service with a Registration method.
<QueryPath>	The complete URL to a web service with a Query method.
<AboutPath>	The complete URL to "about" information.
<Type>	The communication protocol. Always set to SOAP .
<Services>	Contains multiple service descriptions.
<Service>	Contains detailed information about a service.
<Description>	A description of the service.
<Copyright>	A copyright message.
<Display>	Determines if service is visible. May be ON , OFF , or HIDDEN .
<Category>	The category under which the service will be listed.
* A complete listing of every possible element is available in the Research SDK.

Responding to Queries

The registration response stream must specify a complete URL to a web service that contains a Query method. Just like the Registration method, the Query method accepts an XML stream as a String argument and returns an XML stream as a String . The Research Library packages the query in the XML stream along with metadata about the request. When you write the code for the Query method, you extract the query text from the <QueryText> element of the XML stream and use it to process the search request.

The basic approach to processing the incoming XML query stream is to load it into an XmlDocument object. Once the query stream is loaded, you can use the object to select out the nodes that you need to process the query. Listing 8-5 is a partial listing focused on how to access the <QueryText> node using VB.NET.

Listing 8-5: Processing the XML Query Stream

 <WebMethod()>Public Function Query(ByVal queryXml As String) As String     'Load query into new document     Dim objXMLRequest As New XmlDocument     objXMLRequest.LoadXml(queryXml)     'Prepare for parsing     Dim objRequestManager As New XmlNamespaceManager(objXMLRequest.NameTable)     objRequestManager.AddNamespace("ns", "urn:Microsoft.Search.Query")     'Get query string     Dim strQuery = _     objXMLRequest.SelectSingleNode("//ns:QueryText",objRequestManager).InnerText End Function 

 

Depending upon how you design your service, you may be interested in several other nodes available in the query stream. The <Name> element contains the name of the application making the request. This is important if you must customize your response to different Office products. The <StartAt> element specifies which record to begin with in the result set, and the <Count> element specifies how many records to return with the result set. These are important if you are paging your results through multiple responses.

Once you have completed your processing, you must return a result stream to the client in accordance with the expected XML schema. The Research Library recognizes a general schema that forms an envelope for the result set and specific schemas to define the query results. The following code shows a typical envelope for results.

 <?xml version="1.0" encoding="utf-8" ?> <ResponsePacket revision="1" xmlns="urn:Microsoft.Search.Response">     <Response domain="{351B0D21-9767-4677-9880-361AA722EA1A}">         <Range>         </Range>         <Status>SUCCESS</Status>     </Response> </ResponsePacket> 

The response envelope contains the metadata information the Research Library needs to properly handle the returned results. Most importantly, the <Response> element must contain a domain attribute that is identical to the <Id> of the service that was originally registered. The actual query results are then built between the <Range> and </Range> tags.

When the results are written into the stream, the format must be in compliance with the urn:Microsoft.Search.Response.Content schema. Generally, the process involves creating a new XmlTextWriter object and painstakingly creating the results one element at a time. The schema, however, is reasonably flexible and allows you to include things such as images, hyperlinks, and Text, Copy, and Insert buttons . Listing 8-6 shows a typical result stream returning a single record.

Listing 8-6: A Query Response Stream

 <?xml version="1.0" encoding="utf-8"?> <ResponsePacket revision="1" xmlns="urn:Microsoft.Search.Response"> <Response domain="{351B0D21-9767-4677-9880-361AA722EA1A}"> <Range>     <StartAt>1</StartAt>     <Count>1</Count>     <TotalAvailable>1</TotalAvailable>     <Results>         <Content xmlns="urn:Microsoft.Search.Response.Content">         <Heading collapsible="true" collapsed="true">             <Text>DataLan Corporation</Text>             <P>             <Char>170 Hamilton Avenue</Char>             <Actions><Insert/><Copy/></Actions>             </P>             <P>             <Char>White Plains, NY 10601</Char>             <Actions><Insert/><Copy/></Actions>             </P>         </Heading>         </Content>     </Results> </Range> <Status>SUCCESS</Status> </Response> </ResponsePacket>