Enabling Discovery for an XML Web Service

Article
10/17/2014

XML Web service discovery is the process of locating and interrogating XML Web service descriptions, which is a preliminary step for accessing an XML Web service. Through the discovery process, XML Web service clients can learn at design time that an XML Web service exists, what its capabilities are, and how to properly interact with it.

Programmatic discovery can be enabled when an XML Web service publishes a .disco file, which is an XML document that can contains links to other discovery documents, XSD schemas, and service descriptions. Alternatively, XML Web services created using ASP.NET automatically have the capability of providing a generated discovery document. A discovery document is automatically generated for an XML Web service when it is accessed using a URL with ?DISCO provided in the query string. For instance, if the URL to an XML Web service is www.contoso.com/getquote.asmx, then a discovery document is automatically generated with a URL of www.contoso.com/getquote.asmx?DISCO.

To enable discovery for an XML Web service

Create an XML document with your favorite editor, adding the <?xml version="1.0" ?> tag to the first line.

Within the XML document add a <discovery> element, such as

<disco:discovery xmlns:disco="https://schemas.xmlsoap.org/disco/"></disco:discovery>

Within the <discovery> element, add references to service descriptions, XSD schemas, and other discovery documents.

You can add as many references as you would like to publicly expose. Service description references are specified in a discovery document by adding a <contractRef> element with the https://schemas.xmlsoap.org/disco/scl/ XML namespace. Likewise, references to other discovery documents and XSD schemas are specified by adding <discoveryRef> and <schemaRef> XML elements, respectively. For XSD schema references, the XML namespace https://schemas.xmlsoap.org/disco/schema must be specified. For all three types of referenced documents, you specify the location of the document by using the ref attribute. The following code example has references to a discovery document, a service description, and an XSD schema.
```
<?xml version="1.0"?>
<discovery xmlns="https://schemas.xmlsoap.org/disco/">
<discoveryRef ref="/Folder/Default.disco"/>
<contractRef ref="http://MyWebServer/UserName.asmx?WSDL"
             docRef="Service.htm"
             xmlns="https://schemas.xmlsoap.org/disco/scl/"/>
<schemaRef ref="Schema.xsd"
           xmlns="https://schemas.xmlsoap.org/disco/schema/"/>
</discovery>
```
References can be relative to the directory where the discovery document resides, as shown in the discoveryRef element, or to a URI, as shown in the contractRef element.
Deploy the discovery document to a Web server by copying it to a virtual directory on the Web server.
Optionally, if you would like to allow prospective consumers to navigate to a URL by specifying an IIS application, without having to specify a document, you can add a link to the default page for the IIS application. This has the benefit that prospective consumers do not have to know the name of any discovery documents. Users can then supply URLs like the following during the discovery process:
```
http://MyWebServer/MyWebApplication
```
If the default page for the Web application is an HTML page:
Add a link to the discovery document in the <head> tag of the default Web page for the Web server. For example, if you name your discovery document MyWebService.disco and place it in the same directory as the default page, you need to place the following tag in the default Web page:
```
<HEAD>
<link type='text/xml' rel='alternate' href-'MyWebService.disco'/>
</HEAD>
```
If the default page for the Web application is an XML document:

Add a link to the discovery document in the <head> tag of the default Web page for the Web server. For example, if you name your discovery document MyWebService.disco and place it in the same directory as the default page, you need to place the following at the top of the default page:
```
<?xml-stylesheet type="text/xml" alternate="yes" href="Mhref.disco" ?>
```
Optionally, if you are using Visual Studio .NET, you can turn on dynamic discovery to allow XML Web service client applications to discover the available XML Web services on a Web server without creating a discovery document. When dynamic discovery is turned on, client applications specify a URL referencing a file with a .vsdisco section, such as www.contoso.com/default.vsdisco in the Add Web Reference dialog box, instead of a specific discovery document.

To turn on dynamic discovery for a Web server, modify the machine.config to add the following <add> element. Ignore the line breaks in the following sample, as the type attribute must be on one line.
```
<configuration>
  <system.web>
     <httpHandlers>
       <add verb="*" path="*.vsdisco"
           type="System.Web.Services.Discovery.DiscoveryRequestHandler,
                 System.Web.Services, Version=1.0.3300.0,
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
           validate="false"/>
     </httpHandlers>
   </system.web>
</configuration>
```
**Note **When dynamic discovery is turned on, all XML Web services and discovery documents existing on the Web server beneath the requested URL are discoverable. Therefore, care must be taken when turning on dynamic discovery, as it could unintentionally expose sensitive data, if the Web server is not on a network that uses a firewall and other security features.

Enabling Discovery for an XML Web Service

See Also

Additional resources