TN_1106: Copying Endpoints vs. Creating Endpoints From WSDL

Bill Gibson, Program Manager
Microsoft Corporation

Application Designer supports two ways to copy the specification of a Web service endpoint onto an ASP.NET application. This note discusses each approach, their differences, and how you can use these to your advantage.

The Two Approaches

The first and most obvious approach is to use copy and paste. You can copy an application with its endpoints or copy one or more endpoints. If you copy multiple endpoints, they must be copied from the same application. You can copy between different Visual Studio instances, allowing you to copy endpoints between solutions. Web service endpoints can only be pasted onto ASP.NET applications.

The other approach is to use the Create Web Service Endpoint from WSDL feature supported on an ASP.NET Web Application. This can only be used when the original application is implemented. With this technique, you create new endpoints on your target application using the WSDL of the original endpoint. To do this, right-click the target application, select Create Web Service Endpoint from WSDL, and provide the URL of the source endpoint. A new endpoint will be created. The target application does not need to be implemented at this point.

How the Two Approaches Differ

In both cases, a shallow copy is produced in that the endpoint and operation definitions are copied, but no implementation code is copied.  This ensures a consistent experience pre-implementation and post- implementation. This is also consistent with the purpose of the application diagram to represent the specification of an application and not its implementation.

The differences lie in how each approach handles complex types referenced by an operation as return types or parameter types.  In the case of copy/paste, the operation and signature are copied, including the names of all referenced types. However, no new complex type definitions are created in the target application, and no references are created to assemblies or projects containing the types referenced by the original endpoint.

By comparison, if you create the endpoint from the WSDL file, this file and any referenced XML schema documents are processed, and new CLR type definitions are created for any complex types referenced in the message definitions.  If the target application is unimplemented, you will not be able to see or manipulate these new types until the application is implemented, but they are there! When the application is implemented, the appropriate classes are generated into the root project using the language chosen for the application.  If you create an endpoint from WSDL on an implemented application, the endpoint code, including any required classes, is generated immediately.

Using Copy/Paste

Copy/paste of an endpoint takes the view that the implementer of the target application will provide the definition of the parameter and return types out of band.  As the implementer, you can define the types from scratch, copy the type definitions from the source, or more interestingly, reference the actual type definitions used in the original application. 

Referencing types that are defined in the original application is, in most cases, not best practice as it creates a coupling between the two implementations. If common type definitions are to be used it is better if the types are defined in a third project, decoupling the implementations and allowing each to be evolved independently.

If you choose to reuse existing type definitions, once the application is implemented, add a reference to the assembly or class library in which the types are defined. This is all it takes for a pasted endpoint with complex types to compile. If you choose to define the types again from scratch, you obviously have a little more work ahead of you.

Using Create Web Service Endpoint from WSDL

Creating the endpoint from WSDL works rather differently.  This works the same way as the utility WSDL.exe /server and creates a 'fresh’ set of classes in the target application based on the types in the WSDL document and any imported XML schema documents.  This approach echoes the service-oriented architecture tenet of sharing schema and not types (although this tenet is directed primarily at avoiding implementation dependencies between consumers and providers of a service, not between providers).

When to Use Each Approach?

Each approach has its advantages and disadvantages. If you are investing effort in adding behavior to the message type definition, perhaps to handle data formatting or validation, and if the same behavior is wanted in each application, then it makes sense to reuse the same data type definitions so that this behavior is available. You will need to ensure that the behavior is not specific to the original implementation and inappropriate in the copy (although it would be easy enough to fork the implementation later if that was necessary). As mentioned above, if you are reuse type definitions, then it would not generally be considered good practice to leave the types defined inside the original ASP.NET application. This binds the copied application to the implementation of the original, not just to the common types.

If the original endpoint is only to be used as a template for similar but ultimately different behavior, the technique you use depends on how valuable any of the existing types are to the final endpoint design. Bear in mind that copy/paste preserves all the WSDL properties, so you will want to change the WSDL Binding Name and/or Namespace properties to indicate that the copied endpoint is of a different type than the original.

If you believe that message type definitions should just be used as a behavior-independent, data-formatting mechanism, there is no advantage in coupling the implementations. In this case, creating the endpoint from WSDL has the advantage of giving you an independent and immediately usable implementation.  

You can create an endpoint from the WSDL of any Web service, not just one included in your solution. So you can use this technique to copy an endpoint on an External Web Service, which doesn't otherwise support copy/paste.

Summary

Copy-and-paste and Create Web Service endpoints from WSDL offer two different approaches to duplicating the specification of an endpoint. Copy-and-paste is more appropriate when you plan to leverage the type definitions used in the source web service definition in your copy, and Create Web service Endpoint from WSDL when you plan to create a more independent copy.