Microsoft Discovery (DISCO)

DISCO is a Microsoft-defined specification for discovering Web services that are available on a server. However, its scope extends only to individual servers and to providing the client with a WSDL document. If you need to publish more details of available Web services on a larger scale, you must use UDDI instead.

Note

Rather than write new Web services to show the facilities that DISCO offers, we’ll use the seven Web services that we created in Chapter 3. You can find them at http://localhost/wscr/04, using the same directory structure as in Chapter 3.

The DISCO Specification

The basis of the entire DISCO process is the discovery document, which contains the information that enables a client to find the physical address of the Web service on the server. The discovery document can also provide links to other discovery documents and to schema documents that describe the Web service.

The basic outline of the discovery document is as follows:

<?xml version="1.0"?> <discovery xmlns="http://schemas.xmlsoap.org/disco/">   <contractRef />   ⋮   <contractRef />   <discoveryRef />   ⋮   <discoveryRef />   <schemaRef />   ⋮   <schemaRef /> </discovery>

Within the <discovery> element, we defined three child elements that can appear multiple times. These elements are used to link to different documents on the server:

• <contractRef> This is the most important element in a discovery document because it provides the link to the actual Web service. The ref attribute points to the WSDL file for the Web service, and the docRef attribute provides details of any accompanying documentation for the Web service. For ASP.NET Web services, the docRef attribute points to the actual .asmx file, and the ref attribute points to the .asmx file with the ?wsdl query string.

• <discoveryRef> This element provides a link, via the ref attribute, to another discovery document.

• <schemaRef> This element provides a link, via the ref attribute, to an XML Schema (XSD) file that details the Web service. This element is not used in version 1.1 of the Microsoft .NET Framework.

Discovery Document Types

You can write a discovery document using the format we’ve discussed, give it a .disco extension, and place it on a Web server. Discovery-enabled browsers such as the Add Web Reference dialog box in Visual Studio .NET will correctly parse this document. Writing a discovery document manually and using it to discover the available Web services is known as static discovery, and in most cases this is the best way to use discovery because it provides the most control. However, .NET offers two other methods for generating discovery documents: dynamic discovery and .asmx file discovery.

A dynamic discovery document, which has a .vsdisco extension, automatically searches the server’s directory structure to gather references to all of the available Web services and other discovery documents. With .asmx file discovery, any Web service you write can also be used as a discovery document; you specify the ?disco query string when you view a Web service via HTTP.

We’ll look at each type of discovery document in turn.

Static Discovery

Static discovery is the simplest approach to implement and involves manually creating a file with a .disco extension and adding the required <discovery> element to it. Within the document, you add a <contractRef> element for each Web service you want to make available; if you want a reference to only one Web service, add only one <contractRef> element.

As you can see if you look at the static discovery document at http: //localhost/wscr/04/default.disco, adding a reference to a Web service is simple. This discovery document has a single reference to the RecordFinder Web service:

<?xml version="1.0"?> <discovery xmlns="http://schemas.xmlsoap.org/disco/">   <contractRef    ref=" http://localhost/wscr/04/recordfinder.asmx?wsdl"    docRef=" http://localhost/wscr/04/recordfinder.asmx"    xmlns="http://schemas.xmlsoap.org/disco/scl/" />

You can add as many <contractRef> elements as are required, and you can also add links to other discovery documents by adding <discoveryRef> elements:

  <discoveryRef    ref="http://localhost/wscr/04/simple/default.disco" />   <discoveryRef    ref="http://localhost/wscr/04/soap/default.vsdisco" />  </discovery>

As you can see, we added links to two other discovery documents—one static and one dynamic. You’re free to mix and match types of discovery documents that you’re linking to.

Dynamic Discovery

Dynamic discovery lets you forget about the discovery document and have .NET generate it. This might seem like an ideal scenario, but it comes with several security problems. Microsoft has deemed the problems so severe that dynamic discovery is disabled in .NET; before you can use dynamic discovery, you must enable it on the server.

.NET integration with IIS has two parts, and only one of these is actually disabled. As with all files that you want IIS to handle, you need a mapping for the extension to the correct handler. When .NET is installed, this mapping is already in place, and files with the .vsdisco extension are mapped to the aspnet_isapi.dll handler. It is within the .NET configuration itself that the handling of the .vsdisco files has been disabled.

To enable handling of the .vsdisco files, you must modify the configuration files, at either the machine level (in machine.config) or the application level (in a web.config file). At either level, you must add the following to the <httpHandlers> element:

<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>

After you enable dynamic discovery on your server, you can use it by creating a file with a .vsdisco extension, and instead of adding a <discovery> element, you can add a <dynamicDiscovery> element. In the dynamic discovery document at http://localhost/wscr/04/soap/default.vsdisco, we added this <dynamicDiscovery> element and also specified several directories to exclude from the search:

<?xml version="1.0" encoding="utf-8" ?> <dynamicDiscovery xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17">   <exclude path="_vti_cnf" />   <exclude path="_vti_pvt" />   <exclude path="_vti_log" />   <exclude path="_vti_script" />   <exclude path="_vti_txt" />   <exclude path="Web References" /> </dynamicDiscovery>

We told the parser to exclude the various Microsoft FrontPage directories, as well as the Web References directory; if you specify a directory that doesn’t exist, the entry is simply ignored.

Barring the excluded directories, the parser searches all the directories from the location of default.vsdisco downward in the directory tree, looking in any real directories that it finds (ignoring virtual directories). Within each directory, the parser looks for any files with the extensions .vsdisco, .disco, and .asmx, in that order. One word of warning: the parser looks first for files with the extension .vsdisco, and if it finds one, it stops searching that part of the directory tree; it ignores all other files in that directory and all its subdirectories.

