Designing with the Models

To make the best use of the models in the Service Factory, you should know something about how they were chosen and what design principles were applied as they were being built. The scope of each of the models chosen was defined to optimize reuse in the design. This point will be further explained in the following sections.

Also, not all services are built the same way, but you almost always start with whatever artifacts you already have. For example, you may already have some XSD files that define the messages, you may know what behaviors the services must support, or you may begin with the data the services will send and receive. The Service Factory models support starting with what you currently have.

Service Contract Model

By using the Service Contract Model, you can model single services and the elements that make up that service: service contracts, operations, and messages. Multiple services can exist on a single design surface, but the interaction between those services cannot be modeled without changing and rebuilding the Service Factory source.

The available tools in the Service Contract Model are listed in the upper-left corner of Figure 1. The right side of Figure 1 illustrates these tools in use on the design surface. You can notice in that the operation shape is represented as its own shape instead of being a line item in the Service Contract shape. This was done intentionally so the Web service developer can model all the necessary behaviors without having to know ahead of time how many services are needed.

Figure 1
Service Contract tools and Service Contract designer

The Service Contract tools are the following:

• Service. Represents the implementation of the contract. Unlike class definitions, this shape is not intended to implement multiple service interfaces (contracts). This shape can only connect to a single service contract. This is the element the Host Model will reference.
• Service Contract. Represents the service interface that associates multiple operations (methods). This shape connects to a single service shape and can connect to multiple operation shapes.
• Operation.****Represents a method that can be invoked on the service. This shape connects to a single service contract and one or two message contracts.
• Message.****Represents a request or response message that contains data contracts or primitive types (not types from an XSD). This shape connects to a single operation. To make it a request message, drag the connector shape from the message shape to the operation shape. To make it a response message, drag the connector shape from the operation shape to the message shape.
• XSD Message.****Represents a reference to an element or a complex type within an XSD file that represents a request or response message. To use this shape, you need to add a schema as an existing item to the Schemas folder of the solution. This shape connects to a single operation. To make it a request message, drag the connector shape from the message shape to the operation shape. To make it a response message, drag the connector shape from the operation shape to the message shape.
• Connector.****Makes valid connections between**shapes on the design surface. To use the connector, click the Connector shape in the Toolbox, click the first shape, and then click the second shape. For more information about connecting message shapes, hover over the Message or XSD Message shapes in the Toolbox.

The design surface of the Service Contract Model has two properties that are significant during the design stage:

XML Namespace. This is the same value you provide in the New Model dialog box when you created the model. It represents the default namespace for this model and will be applied to any shape added to the model. The value can be changed at any time to a valid URI, but it will only influence shapes added to the model after the change. Any shape's XML Namespace property can also be changed manually without affecting other shapes.

Serializer Type. The Service Factory supports two serializers:

• XMLSerializer. This serializer is supported by both ASMX and WCF and is also more likely to work with an existing XSD file.
• DataContractSerializer. This serializer is supported only by WCF and generally provides higher levels of interoperability and performance, but is not compatible with most XSD files.

Choosing the serialization engine is arguably an implementation decision, but it is also important to consider this value during the design stage. The Serializer Type property applies to all operations and message on this model and it must be consistent with the Implementation Technology property of any Data Contract Models referenced from the messages. The impact of this property is more obvious when using the XSD Message element.

Using the XSD Message Element

If the XML Schema file was not built specifically for the DataContractSerializer, it will not likely be supported. The Serializer Type property applies to the entire model and the use of XML Schema files will influence your decision on serializers.

Figure 2 illustrates a common WCF scenario that will not work. This is problematic because the XML Schema file is not compatible with the serializer type. If the Serializer Type property is changed, it will not be compatible with the Implementation Technology on the Data Contract Model.

Figure 2
An unsupported WCF scenario with an XML Schema file

This means you have three options when you are using XML Schema files:

• Partition the services across models. If you know you will be using WCF, try to use the DataContractSerializer as much as possible. To do so, if the XML Schema files are not compatible, factor the Service Contract Models so all the XML Schema files are on their own models and do not link to Data Contract Models that use the WCF Implementation Technology.
• Use XML Schema files that are compatible. Using XML Schema files and linking to WCF Data Contract Models is okay when the XML Schema files are compatible with the DataContractSerializer. For information about XML Schema support in data contracts, see Data Contract Schema Reference.
• Use the XmlSerializer. If you are unable to apply one of the previous options, using the XmlSerializer is a viable option. To do this, you must also choose ASMX Extension for the Implementation Technology property even if this value is WCF Extension on the Service Contract Model. For more information, see the next section, “Data Contract Model.”

