What is best-practice when designing SOA WCF web-services?

Question

Given an operation contract such as:

[OperationContract]
void Operation(string param1, string param2, int param3);

This could be redesigned to:

[MessageContract]
public class OperationRequest
{
    [MessageBodyMember]
    public string Param1 { get; set; }

    [MessageBodyMember]
    public string Param2 { get; set; }

    [MessageBodyMember]
    public int Param3 { get; set; }
}

[MessageContract]
public class OperationResponse
{
}

[OperationContract]
OperationResponse Operation(OperationRequest request);

One thing I like about the MessageContract is that I get a little more explicit control over the format of the SOAP message.

Similarly, I could write nearly the same code, but use a DataContract:

[DataContract]
public class OperationRequest
{
    [DataMember]
    public string Param1 { get; set; }

    [DataMember]
    public string Param2 { get; set; }

    [DataMember]
    public int Param3 { get; set; }
}

[DataContract]
public class OperationResponse
{
}

[OperationContract]
OperationResponse Operation(OperationRequest request);

One thing I like about the DataContract is that I can define IsRequired, Order, and Name.

Today I expect the only consumer will be a WCF client. However, I want to design contract first and adhere to SOA practices as much as possible. Rather than have WCF dictate my SOAP, WSDL, and XSD, I want the XML to define the WCF layer, but use WCF to generate this so as not to add any custom message processing to WCF. I want to follow the most common SOA XML conventions which I believe is probably all tags beginning in lowercase - am I right? And I want to be as version tolerant as possible.

Is it wise to always create Request and Response messages like this? Which of the three formats promotes the best SOA practices? Should I go one step further and define both a DataContract and a MessageContract whereby the MessageContract only contains the DataContract? Or should I only ever use DataContracts if I am truly exposing a new type (i.e. do not create message types as containers)?

A loaded set of questions I know, but I am trying to get to the heart of it, and I am not sure separating the questions provides sufficient context to get the answer I am looking for.

Answer 1

I think it honestly depends on the scenario. If you're just exchanging simple types [i.e. string], OperationContract is certainly acceptable.

You should use MessageContract when you want to modify the message format and DataContract should be leveraged when you want to express a Complex Type, such as an address.

Answer 2

YAGNI comes to mind here.

I say don't over do it on getting too fancy looking to the future. WCF is already nicely SOA friendly. I say, in general, stick to the defaults and be careful about coupling until you have a specific need to do something elaborate.

Answer 3

XML usually tends to be camelCased. WSDL and XML Schema use camelCasing for both elements and attributes, for example:

[http://www.w3schools.com/wsdl/wsdl_syntax.asp][1]
[http://www.w3schools.com/Schema/schema_howto.asp][2]

Why SOAP was defined differently, I do not know, but it uses PascalCasing for elements and camelCasing for attributes, see:

[http://www.w3schools.com/soap/soap_header.asp][3]

Similary, most of the WS* specs (maybe all) use PascalCasing for elements and attributes, see: http://ws-standards.com/. XML Schema is agnostic about the conventions of the types it defines for XML.

Thomas Erl (http://www.thomaserl.com/) writes many important books on SOA (http://www.soabooks.com/) including "Service-Oriented Architecture". In Chapter's 13 and 15 he provides a number of examples of the XML of the various parts of typical transactions. It define types and object members in XML Schema using PascalCasing which nicely matches the normal patterns of C# for class and property naming. Thus WCF defaults already closely match the standards.

Regarding actual message naming, some conventions use camelCasing and others use PascalCasing, so my preference is to match the primary language needs, which in the WCF case is PascalCasing. And WCF defaults match some examples of how the request and response message should be written: http://www.w3schools.com/soap/soap_example.asp.

So the only outstanding question is now the basic question of how much to standardize around the use of OperationContract, DataContract, and/or MessageContract.

Defining DataContract only when a you have a complex type (in XSD parlance) makes sense, and I tend to think YAGNI as pointed out by Terry is the correct choice, but Erl seems to suggest a much more process intensive version so I am still not sure the best approach to use as my default choice (the main part of the question).

Answer 4

its always a best practice not to have multiple parameter in a operation contract, always have a type that wraps all the required parameters, this will help out in the long run. Your existing clients won't break when you add a new optional parameter.

I work in a business integration team where we integrate with other companies fairly regularly, (AT&T, Cox, Exxon ...) and have never seen a web service call that took more than a single parameter.