After searching the directory tree as described, the parser constructs a <discovery> element that contains a <contractRef> element for each .asmx file it found and a <discoveryRef> element for each .vsdisco or .disco file it found.

The http://localhost/wscr/04/soap/default.vsdisco discovery document in Internet Explorer returns five Web services, as shown in Figure 4-1.

Figure 4-1: A dynamically generated discovery document

As you can see, we returned the correct five Web services, which, as you might recall, show the different SOAP message formats. You’ll also see two extra namespaces mapped to the <discovery> element—one with the prefix xsd and the other with the prefix xsi. You’ll probably gather from the prefixes and the addresses they map to that the namespaces are concerned with XSD documents. Even though we don’t have any <schemaRef> elements in our discovery document, the parser still adds the namespaces to our document.

.asmx File Discovery

In addition to the two physical discovery documents that you can create for static or dynamic discovery, the .asmx files that contain your Web services can also generate an .asmx discovery file.

In much the same way that you can interrogate an .asmx file to provide the correct WSDL for the Web service by using the ?wsdl query string, you can use the ?disco query string to force an .asmx file to give you the discovery document for itself.

The RecordFinder Web service that we mentioned in the static discovery document shown earlier generates a discovery document for itself, as shown in Figure 4-2.

Figure 4-2: A discovery document from an .asmx file

Like the dynamically generated discovery document described previously, the .asmx discovery document includes two extraneous namespaces and a <soap> element that you can safely ignore. The address and binding attributes of the <soap> element map to the details contained in the .wsdl file, but they are never used, so you can ignore the entire element.

Visual Studio .NET and DISCO Files

Now that we’ve looked at the DISCO specification and the three types of discovery documents, it’s time to see how Visual Studio .NET actually deals with discovery. We’ll use the Web services from Chapter 3 and the two discovery documents we just looked at.

In Visual Studio, selecting Add Web Reference from the Project menu launches the Add Web Reference dialog box, where you can navigate to the discovery document you’re interested in or enter the document’s URL and then click Go.

If we navigate to http://localhost/wscr/04/default.disco, the static discovery document we looked at earlier, Visual Studio .NET will display the returned document in the browser window, as shown in Figure 4-3.

Figure 4-3: Adding a reference using a discovery document in Visual Studio .NET 2003

The Web server returns the discovery document we created earlier to the dialog box, and the dialog box does some processing on this returned file to present the user-friendly version of the document shown in Figure 4-3.

Clicking the View Service link takes us to the URL that is specified as the docRef attribute of the <contractRef> element. Similarly, the View Documentation link takes us to the URL specified in the ref attribute.

If you look again at Figure 4-3, you’ll notice that some of the information we described in the discovery file is missing. We specified two links to other discovery documents that are missing from the details shown in the Add Web Reference dialog box in Visual Studio .NET 2003. As shown in Figure 4-4, the previous version of Visual Studio .NET, Visual Studio .NET 2002, displays these links when we navigate to a discovery document.

Figure 4-4: Adding a reference using a discovery document in Visual Studio .NET 2002

In Visual Studio .NET 2002, we can use the links to other discovery documents to navigate to those documents without needing to know the address of the discovery document. Without this feature in Visual Studio .NET 2003, we need to know the addresses of the individual discovery documents.

Adding a Web Reference from a Discovery Document

When you view a discovery document, as you saw in Figure 4-3, you have the option of adding the reference directly from the discovery file. If only one Web service is referenced in the discovery document, this isn’t a problem—the correct reference to the Web service is added to the project. But problems occur when you try to add references from a discovery document that contains multiple Web service definitions. If you look at the discovery document at http: //localhost/wscr/04/soap/default.vsdisco, you’ll see five Web services defined, as shown in Figure 4-5.

Figure 4-5: Adding a reference from a discovery document with multiple Web services

You might think that clicking the Add Reference button will add references to all five Web services to the project. Instead, although all five referenced WSDL documents are downloaded and added to the reference, a proxy class is created only for the last Web service referenced in the file—in this case, RecordFinder5.

Because of the behavior that Visual Studio .NET exhibits when you add references from a discovery document that contains multiple Web service definitions, you should always add a reference to the Web service from the .asmx file itself, not from a discovery document. You can thereby avoid problems that might occur with the ordering of the Web services within the discovery document.

Adding a Web Reference from a Web Service

In the previous chapter, we looked at adding references to Web services from the .asmx file itself and also from the .asmx file with the ?wsdl query string added. You just learned how to get to these references from the discovery document, and we recommended this approach as the best way to add references to Web services.

As you saw in Chapter 3, when you add a reference to a Web service, Visual Studio .NET in some cases automatically queries the Web service for a discovery document for itself. We said then that we’d leave the discussion of the .disco file until this chapter; we’ll address that subject now.

When you view an .asmx file and add it as a reference, Visual Studio .NET has no idea what the .wsdl definition of that document is. To retrieve the WSDL definition of the Web service, Visual Studio .NET queries the .asmx file with the ?disco query string to return the discovery document for the Web service. Because this discovery document contains the contract details for the Web service, Visual Studio .NET can locate the WSDL for the Web service, download it, and create the proxy, as you’d expect. Visual Studio .NET keeps a copy of the discovery document and the WSDL file, and if you look at those two files you’ll see that the two cached files are the same as those we’d see if we were to query the Web service by using the ?wsdl and ?disco query strings.

When you view an .asmx file with the ?wsdl query string, you see the WSDL definition of the document. When you add a reference to a Visual Studio .NET project by using a WSDL document, Visual Studio .NET adds the WSDL file to the reference and creates the proxy class from it—it doesn’t need to query for a discovery document because it already has the WSDL definition of the Web service.