TN_1102: Designing Substitutable Web Services

Bill Gibson, Progam Manager
Microsoft Corporation

Why Create Substitutable Web Services?

A key benefit of interface-oriented programming models is that they allow you to substitute one implementation of an interface for another. This capability makes it possible for you to perform the following tasks:

• Enable client applications to be tested with a stubbed-out version of a service.
  
  
• Create alternative implementations with different performance, persistence, or other characteristics.
  
  
• Substitute implementations from different sources.
  
  
• Implement common behavior, such as a common audit or tracking interface.

A Web service defined by a contract is a special case of an interface-oriented programming model that allows loose and late binding through message schemas rather than implementation types. This binding model makes it easy to substitute one service for another with no need to even recompile the client. Substitution requires no more than switching a service URL entry in a configuration file to substitute one service for another.

Several features of the Distributed Service Designers make the design and testing of substitutable Web services easy and are the subject of this note.

The interface definition of a Web service, often referred to as a contract, is expressed and shared externally using WSDL (Web Service Description Language). A WSDL document describes the operations and messages supported by the service.

Three Ways to Define an Asmx Web Service

There are three common ways to create an ASP.NET (ASMX) Web service:

• Start with an existing WSDL contract and create an ASMX implementation from it.
  
  
• Define the behavior with the Application Designer using its combined WSDL- and .NET-based abstractions.
  
  
• Program directly in the ASMX programming model, managing all aspects of the service implementation and contract yourself with attributes added to classes and methods.

You need do very little to create a skeleton service implementation from a pre-defined WSDL document. You can use the WSDL.exe utility with its ‘/server’ switch and tidy up the results and add an .asmx file, or you can use a built-in feature in the Application Designer that effectively does the same as WSDL.exe (only it creates the implementation in a project and creates an .asmx file for you).

Alternatively, you can use Application Designer to design the service operation-by-operation, specifying message definitions using CLR types. The design view and code are synchronized automatically once you implement the service, so that changes you make using either method are immediately reflected in the other. The design tool hides the detail of the attribute model and lets you focus on defining the behavior.

If you choose to define the service entirely in code, then it is up to you to manage the service and endpoint abstractions using attributes, which is not difficult but can be tedious and error prone. If you use code, then it is recommended you define the contract using an interface with ASMX attributes as it makes reuse simpler, especially if you plan to create multiple substitutable services.

While you can use all three approaches to define substitutable services, this note describes only those supported by the Application Designer.

Creating Substitutable Services from WSDL

If you create multiple Web services that conform to the same WSDL file, they are by definition substitutable. There are two slightly different WSDL scenarios. In the first scenario, you start with a WSDL file and ‘stamp out’ multiple service implementations from it. In the second scenario, you start with a ‘reference’ Web service and create another that implements its exposed WSDL contract.

In the first scenario, add a new ASP.NetWebApplication to the application diagram using the ASP.NETWebService toolbox prototype and then delete the default endpoint. This ensures you have the EmptyWebSite project template. Right-click the application, choose Add Web Service Endpoint from WSDL, and specify the location of the WSDL file. Note that the file must be a valid WSDL document with a single SOAP 1.1 endpoint. It must also contain valid WSDL Service and Port entries with the port address specified. The service is not invoked by this process, so if you have a WSDL document without these entries and they have to be added manually, any location value can be specified!

In the second scenario, you clone the behavior of an existing Web service using its WSDL. This requires that the Web service supports the ?WSDL request to return its WSDL contract. ASMX as well as other kinds of Web services support this. Use the same technique as before to add the endpoint, only use the address of the service’s endpoint as the WSDL location.

Creating Substitutable Web Services using Copy and Paste

Another approach is to copy and paste an ASP.NET application with its endpoints to create a substitutable application, or copy just the required Web Services endpoint(s) onto an existing ASP.NET application to make it substitutable on the copied endpoint. Note that you cannot copy an external web service or the endpoint on an external service, so use the WSDL technique instead.

Copy and paste always creates a shallow copy of endpoints—no code is copied. The operations and their signatures are copied as well as its WSDL and other properties. This ensures that copied endpoints are substitutable. There are some notable differences between the result of using copy and paste on an endpoint and creating a Web service endpoint from WSDL, which are discussed in another note <reference to note on copy and paste vs. Create Web Service Endpoint from WSDL.

Substituting One Service for Another

Having created or located substitutable services, the Application Designer and System Designer can be used to actually substitute one for another. The Application Designer provides a view over your solution so changes to this diagram are reflected immediately in the configuration of projects in your solution. In the System Designer, changes are reflected when you deploy the system based on its definition.

Substitution on the Application Designer

Substituting a service in the application diagram requires that you delete the connection between two Web services endpoints and then reconnect the consumer endpoint to an appropriate provider endpoint on the substitute service. You are warned if the WSDL Binding Name and Binding Namespace properties on the two endpoints are different; however, this can be ignored if you know the services are substitutable. This simple type checking reflects the convention of using the Binding Name and Namespace to identify the type of a service. (All the techniques described above create services with the same WSDL Binding Name and Namespace values, so they won’t produce the warning.)

When you reconnect the consumer endpoint on an implemented application to a new provider endpoint, you are asked if the connection is permanent or temporary. If permanent, the Web service proxy is regenerated from the newly connected service. This ensures that further changes to the service are automatically reflected in the proxy. If temporary, then only the configuration file is updated with the URL of the new service. This is appropriate if you wish to verify that a service is a valid substitute without modifying the client.

Substitution on the Service Designer

A service can be substituted in place of another in a connection between members or in a delegation between a system and member endpoints. The same type checking occurs as before with the same caveats about ignoring warnings.

If you substitute a service in a connection, simply delete the existing connection and make the new connection. You can make the connection by moving the mouse over one endpoint, pressing the ALT key, and dragging the connection.

If you substitute a service in a delegation, do not delete the delegation as that deletes the system endpoint, which can have a ripple effect in other systems. Instead, simply connect the system endpoint to the substitute endpoint, and the delegation will be ‘moved’ in a single action. This is useful when designing systems from the top down. For more information about moving a delegation, see Top-Down System Design.

Summary

The Distributed System Designers support several ways in which you can create and substitute alternative implementations of the same contract.