Show All

# Handling Queries

The Query method is central to a research service. The Research task pane submits the user's query to the Query method, along with information about the Research task pane, the Microsoft® Office 2003 host application, and other user settings. The Query method responds with the query results, which may consist of simple hyperlinks or richly formatted content, and may be enhanced with form controls and actions.

## Query Web Method

The Query method receives an incoming string value from the Research task pane in the form of an XML document that conforms to the Microsoft.Search.Query family of schemas, and returns a string value containing the query results (or an alternate message) in the form of an XML document that conforms to the Microsoft.Search.Response family of schemas.

Query method prototype

Visual Basic .Net

    <WebMethod(Description="Query Web Method")> _
    Public Function Query(queryXml As String) As String

C#

    [WebMethod(Description="Query Web Method")]
    public string Query(string queryXml)

Important The string input parameter for the Query Web method must be named `queryXml`. This name is also case-sensitive. If you find that the incoming argument is empty while you are testing a research Web service, check the name and case of the parameter in the function header.

## Format of the Query Request and Response

Format of the query request

The query request and response can contain the following elements and attributes. Optional attributes that are not currently used have been omitted.

    <QueryPacket xmlns="urn:Microsoft.Search.Query" revision="" build="">
        <Query domain="">
            <QueryId/>
            <OriginatorId/>
            <SupportedFormats>
                <Format  revision="" build="" />
                <Any/>
            </SupportedFormats>
            <Context>
                <QueryText language="" type="" />
                <LanguagePreference/>
                <Requery>
                    <RequeryContext>
                        <Any/> *
                    </RequeryContext>
                    <Any/>
                </Requery>
                <OriginatorContext>
                    <Any/>
                </OriginatorContext>
                <Any/>
            </Context>
            <Range id="">
                <ResultType/>
                <StartAt/>
                <Count/>
                <Any/>
            </Range>
            <Any/> **
        </Query>
        <Any/>
    </QueryPacket>

* Additional query request information from the Microsoft.Search.ServiceParameters namespace takes the place of the indicated Any element.

** Additional query request information from the Microsoft.Search.Query.Office.Context and Microsoft.Search.Query.Office.Keywords namespaces takes the place of the indicated Any element.

For more information, see Microsoft.Search.Query Schema Documentation. For enumerated constants defined in the Microsoft.Search.Query schema, see Enumerations Reference.

Format of the query response

    <ResponsePacket xmlns="urn:Microsoft.Search.Response"
        revision=""
        build=""
        providerRevision="">
        <Response domain="">
            <QueryId/>
            <Copyright/>
            <OriginatorContext>
                <Any/>
            </OriginatorContext>
            <RequeryContext>
                <Any/>
            </RequeryContext>
            <Range id="">
                <ResultType/>
                <StartAt/>
                <Count/>
                <TotalAvailable/>
                <Results>
                    <Any/> *
                </Results>
                <Any/>
            </Range>
            <Status/>
            <DebugErrorMessage/>
            <Any/>
        </Response>
        <Any/>
    </ResponsePacket>

* Additional query response information from the Microsoft.Search.Response.Document, Microsoft.Search.Response.Content, and Microsoft.Search.Response.Form namespaces takes the place of the indicated Any element.

Note The preceding list does not include the MustDisplayCount element, which is not used.

For more information, see Microsoft.Search.Response Schema Documentation. For enumerated constants defined in the Microsoft.Search.Response schema and related schemas, see Enumerations Reference.

## Elements of the Query Request and Response

The following tables provide information about some of the more significant elements and attributes in the query request and response.

Common elements in the query request and response

Certain query elements are passed back and forth between the Research task pane and the research Web service that it is querying.

Element | Description
--- | ---
domain attribute | On the Query element, identifies the service to query; on the Response element, identifies the service providing the results.
QueryId | Identifies the query with a globally unique identifier (GUID) initially generated by the Research task pane.
RequeryContext | Returned by the research service if the user submits a requery, then returned by the Research task pane to the server on each subsequent request, to assist in maintaining state.
Range | Contains elements such as StartAt and Count that support paging through results. In the query response, also contains the Results element, and provides (through the id attribute) for circumstances where a single query may return more than one Results node.

Unique elements in the query request

The QueryText element is the most important element in the query request because it transmits the user's query.

