16.2 Creating a Discovery File

Once you have created a web service, there must be some way for the developers who will develop the consuming applications to find out about the methods exposed by the web service. This process is called discovery.

The description of the web service is contained in a service description document, an XML document written in a format called WSDL (Web Service Description Language). You have already seen the WSDL document for our example web service in this chapter, in Figure 16-2. There are two ways to view a WSDL document.

The first is to enter the URL of the web service .asmx file in a browser to generate the web service test page, as shown in several of the figures in this chapter, including Figure 16-4 and Figure 16-12. Near the top of the test page will be a link to a Service Description. Clicking on that link will bring up the WSDL document.

Alternatively, enter the URL for a web service .asmx file in a browser with ?WSDL appended to the end of the URL. For example, entering the following URL in a browser would display the WSDL for the web service csStickTicker.asmx:

http://localhost/ProgAspNet/csStockTicker.asmx?WSDL

To ease the chore of generating a WSDL document for the developer creating the consuming application, you can create a .disco file. This is an XML file located in the same virtual directory as the .asmx file. The developer creating the consuming application can then use the .disco file, as will be demonstrated shortly.

Example 16-29 shows a .disco file for the web service in the previous URL.

Example 16-29. csStockTicker.disco, a discovery file for StockTicker web service

<?xml version="1.0" ?>
<disco:discovery 
   xmlns:disco="http://schemas.xmlsoap.org/disco"
   xmlns:scl="http://schemas.xmlsoap.org/disco/scl">
   <scl:contractRef ref="http://localhost/ProgAspNet/csStockTicker.asmx?WSDL"/>
</disco:discovery>

The first line in Example 16-29 specifies the file as XML and the version. The rest of the file is contained within a pair of disco:discovery tags. This tag points to the links a client should follow if it wants to find out about the web service. The next two lines specify XML namespace aliases, which refer to URLs that define the disco and scl tags.

The scl:contractRef tag specifies where the service description can be found. Notice that it is the same URL mentioned previously for manually generating the WSDL. It is not always the case that the URL of the .disco file and URL of the .asmx file it references point to the same location.

The .disco file can also reference another .disco file by including a line similar to

<disco:discoveryRefref="SomeFolder/default.disco" />

where default.disco is another .disco file in a subdirectory below the current directory, called SomeFolder.

Although 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 .NET Command Prompt from the Start Menu in order to get the correct path). Then enter a command similar to the following:

disco /out:<output directory name> http://localhost/ProgAspNet/csStockTicker.asmx

As an alternative to using the out switch to specify the output directory, change the directory to the directory 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 16-4) in the output directory.

Table 16-4. Files output by the disco utility

Filename	Description
csStockTicker.disco	Discovery document you are trying to create.
csStockTicker.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	Alternative discovery document.

At this stage of the process, the .disco file is the main output you are interested in. The other two files may be used by a developer creating a consuming application, as will be described in Chapter 17.

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

disco /?