Defining Message Part Collections

Message parts collections can be defined in two different ways:

• The “Is Collection” property on a primitive message part. Using this option simply applies the chosen collection type generic to the type when it is generated. This type will not be available to other messages.
• The collection types on the Data Contract Model. If the collection part will be reused, add a Data Contract Message Part to the message and reference an element on the Data Contract Model. The Data Contract Model provides both primitive and complex collections as described in the next section.

Choosing the right option depends on whether the collection will be reused in other messages or on other operations and services.

Data Contract Model

By using the Data Contract Model, you can model data and fault contracts that can be reused across services and operations. The available tools in the Data Contract Model are listed in the upper-left corner of Figure 3. The right side of Figure 3 illustrates these tools in use on the design surface.

Figure 3
Data Contract tools and Data Contract designer

The Data Contract tools are the following:

• Data Contract. Represents a serializable type that can be reused across multiple services. Its members can be primitive types, enumerated types, other data contracts, and collections. This shape connects to other data contracts, data contract enumerations, primitive data type collections, and data contract collections.
• Data Contract Collection. Represents a serializable collection that can be reused across multiple services. To specify what type this is a collection of, use the Data Contract property for the collection. To do this, drag a Data Contract shape onto the design surface, drag a Data Contract Collection shape onto the design surface, select the Data Contract Collection, and then click the data contract type in the Data Contract drop-down list in the Properties window. To specify how this collection should be represented in code, select the Implementation Technology on the design surface, and then choose a CollectionType (for example, List<T>) for the collection shape.
• Primitive Data Type Collection. Represents a serializable collection of a primitive type that can be reused across multiple services. To specify what type this is a collection of, use the ItemType property in the Properties window. To specify how this collection should be represented in code, select the Implementation Technology on the design surface, and then choose a CollectionType (for example, List<T>) for the collection shape.
• Data Contract Enumeration. Represents a serializable enumeration that can be reused across multiple services. After adding the Data Contract Enumeration to the design surface, add new values by right-clicking the Values label on the Data Contract Enumeration shape.
• Fault Contract. Represents a serializable SOAP fault that can be reused across multiple services. Its members can be primitive types, enumerated types, other data contracts, and collections. This shape connects to other data contracts, data contract enumerations, primitive data type collections, and data contract collections.

Host Model

By using the Host Model, you can model the host application, service endpoints, and client/proxies. Figure 4 illustrates the Host Designer and the tool windows used to interact with the model. The Host Explorer window in the top right of the figure is used for adding, removing, and selecting model elements. The contents in the main window and the Properties window are driven by the element selected in the Host Explorer window. The main window in the figure is split into two panes. The upper pane provides a way to generate code after the model is valid, and the lower pane describes the currently selected element and how to add new child elements to it. To get started, use the Host Explorer to add a host application and a client application. To do this, right-click the top-level Host Model element, and then click the appropriate menu item.

Figure 4
View of the Host Model

The Host elements are the following:

• Host Application. Represents the application that will accept request messages and send response messages. The host application contains one or more service references. To add a service reference, using the Host Explorer, right-click your host application, and then click Add New Service Reference.
• Service Reference. Associates the service implementation shape from the service contract designer with the application that will host the service. A service reference contains one or more endpoints. To add an endpoint, using the Host Explorer, right-click your service reference, and then click Add New Endpoint.
• Endpoint. Describes in a standard-based way where messages should be sent, how they should be sent, and what the messages should look like.
• Client Application. Represents the application that consumes the service. The client application contains one or more proxies. To add a proxy, using the Host Explorer, right-click your client application, and then click Add New Proxy.
• Proxy. Represents the part of the client application that consumes the service.

Unlike the other models, the Host Model does not use project mapping tables. Instead, the host application and the client application link directly to the projects they will be generated to. However, like the other models, these links do not have to be established until after the implementation projects are created.

One of the other significant requirements that influenced these models was to allow you, the Web service developer, to design Web services using logical models that are independent of any platform technology or programming language. This requirement is why there is an explicit stage to create the implementation. The following topics will explain this stage in more detail.