Element | Description
--- | ---
QueryPacket | Must reference the Microsoft.Search.Query namespace.
Query | Uses the domain attribute to indicate which of several services from the same provider to query.
OriginatorId | Identifies Microsoft Office 2003. (Always the same GUID.)
SupportedFormats | Lists the three namespaces that the Research task pane currently accepts in the Results element of the query response: Microsoft.Search.Response.Document, Microsoft.Search.Response.Content, and Microsoft.Search.Response.Form.
QueryText | Contains the text of the user's query. This element's language attribute, along with the subsequent LanguagePreference element, may also help determine the results to return.

Unique elements in the query response

The Results element is the most important element in the query response because it transmits the results of the user's query. Note that the Status element is required and that without it the Research task pane does not display the results received.

Element | Description
--- | ---
ResponsePacket | Must reference the Microsoft.Search.Response namespace.
Response | Uses the domain attribute to indicate which of several services from the same provider is responding.
Results | Contains the results of the user's query, including markup to specify how the Research task pane should render the data.
Status | Indicates the success or failure of the query. Typically, SUCCESS. For more information, see Enumerations Reference.

## Other Namespaces Used in the Query Request

Query family of namespaces

In addition to the QueryText element that contains the text of the user's query, and the other elements described earlier in this topic, the query request may include additional information in the following elements and attributes. These elements appear in the query request packet at the locations indicated earlier in the section "Format of the Query request."

- The OfficeContext element from the Microsoft.Search.Query.Office.Context namespace contains the user's language settings, preferences (such as parental control), and application information (such as the name and version of the Microsoft Office 2003 host application). The ServiceData element contains the value of the SourceData registry setting, created when the service was registered, which passes arbitrary information set by the developer with each query to the service.
- The Keywords element from the Microsoft.Search.Query.Office.Keywords namespace contains the list of words in the query phrase, and the results of stemming and word-breaking of the query phrase, if the components required for these operations are present on the client computer and available to the Research task pane. (The availability of stemming and word-breaking components depends on the language and the version of Microsoft Windows®. For example, when you are using the English language with Microsoft Windows 2000, neither stemming nor word-breaking are used; when you are using English with Microsoft Windows XP, only word-breaking is used.)
- The ServiceParameters element from the Microsoft.Search.Office.ServiceParameters namespace contains the values of form elements in cases where the previous query response displayed a form in the Research task pane along with query results. This element appears only in a requery.

Microsoft.Search.Query.Office.Context namespace

The OfficeContext element from the Microsoft.Search.Query.Office.Context namespace contains the user's language settings, preferences (such as parental control), and application information (such as the name and version of the Microsoft Office 2003 host application). It also sends the SourceData registry value to the service, if this registry setting is present, in the child Data element of the ServiceData element. The following XML fragment shows the OfficeContext element sent to the server along with a typical query issued from the Research task pane in Microsoft Office Word 2003.

    <OfficeContext xmlns='urn:Microsoft.Search.Query.Office.Context'
        revision='1'>
        <UserPreferences>
            <ParentalControl>false</ParentalControl>
        </UserPreferences>
        <ServiceData></ServiceData>
        <ApplicationContext>
            <Name>Microsoft Office Word</Name>
            <Version>(11.0.5606)</Version>
            <SystemInformation>
                <SkuLanguage>en-us</SkuLanguage>
                <LanguagePack>en-us</LanguagePack>
                <InterfaceLanguage>en-us</InterfaceLanguage>
                <Location>US</Location>
            </SystemInformation>
        </ApplicationContext>
        <QueryLanguage>en-us</QueryLanguage>
        <KeyboardLanguage>en-us</KeyboardLanguage>
    </OfficeContext>

The following table lists the possible values for the Name element of the ApplicationContext section, depending on which application is hosting the Research task pane. Note that the values returned by Microsoft Internet Explorer and Microsoft Office Excel 2003 do not match the format returned by most of the other Office applications.

Host Application | Value of Name Element
--- | ---
Microsoft Internet Explorer | Microsoft Office
Microsoft Office Excel 2003 | Microsoft Excel
Microsoft Office OneNote 2003 | Microsoft Office OneNote
Microsoft Office Outlook 2003 | Microsoft Office Outlook
Microsoft Office PowerPoint 2003 | Microsoft Office PowerPoint
Microsoft Office Publisher 2003 | Microsoft Office Publisher
Microsoft Office Visio 2003 | Microsoft Office Visio
Microsoft Office Word 2003 | Microsoft Office Word

