Section 15.12. Creating Discovery Documents

15.12. Creating Discovery Documents

Once you have created a web service, the developers who develop the consuming applications will want a way to find out what web services are available on a server, the methods exposed by those web services, what parameters those methods and properties expect to receive, and what data type the web method returns. This process is called discovery , which is an optional process. If the developer of the consuming application knows the URL of the web service file ( .asmx ), then there will be no need to do discovery.

This discovery information is contained in discovery documents. These are XML files created with a command line utility called disco.exe, described next .

There are several ways for a web service consumer to access a discovery document, including viewing a discovery document with a query string and making use of a static discovery file.

These two methods are described in the following sections.

15.12.1. Discovery via Query String

A developer may be able to create a client application by obtaining the disco file created on the server. To see this file, append ?disco to the URL of the service.asmx file:

 http://localhost/StockTicker/service.asmx?disco 

This will display the following disco file:

 <?xml version="1.0" encoding="utf-8" ?>     - <discovery xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"         xmlns:xsd="http://www.w3.org/2001/XMLSchema"         xmlns="http://schemas.xmlsoap.org/disco/">       <contractRef ref="http://localhost/StockTicker/service.asmx?wsdl"         docRef="http://localhost/StockTicker/service.asmx"         xmlns="http://schemas.xmlsoap.org/disco/scl/" />       <soap address="http://localhost/StockTicker/service.asmx"         xmlns:q1="www.LibertyAssociates.com" binding="q1:OverloadedGetValue"         xmlns="http://schemas.xmlsoap.org/disco/soap/" />       <soap address=http://localhost/StockTicker/service.asmx         xmlns:q2="www.LibertyAssociates.com" binding="q2:StockTickerSoap"         xmlns="http://schemas.xmlsoap.org/disco/soap/" />       <soap address="http://localhost/StockTicker/service.asmx"         xmlns:q3="www.LibertyAssociates.com" binding="q3:OverloadedGetValue1"         xmlns="http://schemas.xmlsoap.org/disco/soap/" />       <soap address="http://localhost/StockTicker/service.asmx"         xmlns:q4="www.LibertyAssociates.com" binding="q4:StockTickerSoap12"         xmlns="http://schemas.xmlsoap.org/disco/soap/" />       </discovery> 

15.12.2. Static Discovery Files

For the consumer of a web service to use a static discovery file, the developer of the web service must create it. (The client's use of discovery is covered in the next chapter.)

Though you can create the .disco file manually, it is far easier to use the disco.exe command-line utility. To do this, open a command prompt window (remember to use the Visual Studio 2005 Command Prompt from the Start Menu to get the correct path ). Then enter a command similar to the following (all on one line):

 disco /out:<output directory name>        http://localhost/StockTicker/service.asmx 

As an alternative to using the out switch to specify the output directory, change the current directory to where you want the output to be located in before executing the command and run the disco utility from that directory. The output will go to the current directory.

The disco utility executed in the previous command line will put three files (summarized in Table 15-3) in the output directory.

Table 15-3. Files output by the disco utility

Filename	Description
service.disco	Discovery document that contains references to descriptions of the resources available in the web service
service.wsdl	This is the exact same WSDL for the web service generated by entering the .asmx file in a browser with ?wsdl appended to the URL
results.discomap	Contains a reference to both the .disco and .wsdl files

At this stage of the process, the .disco file is the main output that interests you. The other two files may be used by a developer creating a consuming application, as will be described in the next chapter.

For a complete listing of all the parameters available to the disco utility, enter the following command line:

 disco /?