Handling Registration Requests

Each research service that is available on a client computer is defined by a group of registry settings. Therefore, installing or deploying a research service involves adding those registry settings to the client computer. The Registration Web method of a research Web service sends the values for those settings to the client computer when the user chooses to add the service by typing in the URL, or by selecting an advertised service. The Research task pane creates the registry settings based on the registration response.

Note Administrators can also register research services on client computers by using methods that transfer the required registry settings without the use of the Registration Web method. For more information, see Deployment Overview.

Important Although we talk about registering a research service, the normal registration process registers a research service provider, along with the research service or services that the provider chooses to register on the user's computer. While the provider (through logic in the Registration method) can programmatically select which services to install, the user does not have an equivalent option in the Research task pane user interface to select or exclude individual services at the time of registration. In some cases, the provider may choose to install services, but not to activate them, by setting their Display setting to "Off." The user can activate or deactivate services at any time, from the Research Options dialog box.

Registration Web Method

The Registration Web method receives an incoming string value from the Research task pane in the form of an XML document that conforms to the Microsoft.Search.Registration.Request.xsd schema, and returns a string value describing the provider and its services in the form of an XML document that conforms to the Microsoft.Search.Registration.Response.xsd schema.

Visual Basic® .Net

<WebMethod(Description="Provider Registration Web Method")> _
Public Function Registration(registrationXml As String) As String

[WebMethod(Description="Provider Registration Web Method")]
public string Registration(string registrationXml)

Important The string input parameter for the Registration Web method must be named registrationXml. 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 Registration Request and Response

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

<RegistrationRequest 
    xmlns="urn:Microsoft.Search.Registration.Request" 
    revision="" build=""> 
    <OriginatorId/> 
    <SupportedFormats> 
        <Format revision="" build=""/> 
        <Any/> 
    </SupportedFormats>
    <SystemInformation> 
        <SkuLanguage/> 
        <LanguagePack/> 
        <InterfaceLanguage/> 
        <Any/> 
    </SystemInformation>
    <Any/> 
</RegistrationRequest>

For more information, see Microsoft.Search.Registration.Request Schema Documentation.

<ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response"
    revision="" build=""> 
    <Status/> 
    <Message/> 
    <Providers> 
        <Provider> 
            <Message/> 
            <License acceptRequired=""> 
                <LicenseText/> 
                <Any/> 
            </License>
            <Id/> 
            <Name/> 
            <QueryPath/> 
            <RegistrationPath/> 
            <AboutPath/> 
            <Type/> 
            <Revision/> 
            <Services> 
                <Service> 
                    <Id/> 
                    <Name/> 
                    <Data/> 
                    <Description/> 
                    <AboutPath/> 
                    <Copyright/> 
                    <TermsOfUsePath/> 
                    <Display/> 
                    <Category/> 
                    <OptionsPath/> 
                    <Parental/> 
                    <Any/> 
                </Service>
                <Any/> 
            </Services>
            <Any/> 
        </Provider>
        <Any/> 
    </Providers>
    <Any/> 
</ProviderUpdate>

The registration response may make multiple research services available through the use of multiple Service elements. However, only one Provider element is supported. A single provider and its services correspond to a single XML Web service (or pair of services) and a single registration URL.

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

Caution In this version of the Research task pane, omitting the optional acceptRequired attribute from the License element of the registration response may cause a problem in the Microsoft® Office 2003 application on the client computer.

Elements of the Registration Request and Response

For examples of the elements in a typical registration request and response, see the sample registration request and the sample registration response later in this topic.

The SystemInformation section of the registration request includes language and locale-related information about the user's computer in the SkuLanguage, LanguagePack, InterfaceLanguage, and Location elements. A provider of localized research services can use this information to decide which services to install and which services to activate on the user's computer. For example, Microsoft Office 2003 uses these elements in the following way:

SkuLanguage and LanguagePack determine which services are installed. For example, if the SkuLanguage is English, Office installs dictionaries for US English, UK English, Australian English, and so forth.
Location determines the services that are activated. For example, if the Location is the United States, only the US English dictionary is activated for searching.
InterfaceLanguage determines the language used for registration registry entries and messages.

The following table maps provider-related elements and attributes in the registration response to the corresponding registry entries on the client computer and the related user interface elements in the Research task pane. Provider information appears in the registry in the HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\Research\Sources subkey. For each provider, a subkey appears under the Sources subkey. The name of this subkey is the globally unique identifier (GUID) that uniquely identifies the service provider. Each provider key has subkeys for the services offered by the provider. The names of these subkeys are also GUIDs that uniquely identify each service.