For more information, see Microsoft.Search.Query.Office.Context Schema Documentation.

Microsoft.Search.Query.Office.Keywords namespace

The Keywords element from the Microsoft.Search.Query.Office.Keywords namespace contains the list of words in the query phrase, and the results of stemming and word-breaking of the query phrase, if the components required for these operations are present on the client computer and available to the Research task pane. (The availability of stemming and word-breaking components depends on the language and the version of Microsoft Windows®. For example, when you are using the English language with Microsoft Windows 2000, neither stemming nor word-breaking are used; when you are using English with Microsoft Windows XP, only word-breaking is used.) The Keywords section analyzes only the first 255 characters of the user's query. In cases where the user's entire query phrase does not produce any query results, you may choose to have the research Web service return results for selected keywords instead. The following XML fragment shows the Keywords element sent to the server when the user enters the query phrase, "He is calm and level-headed" using English with Microsoft Windows XP.

    <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
        revision='1'>
        <QueryText>He is calm and level-headed.</QueryText>
        <Keyword>
            <Word>He</Word>
        </Keyword>
        <Keyword>
            <Word>is</Word>
        </Keyword>
        <Keyword>
            <Word>calm</Word>
        </Keyword>
        <Keyword>
            <Word>and</Word>
        </Keyword>
        <StartAltPhrase/>
            <Keyword>
                <Word>level</Word>
            </Keyword>
            <Keyword>
                <Word>headed</Word>
            </Keyword>
        <StartAltPhrase/>
            <Keyword>
                <Word>level-headed</Word>
            </Keyword>
        <EndAltPhrase/>
        <EndOfSentence/>
    </Keywords>

For more information, see Microsoft.Search.Query.Office.Keywords Schema Documentation.

Microsoft.Search.Office.ServiceParameters namespace

The ServiceParameters element from the Microsoft.Search.Office.ServiceParameters namespace contains the values of form elements, in cases where the previous query response displayed a form in the Research task pane along with query results. The following XML fragment shows the portion of the initial query response from the Email Sample that generates a form. This fragment uses the Microsoft.Search.Response.Form namespace (discussed later in this topic) to display a form containing two drop-down lists (named SortProperty and SortOrder) that allow the user to select a sort field and sort order for the query results. When the user makes a selection in either list, the Research task pane submits a requery and returns the form values in the ServiceParameters element, as shown in the following XML fragment. (Note that in this sample, the Microsoft.Search.Response.Form namespace is registered at the document level with the prefix "f".)

    <Results>
        <f:Form revision='1'>
            <f:Listbox dropdown='true' id='SortProperty'
                action='requery'>
                <f:Text>Sort by: </f:Text>
                <f:Option selected='true' id='CompleteName'>
                    <f:Text>Full name</f:Text>
                </f:Option>
                <f:Option selected='false' id='LastName'>
                    <f:Text>Last name</f:Text>
                </f:Option>
                <f:Option selected='false' id='FirstName'>
                    <f:Text>First name</f:Text>
                </f:Option>
            </f:Listbox>
            <f:Listbox dropdown='true' id='SortOrder' action='requery'>
                <f:Text>Sort order: </f:Text>
                <f:Option selected='true' id='Ascending'>
                    <f:Text>Ascending</f:Text>
                </f:Option>
                <f:Option selected='false' id='Descending'>
                    <f:Text>Descending</f:Text>
                </f:Option>
            </f:Listbox>
        </f:Form>
        ...
    </Results>

The following XML fragment shows the form values from the requery sent back to the server when the user makes a selection in the form elements described in the preceding request. This fragment uses the Microsoft.Search.Office.ServiceParameters namespace to identify the form element that triggered the requery (in the Action element) and the values of the various form elements (in the Parameters section, where an element is created with the ID value of each form element as its name, and the value of each form element as its text).

    <Context>
        ...
        <Requery>
            <ServiceParameters
                xmlns='urn:Microsoft.Search.Office.ServiceParameters'>
                <Action>SortProperty</Action>
                <Parameters>
                    <SortProperty>LastName</SortProperty>
                    <SortOrder>Ascending</SortOrder>
                </Parameters>
            </ServiceParameters>
        </Requery>
    </Context>

Note The Parameters list of the ServiceParameters section 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.

For more information, see Microsoft.Search.Office.ServiceParameters Schema Documentation.

## Other Namespaces Used in the Query Response

Response family of namespaces

