Show All

# Frequently Asked Questions

Troubleshooting

My Registration or Query method doesn't work.

The following checklist includes the most common causes of an empty response packet or an error. For more information, see Building a Research Web Service.

- Does the WebService attribute reference the Microsoft.Search namespace?
- Does the WebMethod attribute of the Registration method reference the Microsoft.Search.Registration.Request namespace?
- Does the WebMethod attribute of the Query method reference the Microsoft.Search.Query namespace?
- Does the single string parameter of the Registration method (or the Discovery method) have the case-sensitive name `registrationXml`?
- Does the single string parameter of the Query method have the case-sensitive name `queryXml`?
- Does the response packet include the required Status element, and a case-sensitive value from the appropriate enumeration? For a list of acceptable values, see Enumerations Reference.
- Has an unhandled exception occurred in your code? Your code should trap exceptions and return a properly-formatted XML error response.
- Does the XML generated by your service contain a syntax error? You can validate the response packet, or save it to a file for analysis.

How can I improve research service performance?

Since the registration response rarely changes, you can improve the performance of the registration response by taking advantage of the caching technology available in the Microsoft® .NET Framework. Supply a value in seconds for the CacheDuration property of the appropriate WebMethod attribute. When you expect queries to vary widely, there is no benefit in caching individual query responses. The following example caches the registration response for one hour:

    <WebMethod(CacheDuration=3600)> _
    Public Function Registration(registrationXml As String) As String

After I test or query my research service several times, it stops working.

You may be encountering the hard-coded limit of ten (10) HTTP connections in Microsoft Internet Information Services (IIS) on non-server editions of Microsoft Windows®, such as Microsoft Windows XP Professional Edition. You can clear these connections by stopping and restarting IIS from Internet Services Manager, or by typing iisreset at a command prompt.

I'm not using Microsoft Visual Studio® .NET and I'm having trouble with my SOAP response packets.

You must encode the string response from the research service's Web methods by using HTMLEncode or a similar method. In the following SOAP packet format example, the "string" value represents the XML that must be encoded.

    HTTP/1.1 200 OK
    Content-Type: text/xml; charset=utf-8
    Content-Length: length

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <RegistrationResponse xmlns="urn:Microsoft.Search">
                <RegistrationResult>string</RegistrationResult>
            </RegistrationResponse>
        </soap:Body>
    </soap:Envelope>

My service is having intermittent trouble when it calls COM+ components.

To avoid problems caused by a crash or a hang in the COM+ component, you may want to create a background thread to interact with the component. Using a background thread allows you to terminate the thread after a time-out and to return a friendly error message to the Research task pane.

Building Research Services

Do I need Microsoft Visual Studio .NET to build research services?

