Using the DCS Software Factory to Create Services

Article
10/27/2009

The DCS Software Factory provides a guidance-based development model for DCS solutions, and implements a number of Visual Studio extensions to help you quickly develop the functionality that your service requires. The DCS Software Factory provides templates with customized menus and recipes that can help to guide you to design and develop a service based on the four workflow models implemented by the DCS runtime.

The following procedure describes how to create a new DCS solution in Visual Studio by using the DCS Software Factory. You can then use this solution to implement the messages and operations required by your service.

To create a new DCS solution project

Start the Microsoft® Visual Studio® development system.
On the File menu, point to New, and then click Project.
In the New Project dialog box, under Project types, under Guidance Packages, click the DCS BL VSExtensions node.
In the Templates pane, click DCS Solution.
Provide a name and location for the project in the relevant text boxes, and then click OK to create the project template.

Using the DCS Software Factory to Create Operation Implementations

When you implement a service, you use a combination of the following project templates that are provided in DCS.

Messages
Stub
Task
BLSpecific
BLCategory

DCS Messages Projects

A DCS Messages project contains the messages that pass between a client and a service. In the Messages project, you define Request messages that the client application instantiates and sends to the service, and Response messages that the service instantiates and sends to the client. For more information, see Defining Request and Response Messages.

A Messages project also contains the Exception and Error classes that the service requires. Exception classes define the exceptions that an operation might throw at run time. The Error class acts a wrapper around a serialized Exception class, enabling DCS to pass the exception to the client. For more information, see Defining Exception and Error Classes.

You can use a Messages project for any of the workflow execution models, and you can use a single Messages project for your entire service solution. This provides a single, central repository for all service messages. Alternatively, you can create message classes in the same space as the operation that requires them.

DCS Stub Projects

A DCS Stub project lets you define the operations that the operation exposes, without requiring you to implement the operation functionality. This lets you define enough information to form the service contract without spending time implementing the actual functionality of the service. You can then deploy the service contract and create a proxy object. Developers can then create client applications that invoke service operations, while you continue to implement the service functionality separately.

You can use a DCS Stub project to define operations that expose specific, conversational, and transparent processes. However, you cannot create category operations outside of the BLCategory project type.

DCS Task Projects

A DCS Task project lets you implement operation functionality for a service contract. After you create a Stub project that contains a service contract, you create a Task project that contains the functionality executed by the service when an operation is invoked. You can also use Task projects to create multiple implementations of a task.

You can use a DCS Task project to implement specific, conversational, and transparent processes that map to operations defined in a DCS Stub project. If necessary, you can also create tasks based on operations defined in the BLSpecific project.

BLSpecific Projects

A BLSpecific project lets you create a complete service instance that links stub and task project elements with message classes in the same C# project. This forms a tightly coupled service implementation. A BLSpecific project lets you group operation definitions and task implementations, and you can create operation messages inside the BLSpecific project. This increases the coupling between service contract, contract implementation, and messages. However, it makes concurrent development impossible due to the use of a single project.

You can create conversational and specific workflows in the same project without conflict. You can also implement specific workflows that extend from category workflows. Although you can create transparent workflows in a BLSpecific project, you must create them in a separate project from other workflow types.

BLCategory Projects

A BLCategory project lets you define category workflow operations that link category operation definitions and task implementations with message classes in the same project. You can create only category workflow operations in a BLCategory project. This is because the BLCategory project does not enable deployment in the same way as a BLSpecific project. Instead, category workflows are deployed when a specific workflow that refers to the category workflow is deployed. You can create any number of category workflows in the same BLCategory project

Software Factory Folder Structure

A default DCS Software Factory solution contains several folders that relate directly to the different DCS project types. These folders filter the Visual Studio Extensions that DCS provides, depending on the type of project to which they relate.

The following table contains a list of the folders found in a standard DCS Software Factory solution, and a description of the project type related to the folder.