Within the Results element, the query response uses elements and attributes from up to three supporting namespaces to display and format the query results, as follows. These elements appear in the query response packet at the location of the placeholder Any element within the Results element.

- The Document element from the Microsoft.Search.Response.Document namespace displays query results as a simple URL, with a title and description, in the familiar format used by many Internet search engines. A list of URLs requires a series of Document elements.
- The Content element from the Microsoft.Search.Response.Content namespace supports a much richer layout and formatting of the query results. This includes support for expandable headings, paragraphs, and images, as well as built-in and custom actions.
- The Form element from the Microsoft.Search.Response.Form namespce uses typical Web form elements to gather additional query or layout criteria or other information from the user.

The query response can contain any combination of Document and Content elements, in any order; however, only one Form element is supported, and the Research task pane always displays a Form at the top of (that is, as the first element) the query results.

As you can see by examining the Microsoft.Search.Response.xsd schema, the query response is independent of the supported formats for query results. This structure facilitates the future extensibility of Research task pane options, beyond the three results namespaces currently supported.

Microsoft.Search.Response.Document namespace

The Document element from the Microsoft.Search.Response.Document namespace displays query results as a simple list of URLs, with a title and description and optional multimedia elements, in the familiar format used by many Internet search engines. The following XML fragment shows a single Document element with an accompanying image.

     <Results>
        <Document xmlns="urn:Microsoft.Search.Response.Document">
            <Title>Microsoft Web Site</Title>
            <Action>
                <LinkUrl fileExt="htm">http://www.microsoft.com</LinkUrl>
            </Action>
            <DisplayUrl>http://www.microsoft.com</DisplayUrl>
            <Description>
                The home page for the Microsoft Corporation.
            </Description>
            <Media type="IMAGE">
                <SrcUrl>
                    http://www.microsoft.com/homepage/gif/
                        bnr-microsoft.gif
                </SrcUrl>
                <AltText>Microsoft logo</AltText>
            </Media>
        </Document>
    </Results>

For more information, see Microsoft.Search.Response.Document Schema Documentation. For enumerated constants defined in the Microsoft.Search.Response.Document schema, see Enumerations Reference.

Microsoft.Search.Response.Content namespace

The Content element from the Microsoft.Search.Response.Content namespace supports much richer layout and formatting of the query results, with support for headings, paragraphs, and images, as well as built-in and custom actions. The following table shows the more commonly used elements in this namespace.

Element | Description
--- | ---
P | Paragraph of text.
Char | Formatted string of text. Always contained within another element from the Content namespace, Char provides a choice of font, as well as the bold, italic, smallcaps, underline, light, superscript, and subscript attributes.
Tabular | Table of name/value combinations. The Tabular element must contain one or more Record elements, each with a Name and a Value element of its own.
Image | Path to an image to be displayed in the Research task pane as a part of the result.
Heading | Heading for a section that can be expanded to display more information.
Hyperlink | Typical link.
HorizontalRule | Separator line.
Line | Element used to force controls to display on the same line when possible.
NewQuery | Hyperlink that, when clicked, issues a new call to the Query method of the research service. The term to be queried is specified as an attribute of the NewQuery element.

The following XML fragment shows the formatted output of a simple test research Web service, including a heading, a separator line, and formatted text within paragraphs.

    <Results>
        <Content xmlns="urn:Microsoft.Search.Response.Content">
            <P>Hello world!</P>
            <HorizontalRule />
            <Heading>
                <Text>Features of the Research Task Pane</Text>
            </Heading>
            <P>Return a list of links.</P>
            <P>Return richly formatted content.</P>
            <P>Display a <Char bold="true">form</Char>.</P>
        </Content>
    </Results>

For additional examples of the use of the Microsoft.Search.Response.Content namespace, review the sample research services included with this SDK. For an example of the Tabular control, see "Adding Simple Actions" in Adding Actions to Query Results.

For more information, see Microsoft.Search.Response.Content Schema Documentation and Adding Actions to Query Results. For enumerated constants defined in the Microsoft.Search.Response.Content schema, see Enumerations Reference.

Microsoft.Search.Response.Form namespace