For more information about the provider-related registry settings and their use, see Provider Registry Settings. Note that some required provider-related registry settings, such as Status and UpdateStatus, do not have a corresponding elements in the registration response. The Research task pane creates these settings automatically when a service is registered by invoking the Registration method.

Response Element	Required?	Registry Setting	User Interface Element
Message	No	n/a	Displayed on the first screen of the registration dialog box. A Message element appears at two places in the registration response schema; under the top-level ProviderUpdate element, and under the Provider element. Since this version of the Research task pane supports only one provider per registration, you normally would use only one of the Message elements.
LicenseText	No	n/a	Appears only during the registration process.
ID	Yes	GUID used as the provider subkey under the Sources subkey	Not shown.
Name	Yes	ProviderName	Appears as the value of Provider Name in the Service Properties dialog box. Also appears in the Update/Remove dialog box with the provider's services grouped underneath.
QueryPath	Yes	QueryPath	Appears as the value of Path in the Service Properties dialog box.
RegistrationPath	No	RegistrationPath	Not shown.
AboutPath	No	AboutPath	Not shown, but accessed from the Learn more about this provider link in the Service Properties dialog box.
Type	Yes	Type	Not shown.
Revision	No	Revision	Not shown. For more information, see Updating and Removing Services.
Services	Yes	Service subkeys appear as GUIDs under the provider key	Shown in the user interface grouped by category, not by provider.

The following table maps service-related elements and attributes in the registration response to the corresponding registry entries on the client computer and user interface elements in the Research task pane. Service information appears in the registry under HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\Research\Sources\{Provider}. For each service, a subkey appears under the key for the appropriate provider. The name of this subkey is the GUID that uniquely identifies the service.

For more information about the service-related registry settings and their use, see Service Registry Settings. Note that some required service-related registry settings, such as Status, PersistData, and SortOrder, do not have a corresponding element in the registration response. The Research task pane creates these settings automatically when a service is registered by invoking the Registration method.

Response Element	Required?	Registry Setting	User Interface Element
ID	Yes	GUID used as the service subkey under the Sources\{Provider} key	Not shown.
Name	Yes	ServiceName	Appears as the value of Service Name in the Service Properties dialog box, and in other Research task pane dialog boxes. Also, appears in the Research task pane above results returned by the service.
Data	No	SourceData	Not shown. The Data element holds an arbitrary value for use by the developer. Each query to the service sends the value of this element back to the server.
Description	No	Description	Appears as the value of Description in the Service Properties dialog box.
AboutPath	No	AboutPath	Not shown, but accessed from the Learn more about this service link in the Service Properties dialog box.
Copyright	No	TermsOfUse	Appears as the value of Copyright Notice in the Service Properties dialog box.
TermsOfUsePath	No	TermsOfUsePath	Not shown, but accessed from the Terms of use link in the Service Properties dialog box.
Display	No	Display	Not shown.
Category	Yes	CategoryID	Appears as the value of Content Category in the Service Properties dialog box. The registration response and the Research task pane use the category name instead of its ID. Services appear grouped by category, and the user can search an entire category of services at a time.
OptionsPath	No	OptionsPath	Not shown, but accessed from the Options button in the Service Properties dialog box.
Parental	No	Parental	Not shown.

Walkthrough: Sample Registration Request, Response, and Code

The following sample registration request includes language and location information that a localized (translated) research service can use to return appropriate content. The fixed OriginatorID value identifies Microsoft Office 2003.

<RegistrationRequest revision='2' build='(11.0.5606)' 
    xmlns='urn:Microsoft.Search.Registration.Request'>
    <OriginatorId>
        {F6FF7BE0-F39C-4ddc-A7D0-09A4C6C647A5}</OriginatorId>
    <SystemInformation>
        <SkuLanguage>en-us</SkuLanguage>
        <LanguagePack>en-us</LanguagePack>
        <InterfaceLanguage>en-us</InterfaceLanguage>
        <Location>US</Location>
    </SystemInformation>
</RegistrationRequest>

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

The following sample registration response comes from a fictitious "Hello World Test Research Services" provider on a development server (thus the INTRANET_GENERAL category). It presents a single service named "Hello World Test Research Service in VB" to the user for registration. The Message appears on the Introduction screen of the Service Setup dialog box.