Folder Name	Related Project Type
BLCategory	The BLCategory folder contains the extensions related to building and deploying category workflow implementations.
BLSpecific	The BLSpecific folder contains extensions related to building and deploying specific, transparent, and conversational workflow implementations.
Messages	The Messages folder contains extensions related to the creation of central message repositories where you define the request, response, error and exception messages used to invoke your service operations.
Stub	The Stubs folder contains extensions related to the creation and deployment of service contracts, where you define the operations that a service must expose.
Tests	The Tests folder contains extensions related to the creation of unit tests.
WF Task	The Tasks folder contains extensions related to the creation and deployment of operations, where you implement tasks for the operations exposed by your service.

Note

You should create the projects for your solution in the appropriate folder for the project type. For example, you should create messages in the Messages folder and BLSpecific services in the BLSpecific folder. If you do not use the appropriate folders for the projects, then the recipes provided by the DCS Software Factory will not be available for the projects.

Common DCS Files

There are some files in DCS Solutions that are used in several model implementations. The following table lists these files and describes how they are used.

File Name	Description
Message files	DCS lets you define messages either in a central message store or in the operation to which the message is related. A message class represents a unit of communication that passes between the service and the client, and contains required parameters for operation invocation or return values.
Workflow files	A workflow file contains workflow implementation logic configured as a standard Windows Workflow Foundation (WF) workflow. DCS generates workflow files when you create an operation implementation, either in the BLSpecific or BLCategory projects for tightly coupled solutions, or in the Task project if you implement stubs and tasks separately. You use the workflow file to design your workflow functionality by dragging activities onto the designer to build the workflow. You use the workflow code-behind file to add any code that your workflow requires.
Envelope files	The workflow envelope file is a class that wraps around a workflow, enabling DCS to invoke it correctly. DCS generates the workflow envelope file when you create an operation implementation. The code uses a WorkflowHost controller to start and control the workflow implementation related to the envelope class.

Message files

DCS lets you define messages either in a central message store or in the operation to which the message is related. A message class represents a unit of communication that passes between the service and the client, and contains required parameters for operation invocation or return values.

Workflow files

A workflow file contains workflow implementation logic configured as a standard Windows Workflow Foundation (WF) workflow. DCS generates workflow files when you create an operation implementation, either in the BLSpecific or BLCategory projects for tightly coupled solutions, or in the Task project if you implement stubs and tasks separately.

You use the workflow file to design your workflow functionality by dragging activities onto the designer to build the workflow. You use the workflow code-behind file to add any code that your workflow requires.

Envelope files

The workflow envelope file is a class that wraps around a workflow, enabling DCS to invoke it correctly. DCS generates the workflow envelope file when you create an operation implementation. The code uses a WorkflowHost controller to start and control the workflow implementation related to the envelope class.

DCS Service Best Practices

The structure of DCS Software Factory solutions enables several developers to work on individual sections of a solution simultaneously. For example, while one developer implements the category workflow implementations required for a service in the BLCategory project type, another developer can implement the Messages project for the entire service. When individual sections are completed, you can export projects from the development system and import the separate implementations into a single unified project. For more information, see Importing and Exporting Projects.

DCS implements service functionality as a series of operation contracts exposed by the service and task implementations that the DCS runtime invokes when a client application consumes an operation. When you use the Visual Studio Extensions to generate one of the workflow types, you can use the BLSpecific or BLCategory project types to generate operation contracts and task implementations. This provides a tightly coupled solution, where you implement the contract and task at the same time and in the same namespace.

While this is a useful paradigm to use for smaller services, there may be times when you want to create a single operation that can invoke one of several task implementations. For example, you might need to enable different functionality depending on the locale of an incoming request, or you might need to reuse the same task implementation in multiple service implementations. In addition, you might need to separate the operation contract from the code for the service, so that another developer can work on the client application while you complete the service functionality. You can use DCS Stub projects and Task projects to separate the operation contract definition from the task implementation to provide advantages at design time and run time.

You use a DCS Stub project to define your operation contracts, which also includes the service definition code. When you build the Stub project, you create a service proxy that a client application can use to invoke a service, This approach enables a developer to work on client applications while you continue to work on the service implementation. For more information, see Building a DCS Stub.

A DCS Task represents the implementation code for a DCS operation. You define an operation contract in a service, and then provide tasks to implement those operations. You create an instance of the Tasks project to contain your task implementations, and then reference an operation stub when you create the task implementation.