The Form element from the Microsoft.Search.Response.Form namespace uses typical Web form elements to gather additional query or layout criteria or other information from the user. The following XML fragment shows the portion of the initial query response from the Email Sample that generates a form containing two drop-down lists (named SortProperty and SortOrder) that allow the user to select a sort field and sort order for the query results. When the user makes a selection in either list, the Research task pane submits a requery and returns the form values in the ServiceParameters element, as shown earlier in this topic. (Note that in this sample the Microsoft.Search.Response.Form namespace is registered at the document level with the prefix "f".)

    <Results>
        <f:Form revision='1'>
            <f:Listbox dropdown='true' id='SortProperty'
                action='requery'>
                <f:Text>Sort by: </f:Text>
                <f:Option selected='true' id='CompleteName'>
                    <f:Text>Full name</f:Text>
                </f:Option>
                <f:Option selected='false' id='LastName'>
                    <f:Text>Last name</f:Text>
                </f:Option>
                <f:Option selected='false' id='FirstName'>
                    <f:Text>First name</f:Text>
                </f:Option>
            </f:Listbox>
            <f:Listbox dropdown='true' id='SortOrder' action='requery'>
                <f:Text>Sort order: </f:Text>
                <f:Option selected='true' id='Ascending'>
                    <f:Text>Ascending</f:Text>
                </f:Option>
                <f:Option selected='false' id='Descending'>
                    <f:Text>Descending</f:Text>
                </f:Option>
            </f:Listbox>
        </f:Form>
        ...
    </Results>

You can also use a form in the Research task pane to gather user credentials for a service that requires authentication. For an example, see "Implementing ASP.NET Forms Authentication" in Authenticating Research Service Users.

For more information, see Microsoft.Search.Response.Form Schema Documentation. For enumerated constants defined in the Microsoft.Search.Response.Form schema, see Enumerations Reference.

## Additional Implementation Details

Including custom data with every query request

When a provider registers a service on the user's computer, the provider has the option of storing an arbitrary string of data that the Research task pane returns to the service with every subsequent query request from that user on that computer. This feature uses the following schema elements and settings:

- In the registration response, the provider initially sends this arbitrary string of data in the Data element. For more information, see Handling Registration Requests.
- The Research task pane stores the string of data in the SourceData registry setting for the service. For more information, see Service Registry Settings.
- In every query request, the Research task pane returns the string of data to the service within the OfficeContext element, in the Data element in the ServiceData section. For more information, see "Microsoft.Search.Query.Office.Context" earlier in this topic.

Querying multiple services from the same provider

When a user directs a query to multiple services offered by the same provider, the query request contains multiple Query elements in which the domain attribute identifies the target service by its GUID ID value. The research service must build a response that contains an equal number of Response elements, which likewise identify the responding service through the domain attribute.

Requerying

A requery can be launched from a Form control that appears with the results of a previous query, or from a "Next" link when the query results span multiple pages. The requery causes an "update in place" of the Research task pane; that is, only the content that changes is replaced with new results. In most other respects, a requery is very similar to any other query; however, additional data is available to the research Web service in the RequeryContext element to help the service maintain state information. The RequeryContext element is like a lightweight cookie that the server can include in the query response after the first requery. The client then passes the same element and data back to the server with each subsequent requery.

Parental control and filtering query results

When parental control is enabled from the Parental Control button of the Research Options dialog box, the user cannot query services that do not support parental control (that is, the filtering of query results).

When the value of ParentalControl in the query request is true (indicating that the user has requested content filtering), and the service identified itself at registration as supporting parental control, the service is expected to filter inappropriate content out of the query results before returning the results to the user. The ParentalControl query request element is defined in the Microsoft.Search.Query.Office.Context namespace.

Recognizing the limitations of the Research task pane user interface

Although the Research task pane is similar to an embedded browser, it does not have the flexibility of a full-fledged browser. You cannot set the background color, you have limited control over the layout of text and images, and you cannot add client-side script. You also have to learn to make the most of limited screen real estate. You are dealing with an area that is typically 100-200 pixels wide. Therefore, you have to economize in choosing the information you present and its layout and formatting. In some ways, you can compare this to formatting information for a Pocket PC, as the two user interfaces share a similar form factor.

Updating and removing services

The providerRevision attribute of the top-level ResponsePacket element in the query response can be used to prompt the user to update (or remove) the service. For more information, see Updating and Removing Services.

## Walkthrough: Sample Query Request, Response, and Code

Sample query request

