Service Station
Web Service Software Factory
Aaron Skonnard
Contents
As architects and developers, we always want to be confident that we're solving problems in the right way. For this reason, there has always been a demand for good guidance in the developer world. Often, this guidance has come from the community of developers, sharing and learning from each others' experiences. But nowadays, with so many emerging technologies, there's often very little communal experience to build on. This makes it increasingly important for software vendors to provide valuable guidance. After all, these vendors have designed and created the tools and technologies, so they should have good advice as to how to properly use these tools.
Guidance comes in many forms, but it can generally be divided into two types: written guidance and code-driven guidance. Written guidance is the most common type. It includes architectural overviews and whitepapers, general guides to patterns and practices (which are typically technology-agnostic), and guidance tailored to specific technologies in the form of primers and "how to" descriptions.
Code-driven guidance, on the other hand, takes the form of source code. It can be sample code or perhaps a complete reference implementation that demonstrates how numerous patterns come together in a real-world solution. Code-driven guidance can be a reusable library or an automated code recipe. Code recipes automate a particular development task, typically using designers or wizards to gather information from the developer for customizing the code.
To help developers, the patterns & practices (p&p) team at Microsoft works with product groups to develop
official Microsoft guidance for various technologies. The p&p team publishes all of these forms of guidance, including complex reference applications and code libraries, which are known as application blocks (such as the
Enterprise Library for the Microsoft® .NET Framework 2.0).
About Software Factories
The p&p team recently began publishing software factories, which take a more holistic approach to guidance. These are collections of guidance assets-tools, reusable code, documentation, reference implementations, and the like. They help automate the process of building software according to accepted patterns and predefined standards.
Generally speaking, a software factory is installed to extend your development environment, adding guidance-related tools and resources. For example, a software factory might include solution templates that make it easier to start a new application. And it might provide wizards and designers that you can use throughout the entire development cycle.
Software factories enhance the relationship between architects and developers. Architects can customize the various code recipes that are available with a software factory and then they can redeploy the customized software factory to development teams. This gives architects a practical mechanism for distributing their own guidance to developers.
A key aspect of software factories is automated tool support. While Visual Studio® has long been extensible via the Visual Studio Industry Partners (VSIP) program, this framework has been far from easy to use. So the p&p team created the Guidance Automation eXtensions (GAX) and the Guidance Automation Toolkit (GAT) to allow architects to more easily apply custom guidance to the Visual Studio experience.
GAX is a runtime built on VSIP and is used in extending Visual Studio with guidance packages. Meanwhile, GAT is a toolkit used for implementing guidance packages that run on GAX within Visual Studio. GAX must be installed if you want to use an existing guidance package, such as those found in the software factories. GAT, on the other hand, is only required if you are going to build guidance packages. (It's important to note that anyone can create new guidance packages with GAT. You can even start with an existing software factory, customize its guidance packages, and then rebuild them.) For more information on GAT, check out the "
Introduction to the Guidance Automation Toolkit".
Web Services Software Factory
The p&p team has recently released a few new software factories, including the Web Service Software Factory (sometimes referred to as the Service Factory), which I'll take a closer look at here. This software factory is designed to help developers build Web service solutions that consistently follow known architecture and design patterns.
There are two flavors of Service Factory: one for ASP.NET Web services (ASMX) and another for Windows
® Communication Foundation (which will ship with the .NET Framework 3.0). The ASMX version is officially supported and available today. The official release of the Windows Communication Foundation version will coincide with the official release of the Windows Communication Foundation. However, the Windows Communication Foundation version of the Service Factory is currently available as a
community release on the Web Service Software Factory community workspace found on GotDotNet.
Both versions install documentation and a complete reference application called the Global Bank Reference Application. Each also installs several guidance packages that provide Visual Studio automation. For example, the ASMX version installs two guidance packages-one for ASMX tasks and another for data access tasks. The Windows Communication Foundation version installs one for the Windows Communication Foundation tasks and another for security-specific tasks. The Guidance Package Manager (see Figure 1), which is available from the Tools menu in Visual Studio 2005, lets you enable or disable the available guidance packages.
To simplify this discussion, the remainder of this column will focus on using the ASMX Guidance Package. In a future column, I will cover the unique aspects of the Windows Communication Foundation Guidance Package.
.gif)
Figure 1 Guidance Package Manager (Click the image for a larger view)
Getting Started with Service Factory
When installed, the Service Factory creates a Microsoft patterns & practices | Web Service Software Factory item on the Start menu. Here, you'll find links to the various Service Factory assets. When you open Visual Studio 2005 and create a new project, you will find a project type called Guidance Packages. Each installed software factory provides templates that show up here. And if you have GAT installed, you'll see a package for creating new guidance packages (called Guidance Package Development).
Select Web Service Software Factory (ASMX) and one of its recipes is displayed as a template on the right. This recipe creates the initial solution structure according to the architecture prescribed by Service Factory. When you select the template and press OK, the recipe is invoked. This recipe first asks you for a prefix that it will use when naming each of the projects it's about to create (I've specified Coho.ClubServices.Membership as a prefix). When you press Finish, the recipe creates all of the projects; the generated solution is your starting point (see Figure 2).
.gif)
Figure 2 Generated Solution Structure
When you use a guidance package, Visual Studio provides a Guidance Navigator (see Figure 3). This allows you to navigate the various guidance assets made available by each guidance package you're using.
.gif)
Figure 3 Guidance Navigator
Prescriptive Architecture
The structure of the initial solution created by the guidance package complies with one of the prescriptive architectures defined by Service Factory. This architecture is primarily targeted at enterprise-level Web services. But remember, if the specifics don't match your needs, you can always customize the guidance package and modify the initial solution template.
The prescriptive architecture is divided into three layers: the service interface layer, the business layer, and the resource access layer. Note how these layers map to the generated solution structure shown in Figure 2. This architecture embodies the Layered Application pattern (described on the patterns & practices site), which greatly simplifies dependency management in large systems.
Each layer consists of different software components that are closely related to one another. The architecture also defines some concerns that apply to all of the layers-notably security, operational management, and communication. The overall architecture is illustrated in Figure 4.
.gif)
Figure 4 High-Level Service Factory Architecture (Click the image for a larger view)
The components of the service interface layer include the service contract and the service adapter. The service contract defines what operations the service can perform but it does not include any behavior, such as how the operation is actually implemented. This requires defining interfaces, which are groups of operations defined in terms of message exchange patterns. For each operation, you define the message types used in the exchange, and you define each message type in terms of the composable data types. The service adapter implements the service contract that is exposed on an endpoint (commonly referred to as the service host) and is responsible for adapting the endpoint to the underlying business layer.
The business layer consists of three components: business entities, business logic, and business workflows. Business entities are classes that model real-world, domain-specific objects. They are different than the data types used in the service contract because they include behavior and perhaps state. The architecture encapsulates business entities so that they are not exposed across a service boundary. This ensures more flexibility within each layer. It also gives you the opportunity to format the data in different ways, catering them to specific integration scenarios. However, this also means entity translation is necessary for moving between the layers.
The business logic implements the actual business behavior. These classes operate on the business entities to perform a desired action. Some business entities are quite simple while others take advantage of more complex logic.
Business workflows handle long-running processes that require sophisticated message correlation and state management. They are typically implemented with a business process management product, such as BizTalk® Server 2006 or Windows Workflow Foundation.
The business layer operates on the underlying resource access layer, which provides access to both data access logic and service agents. The data access logic provides everything you need for interacting with the underlying data store while the service agents provide everything you need to interact with external Web services. Figure 5 provides a more detailed view of how these layers and software components are related to one another. Each of these components maps to one of the projects found in your initial solution. As you can see, the scope of Service Factory is very comprehensive. It provides guidance that begins with the consumer and continues all the way through to the back-end data sources.
.gif)
Figure 5 Layer Components and Relationships (Click the image for a larger view)
Data Access Guidance
Service Factory includes the data access guidance package, which provides numerous recipes for automating common tasks in the data access layer. You typically launch recipes by right-clicking on a project and selecting the recipe from the Service Factory context menu. (There is one menu for each package enabled in a particular context.) You can also invoke recipes directly from the Guidance Navigator.
There are several common tasks that developers must perform to implement a data access layer. These tasks are often tedious and prone to error. One of the first recipes you'll want to use here is the Add database connection recipe. You can launch it by selecting it from the context menu in the Host project. This recipe asks you for a connection name and then has you specify the database connection details. Once you press finish, the recipe adds the specified connection string to the Host project's configuration file.
Then, assuming you already have your database model in place, you can generate a set of stored procedures that encapsulate typical operations (like select, insert, update, and delete) on a particular table in your database model. The recipe lets you choose the table and then you specify the name for each stored procedure operation (see Figure 6).
.gif)
Figure 6 Generating Stored Procedures (Click the image for a larger view)
These simple recipes take much of the pain out of generating a lot of the code that's required for integrating your services with an existing database model. Beyond merely generating code, however, they also provide you with confidence that the implementation is done in accordance with proven best practices. And, handily, you can always add more recipes to fulfill your specific needs.
Generating Business Layer Code
The data access guidance package also provides a recipe for generating the business entities that correspond to the underlying database model. You can invoke this recipe from the context menu on the business entities project. The recipe asks you to choose a database connection and then it lists all of the available tables and views. You then specify the tables and views you want to use and then, for each one, you can customize the names of each business entity class and the fields they contain.
The generated business entities classes model the design of the original table. The code that is generated contains a constructor for populating a new instance with supplied data, using properties to access the underlying fields representing the table columns. Although you can generate most of your business entity layer using this technique, you will surely need to extend or customize the generated code. The recipe generates these entities as partial classes, giving you a mechanism for extending or regenerating them safely without modifying the generated code directly.
The business logic project is where you have to manually write most of the code for this layer-your business logic classes should operate on your business entity classes. Since business logic is very specific to any particular application, there's not much that can be automated in this area.
You can, however, generate the data repository classes that know how to integrate between the generated business entities and the underlying stored procedures you generated. You use the Create data repository classes from business entities recipe for doing this. This recipe asks you to define a mapping between a particular business entity and a stored procedure, and then you define the name and type of each method you want to generate for the repository class. Once you've completed this, you have the classes necessary for moving back and forth between the data and business layers.
Service Layer Tasks
The ASMX guidance package provides several recipes that automate common service layer development tasks. Since the prescriptive architecture doesn't allow business entities to be exposed across service boundaries, the first thing you need to do in the service layer is define the various data types you use to construct messages.
The Create data type recipe allows you to define an XmlSerializer-compatible class annotated with the appropriate serialization attributes. And you can do this without touching any code. The recipe provides a heuristic (based on the project namespace, the year, and the month) for choosing XML namespaces when defining these types. Then it asks you to specify the data members that will make up the structure of the type.
If you already have existing XML Schema definitions, you can use them to define data types using a different recipe. Simply add the XML Schema file to the data type project, right-click on it, and select Create data type from the schema. This recipe gives you support for schema-first design scenarios in your development process.
Once you have all of your service layer data types in place, you can define your message types using the Create message type recipe. This is available in the service contracts project. The recipe asks you to name the classes to represent the request and response messages and then to specify the data types that will make up each message structure (see Figure 7). It then generates more XmlSerializer-compatible classes to represent the messages.
.gif)
Figure 7 Creating Message Type (Click the image for a larger view)
With all the message types in place, you're ready to design your service contract definitions with the Create service contract recipe. This recipe first asks you to specify the name and namespace of the service contract. Then you list the operations you want to support on the service contract. For each one, you specify the method name (the Action) followed by the corresponding request/response messages the operation maps to.
Once the service contract details are defined, you can instruct the recipe to generate the service implementation class (see Figure 8). The generated ASMX class will implement the service contract you defined earlier in the recipe.
.gif)
Figure 8 Generating Service Implementation Class (Click the image for a larger view)
The implementation of each ASMX WebMethod should invoke the business logic classes defined in the business layer. However, in order to do this, the WebMethods must first perform a translation between the service contract types and the business entity types used in the business logic. Since this is a common and tedious task, there is a recipe available for generating the translation code. This recipe, called the Create service contract translator recipe, is available on the service implementation project by default. It provides a user interface for defining the mapping between the two classes and it generates the code in a helper translator class. All you have to do then is use the generated translator classes within your WebMethod implementations before invoking the appropriate business logic.
After you're finished implementing the service and you're ready to expose it to the outside world, you run the Expose service recipe to generate the .asmx endpoint that references your ASMX implementation class. Now you're ready to test it.
Clients and Testing
You may have noticed that the original recipe that generated the solution structure automatically produced a client application that can be used as a test harness for the service layer. To make this client useful for your particular service scenarios, you may need to write a little code.
There are several Service Factory recipes for building and testing clients. For example, Service Factory provides an Add service reference recipe, a Debug client recipe, and a Run client recipe. There are also some testing-related recipes available on the service host, such as the View in browser and Debug host recipes.
Customizing the Solution
You might decide that the solution generated by Service Factory is overkill for your particular project. Or it simply might not be suited exactly to your organization's needs or standards. To address this, you can customize the solution structure by simply modifying what's generated by the original recipe and then reassigning project responsibility for the different layers in the prescribed architecture.
In order to reassign project responsibility, you must unlock the solution by selecting Unlock solution on the Service Factory menu. Then, right-click on service contract project and select Specify project responsibility. The resulting dialog allows you to easily assign various responsibilities (see Figure 9).
.gif)
Figure 9 Specifying Project Responsibility (Click the image for a larger view)
Once you're finished making changes to the solution, you relock it. You can also export the modified solution template so that you can potentially rebuild a customized version of the guidance package based on your modified solution.
Summary
The Web Service Software Factory provides valuable guidance assets that help increase speed, quality, and consistency when developing Web service solutions. It includes useful written guidance and a complete reference application that illustrates the prescribed architecture, patterns, and practices in action. In addition, the Service Factory provides several guidance packages that automate many common development tasks.
I recommend
downloading the Web Service Software Factory and checking out its many features. And check out the suite of hands-on labs on MSDN
® (available on the GotDotNet site) for a step-by-step walkthrough.
Send your questions and comments for Aaron to
sstation@microsoft.com.
Aaron Skonnard is a cofounder of Pluralsight, a Microsoft .NET training provider. Aaron is the author of Pluralsight's Applied Web Services 2.0, Applied BizTalk Server 2006, and Introducing Windows Communication Foundation courses. Aaron has spent years developing courses, speaking at conferences, and teaching professional developers. Reach him at
pluralsight.com/aaron.