How to: Enable Discovery for XML Web Services

Article
02/13/2011

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

Web services can be published to potential clients in the following ways:

Using an XML discovery file with a .disco file name extension.
Using a URL that specifies a .vsdisco extension.
Using a Web service with a query string of ?DISCO.

This topic shows how to set up the first two of these discovery mechanisms. This topic does not demonstrate how to enable requests for a Web service with a query string of ?DISCO, because this method is already automatically available. For an explanation of these options, see XML Web Services Publishing and Deployment.

To public a static discovery document for a Web service

Create an XML document with your favorite editor, adding the ?xml version="1.0" ? element 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 want 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, 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 want 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 element 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 element 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 element 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="MyWebService.disco" ?>
```

To enable dynamic discovery for a Web service

To turn on dynamic discovery for a Web server, modify the machine.config file by adding 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 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 might expose sensitive data, if the Web server is not on a network that uses a firewall and other security features.

Share via

How to: Enable Discovery for XML Web Services

To public a static discovery document for a Web service

To enable dynamic discovery for a Web service

See Also

Concepts

Other Resources

Additional resources