The following sample query request submits the query "test" to a simple research service. The query includes elements from the Microsoft.Search.Query.Office.Context and the Microsoft.Search.Query.Office.Keywords namespaces. Since the user is not submitting a form in this case, the query request does not include elements from the Microsoft.Search.Office.ServiceParameters namespace. The fixed OriginatorID value identifies Microsoft Office 2003.

    <QueryPacket xmlns='urn:Microsoft.Search.Query'
        revision='1'
        build='(11.0.5606)' >
        <Query domain='{41F27485-961F-4EA1-82F1-7623E55DE293}'>
            <QueryId>
                {D0FF4E60-85A5-40CF-B067-8757FB063FB1}
            </QueryId>
            <OriginatorId>
                {F6FF7BE0-F39C-4ddc-A7D0-09A4C6C647A5}
            </OriginatorId>
            <SupportedFormats>
                <Format revision='1'>
                    urn:Microsoft.Search.Response.Document:Document
                </Format>
                <Format revision='1'>
                    urn:Microsoft.Search.Response.Content:Content
                </Format>
                <Format revision='1'>
                    urn:Microsoft.Search.Response.Form:Form
                </Format>
            </SupportedFormats>
            <Context>
                <QueryText type='STRING' language='en-us' >
                    test
                </QueryText>
                <LanguagePreference>en-us</LanguagePreference>
                <Requery></Requery>
            </Context>
            <Range id='result'></Range>
            <OfficeContext
                xmlns='urn:Microsoft.Search.Query.Office.Context'
                revision='1'>
                <UserPreferences>
                    <ParentalControl>false</ParentalControl>
                </UserPreferences>
                <ServiceData></ServiceData>
                <ApplicationContext>
                    <Name>Microsoft Office Word</Name>
                    <Version>(11.0.5606)</Version>
                    <SystemInformation>
                        <SkuLanguage>en-us</SkuLanguage>
                        <LanguagePack>en-us</LanguagePack>
                        <InterfaceLanguage>en-us</InterfaceLanguage>
                        <Location>US</Location>
                    </SystemInformation>
                </ApplicationContext>
                <QueryLanguage>en-us</QueryLanguage>
                <KeyboardLanguage>en-us</KeyboardLanguage>
            </OfficeContext>
            <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
                revision='1'>
                <QueryText>test</QueryText>
                <Keyword>
                    <Word>test</Word>
                </Keyword>
            </Keywords>
        </Query>
    </QueryPacket>

Sample query response

Important The query response packet that you build must reference the Microsoft.Search.Response namespace on the response's top-level ResponsePacket element, as shown in the following example.

The following sample query response comes from a fictititious "Hello World Test Research Services" provider that provides a single service named "Hello World Test Research Service in VB." The response contains a hyperlink that uses elements from the Microsoft.Search.Response.Document namespace, and formatted content that uses elements from the Microsoft.Search.Response.Content namespace.

    <?xml version="1.0"?>
    <ResponsePacket providerRevision="1"
        xmlns="urn:Microsoft.Search.Response">
        <Response domain="{41F27485-961F-4EA1-82F1-7623E55DE293}">
            <QueryID>{7333D51C-1636-4BA5-AD04-EE7FB60145F4}</QueryID>
            <Range>
                <Results>
                    <Document xmlns=
                        "urn:Microsoft.Search.Response.Document">
                        <Title>Microsoft Web Site</Title>
                        <Action>
                            <LinkUrl fileExt="htm">
                                http://www.microsoft.com
                            </LinkUrl>
                        </Action>
                        <DisplayUrl>http://www.microsoft.com</DisplayUrl>
                        <Description>
                            The home page for the Microsoft Corporation.
                        </Description>
                    </Document>
                    <Content xmlns=
                        "urn:Microsoft.Search.Response.Content">
                        <HorizontalRule />
                        <P>Hello world!</P>
                        <HorizontalRule />
                        <Heading>
                            <Text>
                                Features of the Research Task Pane
                            </Text>
                        </Heading>
                        <P>Return a list of links.</P>
                        <P>Return richly formatted content.</P>
                        <P>Display a <Char bold="true">form</Char>.</P>
                    </Content>
                </Results>
            </Range>
            <Status>SUCCESS</Status>
        </Response>
    </ResponsePacket>

Sample query response code