<?xml version="1.0"?>
<ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response">
    <Status>SUCCESS</Status>
    <Providers>
        <Provider>
            <Message>
                This is the message displayed by the Message
                element that is a child of the Provider element.
            </Message>
            <License acceptRequired="false">
                <LicenseText>
                    This test service has no licensing requirement.
                </LicenseText>
            </License>
            <Id>{17CA29E2-854B-4291-86CD-D1EDE116D69F}</Id>
            <Name>Hello World Test Research Services</Name>
            <QueryPath>
                http://localhost/HelloWorldVB/HelloWorldVB.asmx
            </QueryPath>
            <RegistrationPath>
                http://localhost/HelloWorldVB/HelloWorldVB.asmx
            </RegistrationPath>
            <Type>SOAP</Type>
            <Revision>1</Revision>
            <Services>
                <Service>
                    <Id>{41F27485-961F-4ea1-82F1-7623E55DE293}</Id>
                    <Name>
                        Hello World Test Research Service in VB
                    </Name>
                    <Description>
                        My first Research service, 
                        Visual Basic .Net version.
                    </Description>
                    <Copyright>This test service is not copyrighted.
                        </Copyright>
                    <Display>On</Display>
                    <Category>INTRANET_GENERAL</Category>
                    <Parental>Unsupported</Parental>
                </Service>
            </Services>
        </Provider>
    </Providers>
</ProviderUpdate>

The following Registration Web method code generated the preceding registration 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 Registration method registers" & _
    " or updates the Research service on client computers.")> _
Public Function Registration(ByVal registrationXml As String) _
    As String

    ' Save the Registration Request packet for viewing.
    SavePacket(registrationXml, "regrequest.xml")

    Dim regResponseStream As MemoryStream = New MemoryStream
    Dim regResponseWriter As XmlTextWriter
    regResponseWriter = _
        New XmlTextWriter(regResponseStream, Nothing)

    With regResponseWriter

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

        ' Compose the Registration Response packet.
        .WriteStartDocument()
        .WriteStartElement("ProviderUpdate", _
            "urn:Microsoft.Search.Registration.Response")
        .WriteElementString("Status", "SUCCESS")

        ' PROVIDER information. Only one Provider is allowed.
        .WriteStartElement("Providers")
        .WriteStartElement("Provider")
        .WriteElementString("Message", _
            "This is the message displayed by the Message " & _
                "element that is a child of the Provider element.")
        .WriteStartElement("License")
        .WriteAttributeString("acceptRequired", "false")
        .WriteElementString("LicenseText", _
            "This test service has no licensing requirement.")
        .WriteEndElement() ' License.
        ' Use the GUIDGEN.EXE tool to 
        ' generate a GUID for the Provider.
        .WriteElementString("Id", " _
            {17CA29E2-854B-4291-86CD-D1EDE116D69F}")
        .WriteElementString("Name", _
            "Hello World Test Research Services")
        .WriteElementString("QueryPath", _
            "http://localhost/HelloWorldVB/HelloWorldVB.asmx")
        .WriteElementString("RegistrationPath", _
            "http://localhost/HelloWorldVB/HelloWorldVB.asmx")
        ' The optional AboutPath for the Provider is not used here.
        .WriteElementString("Type", "SOAP")
        .WriteElementString("Revision", "1")

        ' SERVICE information. This sample shows a single service,
        '  but multiple Services can be registered
        .WriteStartElement("Services")
        .WriteStartElement("Service")
        ' Use the GUIDGEN.EXE tool to 
        ' generate a GUID for the Service.
        .WriteElementString("Id", _
            "{41F27485-961F-4ea1-82F1-7623E55DE293}")
        .WriteElementString("Name", _
            "Hello World Test Research Service in VB")
        ' The optional Data element is not used here.
        .WriteElementString("Description", _
            "My first Research service, Visual Basic .Net version.")
        ' The optional AboutPath for the Service is not used here.
        .WriteElementString("Copyright", _
            "This test service is not copyrighted.")
        ' The optional TermsOfUsePath for 
        ' the Service is not used here.
        .WriteElementString("Display", "On")
        .WriteElementString("Category", "INTRANET_GENERAL")
        ' The optional OptionsPath for the Service is not used here.
        .WriteElementString("Parental", "Unsupported")

        ' Finish up.
        .WriteEndElement() ' Service
        .WriteEndElement() ' Services
        .WriteEndElement() ' Provider
        .WriteEndElement() ' Providers
        .WriteEndElement() ' ProviderUpdate
        .WriteEndDocument()

    End With

    regResponseWriter.Flush()

    ' Move the results into a string.
    regResponseStream.Position = 0
    Dim regResponseReader As StreamReader = _
        New StreamReader(regResponseStream)
    Dim regResponsePacket As String = regResponseReader.ReadToEnd()

    ' Save and return the Registration Response packet.
    SavePacket(regResponsePacket, "regresponse.xml")
    Return regResponsePacket

    End Function