Special Reports
Make Sense of Web Service Discovery
Rumors of DISCO's death have been greatly exaggerated -- it's simply hibernating. Roger Jennings shows you how to wake the DISCO service and prepare for eventual migration to its replacement: WS-Inspection.
To paraphrase Mark Twain, rumors of DISCO's death have been greatly exaggerated. DISCO is hibernating as a result of last-minute changes to Visual Studio .NET security settings, the machine.config file, and Add Web Reference dialog. I'll show you how to wake the DISCO service and prepare for eventual migration to DISCO's replacement—WS-Inspection.
Advertising internal XML Web services in a UDDI 1.0 public registry isn't an option for most Visual Studio .NET developers. Setting up a beta version of an internal UDDI 2.0 registry requires installing Windows .NET Server RC-3+ and the Microsoft UDDI .NET SDK 2.0 Beta 1 from MSDN. Registering Web services with a local UDDI 2.0 implementation is time consuming, and the Add Web Reference dialog is riveted to the Microsoft UDDI 1.0 production and test sites.
If UDDI isn't right for you, here's how to enable display of .vsdisco files in Visual Studio .NET RTM's Add Web Reference dialog:
1. Remove the comment characters (<!-- and -->) from this line of the machine.config file in your \Winnt\Microsoft.Net\Framework\v1.0.3705\Config folder:
<!--<add verb="*" path="*.vsdisco"
type=
"System.Web.Services.Discovery.DiscoveryRequestHandler,
System.Web.Services, Version=1.0.3300.0,
Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
validate="false"/>-->
2. Type http://localhost/default.vsdisco (or substitute your server name for localhost) in the Add Web Reference dialog's Address textbox to display a list of all ASP.NET projects—not just XML Web services—on the local computer (see Figure 1).
3. If you receive an Access Denied exception, add your administrative or development account to the local VS Developers group. (You might need to reboot your server to effect the changes.) If this doesn't work, Microsoft suggests adding the Everyone account to the VS Developers group.
Adding Everyone to the VS Developers group entails a significant security risk, especially if your development machine is connected to the Internet. The "Troubleshooting Add Web References" Knowledge Base article (Q307303) has additional tips for reincarnating DISCO search with the Visual Studio .NET release version.
I have about 50 *.vsdisco files on my primary .NET development server, but only a few production-grade Web services that I might want others to see. Visual Studio .NET RC1 and earlier offered a "Find Web Services on the Local Machine" link, which filtered the .wsdisco files to display only those that point to .asmx or .wsdl files. Opening a .wsdisco file for an ASP.NET Web service enables the Add Reference button (see Figure 2). Links to Web forms applications clutter the Available References list, display an incomplete DISCO document, and disable Add Reference (see Figure 3), so you gain no current or future benefit from retaining those files.
To make default.vsdisco searches more useful to you and other developers in your organization, rename or erase spurious .vsdisco files for ASP.NET Web forms clients. Don't rename the DynamicDisco.vsdisco files; they don't appear in Add Web References lists and you need them to support Visual Studio .NET project templates. If for some reason you've lost a ServiceName.vsdisco file, you can regenerate it by typing http://servername/servicename.asmx?disco in the Address textbox. This technique also works for services you've hidden by erasing or renaming their .vsdisco files during development. Regenerating the .vsdisco file adds a <soap> element to the discovery document (see Figure 4).
Preview the WS-Inspection Alternative
The October 2001 IBM/Microsoft WS-Inspection 1.0 specification, which Microsoft has subsumed into its still-nebulous Global XML Architecture (GXA) proposal, presumably will replace DISCO when the Visual Studio .NET folks get around to delivering an implementation. IBM's Web Services Toolkit has supported WS-Inspection since version 2.4.1 and the current release (version 3.1 at this writing) even implements the SOAP Security Token and Digital Signature elements of the proposed WS-Security 1.0 specification. WS-Inspection, which the authors of the "The WS-Inspection and UDDI Relationship" white paper analogize with business cards, is a substantial improvement to DISCO and IBM's original Advertisement and Discovery of Services (ADS) implementation. If you want to expose private .NET XML Web services to WebSphere developers, WS-Inspection is an answer.
WS-Inspection is an open-ended XML dialect for discovery of Web service provider endpoints. The WS-Inspection schema has extension schemas for WSDL and UDDI bindings. The specification supports additional bindings to service documentation, such as an .asmx page. WS-Inspection also supports free-form location and identification mechanisms such as this WS-Inpsection example from XMethods.net's Web service registry, which also offers a DISCO interface that works in the Add Web Reference dialog.
Microsoft's WS-Inspection sample (see Resources) is an early C# project for manually generating .wsil files from URLs that point to WSDL files. The WsiLibrary defines a set of Web.Services.Inspection serialization classes, which correspond to the basic WS-Inspection elements. To generate a custom inspection.wsil file in your Web server's default directory and correct a minor problem, make the changes in boldface to the WsiCreator project's Form1 class:
//TextWriter writer = new
StreamWriter("c:\\wsil.xml");
TextWriter writer = new
StreamWriter("\\Inetpub\\wwwroot\\inspection.wsil"
, false);
XmlSerializer ser = new XmlSerializer(
typeof(InspectionDocument) );
ser.Serialize( writer, doc);
//Added to prevent exception on multiple
//executions
writer.Close();
Run WsiCreator and replace the default textbox values with the name, description, and URL for your services' WSDL document. Click on Add Service to add entries to the listbox (see Figure 5). WsiCreator doesn't check for valid URLs, so type carefully. When you're done, click on the giant Create WS-Inspection Document! button to write the inspection.wsil file (see Listing 2).
Bob Beauchemin's WSILFromDiscoLib C# library (see Resources) uses the Web.Services.Inspection classes to dynamically transform the content of DISCO files for XML Web services to a single WSIL document. Bob's project requires some effort to install and get running; follow his instructions in the IntegratingWS.doc file to the letter. I installed Bob's files in a \WSIL folder and set up a virtual directory named wsil. For this configuration, the URL to generate the WSIL document is http://localhost/wsil/inspection.wsil (see Figure 6 and Listing 2). If you have several services, it takes WSILFromDiscoLib a few seconds to generate the XML document.
Open the source WSIL document in Notepad and save it as inspection.wsil in the same location as default.wsdisco (usually \Inetpub\wwwroot). Then open the WSILReader project's Class1.cs file, change the URLToRead variable value to point to inspection.wsil, and comment out the Console.WriteLine("Abstract: {0}",s.Abstract.Value); line. (Run WSILReader.exe to display a list of services in the console. Bob's code is a good starting point for developing your own WS-Inspection-enabled projects.)
Web services are in their infancy, so it might be premature to spend scarce IT resources on evaluating alternative discovery mechanisms. On the other hand, efficient Web service discovery is critical to widespread deployment. IBM offers a WS-Inspection implementation (WSIL4J), but Microsoft doesn't. The same is true for private UDDI registries under Windows 2000; IBM's Web Services Toolkit 3.1 includes a UDDI 2.0 registry service and client tools. IBM goes the extra mile to deliver a starter implementation for WS-Security, while Microsoft's Don Box promises a .NET GXA update or toolkit "within our lifetime." I'm still not sure if Don meant his lifetime or mine.
Specifications without implementations are akin to taxation without representation. Microsoft taxes your brain with breathless GXA press releases and turgid specifications but doesn't provide Microsoft.Gxa classes and sample code to generate representations with Visual Basic .NET or C#. Does this make sense?