No, you do not need Microsoft Visual Studio .NET to build research services; however, Visual Studio .NET greatly simplifies the process of building an XML Web service. You only need a development environment or tool that creates applications capable of sending and receiving SOAP messages; for example, Microsoft Visual Basic® 6.0 and the Microsoft SOAP Toolkit. However, at the minimum, you need the Microsoft .NET Framework SDK (which includes the Visual Basic .NET and C# compilers) to build and run the source code samples included with this SDK.

I see a Web method named Status() in some of the samples. Can I implement a Status method in my research service?

No, the Status method is for internal use only. The Research task pane itself never calls the Status method, so implementing this method provides no benefit.

Why are the XML response packets returned by research services wrapped in a string?

If a Web service uses a complex data structure that is subject to change or revision, each time the structure changes, the developer would have to create a new interface for all clients that use the service, and revise the client code that handles the response. For research services in particular, there are many optional elements and sections that support arbitrary namespaces. Wrapping the response packet in a string spares developers the chore of updating client applications every time the Web service is updated.

Registering Research Services

How can a provider register multiple services hosted on different servers by using a single URL?

In this scenario, it is not possible to register all of an organization's services under a single provider. Each distinct QueryPath requires a distinct provider and RegistrationPath. There is, however, one way to use a single URL to register multiple providers. By building a discovery server, which returns a list of providers and their registration URLs to Office, these providers and their services can be automatically installed or advertised to users. In fact, you can specify up to five discovery servers with different URLs. For more information, see Configuring Service Discovery.

How can I make my service the default that appears in the list in the Research task pane?

It is not possible to designate a service as the default. When the Research task pane opens, by default, a drop-down list displays the first available category of services. After the first time the task pane is opened, until it is closed or reset (for example, by changes in the Research Options dialog box), the Research task pane uses the most recently queried service as the default in its drop-down list.

Querying Research Services

Is the Research task pane itself programmable?

No, this first version of the Research task pane does not expose programmability features for automation. Although you can use the WordBasic.ResearchLookup command to launch a query from Microsoft Word 2003, the use of WordBasic is not encouraged. This method queries on the text at the insertion point in the document. It is not possible to select the services to query. In addition to the WordBasic method, you can:

- Open the Research task pane (without executing a query) by using the following code:

      	Word.Application.TaskPanes(wdTaskPaneResearch).Visible = True

- Use the SendKeys method to send the keyboard shortcut that launches a query. However, this approach is not reliable since the user can modify the keyboard shortcut.

Can I use cookies in a research service?

Yes, you can use cookies in a research service, but only if the user's Web browser is Microsoft Internet Explorer. This is because the Research task pane looks for cookies in the specific folder where Internet Explorer saves them. The Research task pane can:

- Read cookies written by the browser.
- Write cookies that are recognized by the browser.
- Use both session cookies and persistent cookies.

I'm having trouble with the Range and Count elements when the user pages through my query results.

The Range element of the Microsoft.Search.Response namespace contains the StartAt, Count, and TotalAvailable elements to give the Research task pane information about the number of query results. Count represents the desired "page size," or number of results to display at one time in the pane. The Research task pane displays these values in a message that indicates the user's position within the query results.

- TotalAvailable If this element is absent, the Research task pane assumes that there are no more results.
- Count Normally the Research task pane displays:

      StartAt "-" (StartAt + Count - 1) " of " TotalAvailable

  In cases such as the end of the results, where `(StartAt + Count - 1) > TotalAvailable`, the Research task pane displays:

      StartAt "-" Min((StartAt + Count - 1), TotalAvailable) " of " TotalAvailable

  Thus you do not have to worry about the message in the case where `(StartAt + Count - 1) > TotalAvailable`.

The Range element of the Microsoft.Search.Query namespace returns the value of these elements from the previous response to the service on the next requery, so the service does not need to remember its position in the list of query results.

How can I create a drop-down list of actions for a term in my query results, similar to the Copy/Insert/Look up list provided by the Thesaurus service?

Use the Tabular element provided in the Microsoft.Search.Response.Content namespace. The following example generates the drop-down action list for the word "chocolate" appearing in the query results. (Note that in this sample, the Microsoft.Search.Response.Content namespace is registered at the document level with the prefix "c".)

    <c:Content ...  >
        <c:Tabular>
            <c:Record>
                <c:Name>chocolate</c:Name>
                <c:Actions>
                    <c:Insert/>
                    <c:Copy/>
                    <c:NewQuery query="chocolate"/>
                </c:Actions>
            </c:Record>
        </c:Tabular>
    </c:Content>

My query results wrap to a new line where I don't want them to.

The Microsoft.Search.Response.Content namespace provides the Line element to allow you to combine multiple elements without a line break after each element. However, due to the limited width of the Research task pane, you may still need to wrap lines within the Line element.

The records in my Tabular control run off the side of the screen.

The Research task pane does not wrap lines for the contents of the Tabular control.

Using Forms

When a user submits a requery from the form provided by my research service, the ServiceParameters element of the requery request doesn't contain the values of some of the form controls.

The ServiceParameters element from the Microsoft.Search.Office.ServiceParameters namespace contains only the values of form elements whose values can change. For example, it reports the values of drop-down lists and of text boxes. However it does not report the values of controls with static values, such as buttons or hyperlinks. Therefore, for example, if you display a series of hyperlinks with the `action="requery"` attribute, the Action element reports the unique ID of the hyperlink selected by the user, but the Parameters section does not include an element for the selected hyperlink because of its static value.

©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp