Magazine > Issues > 2005 > August >  Service Station: The Application Connection Des...
Service Station
The Application Connection Designer
Aaron Skonnard

In some of my past columns on service orientation and contract-first development, I've mentioned the new suite of designers, formerly codenamed "Whitehorse," that are part of Visual Studio® Team edition for Software Architects Team System. The Distributed System Designers are the first Microsoft design tools that encourage developers to embrace contract-driven service-oriented architecture (SOA) development by offering a productive, user-friendly experience. Although they're comprised of numerous designers, I'll focus on the Application Connection Designer (ACD) because it provides the specific features related to designing service contracts. I won't, however, look at the Logical Datacenter Designer (LDD) or the various features related to deployment. For more information on the Distributed System Designers, check out the Visual Studio 2005 Team System References sidebar.
As you are reading, remember that this column and the various screenshots of the IDE included herein are based on the Beta 2 release of Visual Studio 2005.

Application Connection Designer
The ACD allows you to model designs for distributed systems. The distributed systems may include a variety of application types including Windows®-based applications, Office applications, Web applications, Web services, databases, and generic application types. One of the key features of the ACD is that it makes it possible to design the service contracts for communicating between these different application types without having to be familiar with the intricacies of Web Services Description Language (WSDL) or the particular implementation technology.
Once your applications and service contracts have been designed, the ACD makes it possible to automatically generate skeletons for the modeled applications, including the necessary ASMX code to implement the service contracts as per your design. It also generates the necessary proxy code for any applications designed to use the service. Then your job is reduced to simply implementing the generated WebMethod stubs with the appropriate business logic. And if you need to modify the service contract after generating code, not to worry, the ACD will automatically update the implementation projects keeping them in sync with all modifications to the service contract. This approach is a great example of contract-driven service development.
You can begin using the ACD by opening Visual Studio 2005 and creating a new Distributed System solution. You can do this by selecting New | Project, navigating to Distributed System Solutions. The Distributed System template gives you the ACD design experience.
Select the Distributed System template, specify the solution details and press OK to generate the ACD-based solution. Visual Studio will generate an empty solution that contains a single file with a .ad extension—this file contains the distributed system design information. You can open the ACD to begin designing your solution by opening the .ad file. Figure 1 illustrates what the empty solution looks like after generating the new project, with an open .ad file ready to go.
 Figure 1 Empty Distributed System Solution

The idea behind this experience is that you design the structure of the entire distributed system and the relationships between the different applications before writing any code. Once you've finished designing, the ACD will generate the code for you. However, until you use the code generator, there will be only a single .ad file within the solution. During the code generation phase, new implementation projects will be added to the solution automatically.
You design your distributed system on the design surface in the middle area where it says "Drag from the Toolbox to define applications." You can inspect the available application types in the ACD Toolbox shown in Figure 1. You can drag any of these application types to the design surface. You can also define endpoints on certain application types in order to design communication channels between apps. A connection between applications indicates that they'll exchange information according to a service contract.

Designing Service Contracts
You design service contracts within the ACD by designing Web service endpoints associated with application types. Only Web applications or Web services may have Web service endpoints associated with them. In fact, the only difference between a Web application and a Web service in the ACD is that a Web service has at least one Web service endpoint associated with it.
Once you have a Web service application type on the design service, you can give it a name and start specifying its properties. In order to help you visualize how this works, I'm going to walk you through the steps for building a sample distributed system that consists of a Web application that consumes several Web services. Let's start by designing a new Web service for reporting weather information. You can do this by dragging a Web service application type from the toolbox and dropping it on the design surface. Then you can change the name of the service by double-clicking on it and entering your desired name, in this case NewWeatherService, as shown in Figure 2.
Figure 2 Web Service Shape 
The shape on the design surface represents an ASP.NET Web service application. Note that the designer doesn't currently provide support for generating Web Services Enhancements (WSE) 2.0 implementations. The name you specify for the Web service will become the name of the ASP.NET Web service project once you generate the implementation code. It will also become the name of the virtual directory where the project code is published. Hence, if you want the project and code to go to a specific virtual directory location, make sure you have the virtual directory created ahead of time and use that name in the design.
If you right-click on the shape, you can inspect the various properties exposed by this application type (see Figure 3). For example, you'll want to specify the .NET-targeted language that will later be used to implement the project, and you may want to specify the name of the default class namespace used in the generated code, and so forth. The properties here are all related to the generated implementation code.
Figure 3 Web Service Properties 
Others will communicate with this Web service through the endpoints it exposes. A given Web service may expose multiple endpoints. In this case, a Web service endpoint is the combination of a service contract and the concrete binding details such as the type of encoding used by the service. You design the former and the ACD generates the latter. The little circle on the left border of the Web service shape (see Figure 2) represents an endpoint exposed by this service. Web service application types may define multiple endpoints if they need to support multiple communication channels.
You can begin designing the Web service endpoint by selecting it on the design surface and opening the Properties window. You'll notice that most of the properties are now related to WSDL details, such as the service and binding names and namespaces (see Figure 4), but it also asks you to specify the names of the Microsoft .NET Framework classes for implementing the ASMX endpoint within the project.
Figure 4 Endpoint Properties 
Once you've specified these WSDL properties, you can begin designing the endpoint contract by right-clicking on the endpoint and selecting Define Operations. This causes the Web Service Details window to appear, which gives you a contract designer for modeling the operations exposed by the endpoint (see Figure 5). The Web Service Details window provides a remote procedure call (RPC)-oriented design experience by modeling the endpoint operations like traditional methods with parameter lists, types, and modifiers. I've defined two operations in this example: one named GetForecast and another named GetForecastByDate, which differ only by a single parameter.
Figure 5 Endpoint Details 
The first thing you'll probably notice is that the types used here are .NET Framework types, not XML Schema Definition (XSD) types. This is a letdown for those who would have preferred a true WSDL-first development experience. You may also notice that I'm only using simple types in this example. You could theoretically specify .NET classes here, but I don't actually have any code in the solution yet—I'm still working in the completely abstract world of service contract design.
At this stage in the design, I think it makes more sense for the ACD to focus on the message design for each operation as opposed to a method-oriented signature. You could imagine an experience where for each operation, the designer lets you drop into the Visual Studio graphical XSD designer to model the input and output messages, or better yet, let you select from libraries of existing XSD types shared across your organization. The XSD types, rather than .NET types, would then show up in this view, and later when the code generator runs, it could generate the appropriate .NET types for each XSD type used in the contract. It's clear from recent design reviews that Microsoft is interested in moving the next version of the product in this direction.

Defining Application Connections
Once you've finished designing the endpoint details as shown in Figure 5, you have successfully designed a service contract without writing any code, or even angle brackets for that matter. Solution Explorer still only contains a single file at this point. Now you can define other applications that use the service by creating connections to the endpoint.
In Figure 6 I've created a new Web application prototype by dragging the Web application shape to the design surface. I've given it a name of WeatherSite and specified its implementation language as C#. Then, I selected the Connection tool from the toolbox and created a connection between the two applications. You do this by clicking on the target endpoint and dragging the line to the consuming application.Visual Studio 2005 Team System References

Figure 6 Endpoint Connections 
Although I've started with a simple one-to-one scenario, the designer supports having multiple applications connecting to a single service, or a single application connecting to multiple services. And I can use a variety of different application types from the toolbox to consume the service. As I continue to build up this sample, you'll be able to see some more interesting scenarios. At this point I've modeled the basic structure of two applications and a communication channel between them based on the NewWeatherEndpoint contract. In the next section I will commit to the initial design with some implementation code.

Generating the Implementation Code
You can have the ACD implement the skeleton projects for the applications in your distributed design by simply right-clicking on the design surface and selecting Implement All Applications. This will generate code for all the applications modeled in your design. When you select this option, a dialog will appear telling you which applications it's about to generate along with the implementation language and project location. (Figure 7 shows how this will look.) Once you press OK, the code-generation begins and you'll see new projects and files added to Solution Explorer. Once the code generation finishes, the application shapes on the design surface will now be accented by drop shadows. The drop shadows provide a visual indication that the applications have been implemented. Given this simple distributed design, your Solution Explorer will contain the files shown in Figure 8 after implementing the projects.
Figure 7 Confirm Application 
There are several things you should notice about the solution at this point. First, note that there is an ASP.NET Web services project providing the implementation for the NewWeatherService application in my design—it contains a single ASMX endpoint that's named NewWeatherEndpoint.asmx. Second, there is an ASP.NET project providing the implementation for the WeatherSite application in my design. It doesn't contain much in the way of ASPX code but it does contain a Web reference to NewWeatherEndpoint.asmx.
Figure 8 Generated Project Files 
At this point you can build the entire solution without any errors or warnings. Granted, the projects are essentially empty except for the code generated from the service contract. However, if you browse to NewWeatherEndpoint.asmx after building the solution, you should see something similar to Figure 9. If you click on the Service Description link, you'll see the WSDL definition that you designed using the operation designer. Even though you weren't typing in angle brackets all over the place while designing the operations, you were indeed authoring a WSDL contract that became the shared artifact between these two applications.
Then, if you open the NewWeatherEndpoint.asmx.cs file and inspect the source code, you'll notice that it generated the correct WebMethod signatures using the document/literal/bare style of ASMX attributes. The ACD code generator makes the generated .NET Framework classes concrete (as opposed to making them abstract like wsdl.exe /server does). This gives you an executable ASMX endpoint out of the gate, allowing you to browse to the documentation page, view the various operation details, and grab the official WSDL contract even though you haven't implemented the WebMethods yet.
If you inspect the WeatherSite project using the Class View, you'll find a proxy class that was generated from the same contract used to generate the ASMX code. This class is the mirror image of NewWeatherEndpoint.asmx, the proxy consumer for use on the client side. The point is that both projects contain code generated from the same predefined contract. At this stage, developers on both sides of the contract can begin working on their business-related implementation logic in parallel.
Figure 9 NewWeatherEndpoint.asmx 
Regardless of the amount of time you spend during the contract design phase, you're likely to change the contract after generating the implementation code. This is another area in which the ACD becomes extremely powerful. When you need to modify the contract, simply return to your distributed design in the ACD and modify the contract there. After committing the changes, the ACD will automatically update all implementations of the contract, whether it's in a client project (like WeatherSite) or an implementation project (like NewWeatherService). This key feature gives you an iterative development process driven completely by contract design.

Implementing Existing Service Contracts
There's another common service-oriented design scenario that I haven't addressed yet—that of implementing an existing service contract. For example, assume that the contract for the weather service has already been defined by an industry standards body or by another team within your organization and it's your job to provide an implementation that conforms to the predefined contract.
The ACD provides built-in support for this scenario by providing an option to create a Web service endpoint from an existing WSDL definition. You can do this by right-clicking on any Web app or Web service shape found on the design surface and selecting "Create Web Service Endpoints from WSDL". Then the familiar Add Web Reference dialog appears asking you to specify the location of the existing WSDL contract. After you locate the WSDL and press Add Reference, the ACD will generate an endpoint on the app using the information found in the WSDL definition.
If you select the generated endpoint on the designer and view the endpoint details, you'll notice that all of the contract operations have been imported from the WSDL. You shouldn't have to make any changes at this point if your goal is to conform to the predefined contract. In this case you can go straight to the implementation by right-clicking on the Web service shape and selecting Implement—this will only implement the single project for the new Web service application.
Figure 10 Implementing an Existing Service Contract 
You can connect this Web service with other applications using the Connection tool like before. When you connect endpoints to applications that are already implemented, the ACD will automatically generate the proxy code and add it to the consuming applications. Figure 10 shows what my sample looks like after following these steps—ConformingWeatherEndpoint implements an existing WSDL definition that I provided and the WeatherSite project now contains the proxy code for it. Like before, you would implement the operations in this Web service by opening the generated ASMX code and finishing the stubbed-out WebMethods.

Consuming External Services
The ACD also makes it possible to design connections with external Web services, that is, services whose implementations you don't control. The toolbox contains an External Web service application type for doing this. When you drag it onto the design surface, the Add Web Reference dialog immediately appears asking you for the external Web service's WSDL definition. Once you provide the location and press Add Reference, it adds the new shape to the design surface and it contains an endpoint definition that corresponds to the downloaded WSDL definition.
The shape for external Web services is a different color than the others to provide a visual cue that you don't own the contract or implementation. When you select the generated endpoint and view the endpoint details, you'll also notice that the endpoint contract is read-only. You obviously shouldn't be able to modify the contract since it's controlled by another party. Thus, when you right-click on the shape, you won't see the Implement option anymore.
The only reason you have the External Web service on the design surface is so you can establish connections to it from your other applications. When you do so, the ACD will automatically generate the proxy code in the consuming application based on the WSDL definition associated with the shape. Your job, then, is to author the application logic that consumes the external service—you'll want to use the Class View again to inspect the generated proxy code along with any documentation provided by the external service.
I've done this in the sample and called the new shape ExternalWebService. I pointed the Add Web Reference dialog to a weather service found on www.xmethods.com and called the generated class ExternalWeatherEndpoint. Then I established a connection to it from the WeatherSite application creating the design that is illustrated in Figure 11. Now the WeatherSite application can communicate with three distinct services, two of which are part of this distributed system implementation and one that happens to be controlled by an external party.
Figure 11 Implementing an External Web Service 
The design shown in Figure 11 is truly an example of service-oriented development and contract-driven development. The design emphasizes the distinction between services and other application types, and the service contracts that drive the system. The contract definitions are what then drive the code-generation process along with continued synchronization support for contract changes and an iterative development process.

State of the Art
The Application Connection Designer that ships with Visual Studio Team System is a great first-step towards a true contract-driven, service-oriented design experience. Using the ACD you can design systems that define new contracts, implement existing contracts, and consume external contracts without writing any code. You can also define contract-based connections between a variety of different application types used in your systems. After designing your system, you can utilize the ACD to generate the skeleton projects around your contracts and continue to keep the code synchronized as the contracts evolve. You should keep your eye on this application designer as it continues to evolve in future releases of Visual Studio.

Send your questions and comments for Aaron to  sstation@microsoft.com.


Aaron Skonnard is a co-founder of Pluralsight, a premier Microsoft .NET training provider. Aaron is the author of Pluralsight's Applied Web Services, Applied BizTalk Server 2004, and Introducing Indigo courses. Aaron has spent years developing courses, speaking at conferences, and teaching professional developers. Reach him at pluralsight.com/aaron.
Page view tracker