TN_1103: Web Service Endpoint Name Propagation

Bill Gibson, Program Manager
Microsoft Corporation

Renaming a Web service endpoint on an ASP.NET Web Application using the Application Designer provides a great demonstration of the power of a model-based design tool. This note explores what endpoints are, how they abstract details of the implementation, and what happens when you make a simple yet fundamental change to the abstraction, such as renaming an endpoint.

Models Hide Detail

Models provide us with a higher-level view over artifacts of some kind and allow us to think about specific aspects of these artifacts without being immersed in all the detail. The Application Designer and System Designer allow us to think about applications, specifically to consider their behavior, packaging and connections, without considering how they are implemented. Even when we consider their implementation, other tools like the Class Designer allow us to think about the structure of the implementation without being immersed in all its details.

The Application Designer and System Designer are based on the System Definition Model (SDM), which has been extended with a model of Web service behavior. These models, combined with two-way model/code synchronization, allow us to think about the high-level design, deployment, and management of Web service applications without sacrificing any of the flexibility and power of code for defining their implementation.

In some cases, a single concept in a model may be manifested by multiple underlying artifacts. One of the challenges in maintaining synchronization between models and the world they represent lies in managing changes to the model and propagating these to the underlying artifacts.

Understanding Applications and Endpoints

In SDM, an application is an abstraction over a set of resources, such as binaries, XML files, resource files, and so on, that are deployed together as a unit. An endpoint on an application describes a connection point through which the application offers access to its resources to other applications or accesses the resources of other applications. For a further information, see Understanding Applications and the Application Diagram.

Web Service Endpoints

A Web service provider endpoint represents the connection point to a specific Web service offered by the application. In an ASP.NET Web application, a Web service endpoint is manifested in several artifacts in the implementation typically as follows:

• An .asmx file located in the Web site that can be accessed via HTTP and that provides the address of the Web service.
  
  
• A Web service implementation class.
  
  
• A Web service class file containing the Web service class.
  
  
• A WSDL Service attribute on the service class.
  
  
• A WSDL Binding attribute on the service class and on each Web method.

While the endpoint represents an abstraction over these artifacts and properties, you are still able to exert control over these through the model – particularly the names used for each. However, in the spirit of abstraction, this level of detail is optional. By default, the names chosen for each of these is based on the endpoint name. As the default endpoint name WebService1 is likely to be changed further, changes to this name need to be propagated to the other properties to maintain the abstraction. Before implementation, this propagation takes place solely within the model. After implementation, the propagation requires synchronization with the underlying artifacts listed above.

To control name propagation, a ‘tree’ is defined in the model. This describes the sequence in which the names propagate from property to property in the model. Thus, a change to the endpoint name propagates to the Web service class name, from there to the Web service class file name (if implemented), to the WSDL Service Name property and .from there to the asmx file name, and the WSDL Binding name. Changes to the WSDL Service Name and Binding Name properties are synchronized with attributes in code, if the endpoint has been implemented. If the application is implemented, the class name propagates to the class file name. The propagation tree is illustrated below.

Figure 1. The endpoint name propagation tree.

Name propagation occurs down the tree only. Changes to element names lower in the tree are not propagated to names higher in the tree. Propagated changes also only occur if the initiating change is made via the designers in the model. In no case does a change made to code trigger name propagation in the model and thus to code. While potentially valuable, this would be unpredictable would only happen if the designers were open, and would be very disturbing to anyone not expecting it!

Name propagation is based on successive elements in the tree having the same name before a change is made. This simple approach means that the propagation tree can be broken by changing the name of any element beneath the topmost node in the tree. This breaks the chain at that point—propagation occurs above and below the break but not across the break. You can heal such breaks in the tree simply by renaming adjacent items so they are the same again.

The name of an element can be changed via the Properties window (accessed from the Application Designer) or by changing the corresponding entity in code.

Name Propagation in Action

Try the following demonstration to see this in action. With the Application Designer, add an ASP.NETWebApplication using the ASP.NETWebService prototype in the toolbox. Notice the default name used for the endpoint is WebService1. Select the endpoint and look at the properties of the endpoint. Notice that Implementation Class Name, WSDL Service Name and the WSDL Binding Name properties in the Properties window have the value WebService1 also. Now click on the endpoint label on the diagram and change the endpoint name to MyService. Click on the endpoint again and note how these properties have also been changed.

Now add two operations, Operation1 and Operation2, to the Web service using the Web Service Details window. You can right click on the endpoint and choose Define Operations from the context menu to open the window.

Now implement the application using your choice of language (Visual Basic is the default). Look in the Solution Explorer for the generated project and notice the name of the .asmx file and code files created. Now open the code file for the Web service by right-clicking the endpoint on the diagram and choosing View Code from the context menu. You can also double-click on the endpoint node or an operation node in the Web Service Details window. Look at the Web service binding attribute on the class and the corresponding attributes on each method—all are named MyService.

Now return to the diagram and again change the endpoint name, this time to NewEndpoint and watch the sparks fly. Review the Properties window entries again, then browse the file names in the Solution Explorer, and revisit the code to see the impact of the change.

Finally, break the propagation tree by selectively modifying the names of elements in the Properties window and in code and see the effect this has. For example, change the Web service class name to MyServiceClass, rename the endpoint, and note the different propagation that results, first from changing the class name property and then the endpoint name.

Summary

Name propagation among artifacts, for example, when renaming a Web service endpoint in the Application Designer, demonstrates the ability of a model and designers to provide a simplifying abstraction over code and artifacts. Name propagation is driven hierarchically by a tree of properties and occurs when adjacent properties in the tree have the same name. Propagation can be controlled by manually editing the properties or by changing the equivalent concept in code to break links in the tree.