The following Query Web method code generated the preceding query response. This code uses a private method named SavePacket (shown in Building a Research Web Service) to write the request and response packets to a file for further analysis.

    <WebMethod(Description:="The Query method executes the requested" & _
        " query and returns the results to the Research task pane.")> _
    Public Function Query(ByVal queryXml As String) As String

        ' Save the Query Request packet for viewing.
        SavePacket(queryXml, "qryrequest.xml")

        ' Extract values we need from the Query Request
        Dim xmlQuery As XmlDocument = New XmlDocument
        xmlQuery.LoadXml(queryXml)
        Dim nm As XmlNamespaceManager = _
            New XmlNamespaceManager(xmlQuery.NameTable)
        nm.AddNamespace("msq", "urn:Microsoft.Search.Query")
        Dim domain As String = _
            xmlQuery.SelectSingleNode("/msq:QueryPacket/msq:Query", nm) _
                .Attributes.GetNamedItem("domain").Value
        Dim queryId As String = _
            xmlQuery.SelectSingleNode( _
                "/msq:QueryPacket/msq:Query/msq:QueryId", nm).InnerText
        xmlQuery = Nothing

        Dim qryResponseStream As MemoryStream = New MemoryStream
        Dim qryResponseWriter As XmlTextWriter
        qryResponseWriter = New XmlTextWriter(qryResponseStream, Nothing)

        With qryResponseWriter

            ' Format the output for easy viewing.
            .Formatting = Formatting.Indented

            ' Compose the Query Response packet.
            .WriteStartDocument()
            .WriteStartElement("ResponsePacket", _
                "urn:Microsoft.Search.Response")
            ' The providerRevision attribute can be
            ' used to update the service.
            .WriteAttributeString("providerRevision", "1")
            .WriteStartElement("Response")
            ' The domain attribute identifies the service
            ' that executed the query.
            .WriteAttributeString("domain", domain)
            .WriteElementString("QueryID", queryId)
            .WriteStartElement("Range")
            .WriteStartElement("Results")

            ' Begin Document element
            .WriteStartElement("Document", _
                "urn:Microsoft.Search.Response.Document")
            .WriteElementString("Title", "Microsoft Web Site")
            .WriteStartElement("Action")
            .WriteStartElement("LinkUrl")
            .WriteAttributeString("fileExt", "htm")
            .WriteString("http://www.microsoft.com")
            .WriteEndElement() ' LinkUrl
            .WriteEndElement() ' Action
            .WriteElementString("DisplayUrl", "http://www.microsoft.com")
            .WriteElementString("Description", _
                "The home page for the Microsoft Corporation.")
            ' Include an image
            .WriteStartElement("Media")
            .WriteAttributeString("type", "IMAGE")
            .WriteElementString("SrcUrl", _
                "http://www.microsoft.com/ _
                    homepage/gif/bnr-microsoft.gif")
            .WriteElementString("AltText", "Microsoft logo")
            .WriteEndElement() ' Media
            .WriteEndElement() ' Document
            ' End Document element

            ' Begin Content element
            .WriteStartElement("Content", _
                "urn:Microsoft.Search.Response.Content")
            .WriteStartElement("HorizontalRule")
            .WriteEndElement() 'Horizontal rule
            .WriteElementString("P", "Hello world!")
            .WriteStartElement("HorizontalRule")
            .WriteEndElement() 'Horizontal rule
            .WriteStartElement("Heading")
            .WriteElementString("Text", _
                "Features of the Research Task Pane")
            .WriteEndElement() 'Heading
            .WriteElementString("P", "Return a list of links.")
            .WriteElementString("P", "Return richly formatted content.")
            .WriteStartElement("P")
            .WriteString("Display a ")
            .WriteStartElement("Char")
            .WriteAttributeString("bold", "true")
            .WriteString("form")
            .WriteEndElement() ' Char
            .WriteString(".")
            .WriteEndElement() ' P
            .WriteEndElement() ' Content
            ' End Content element

            ' Finish up.
            .WriteEndElement() ' Results
            .WriteEndElement() ' Range
            .WriteElementString("Status", "SUCCESS")
            .WriteEndElement() ' Response
            .WriteEndElement() ' ResponsePacket
            .WriteEndDocument()

        End With

        qryResponseWriter.Flush()

        ' Move the results into a string.
        qryResponseStream.Position = 0
        Dim qryResponseReader As StreamReader = _
            New StreamReader(qryResponseStream)
        Dim qryResponsePacket As String = qryResponseReader.ReadToEnd()

        ' Save and return the Query Response packet.
        SavePacket(qryResponsePacket, "qryresponse.xml")
        Return qryResponsePacket

    End Function

©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