WCF contract changes that affect clients

Question

I was curious if someone could outline which types of WCF contract (interface) changes on the server side would break a client trying to send in a message, and why. I believe WCF can handle certain discrepancies, but I'm not sure exactly what you can change safely, and what you can't.

• Add/remove parameters from an OperationContract?
• Add/remove/change the DataContract's serialized properties?
• Add/remove OperationContracts from a ServiceContract?

A friend asked a similar question here:

Does adding a method to a WCF ServiceContract break existing clients?

EDIT: As John Saunders pointed out, changing the contract is not usually a good idea, but there are things built in that allow for some version tolerance (ExtensionDataObject, etc.?). I would just like to know how flexible the version tolerance is.

Answer 1

Check out this article on dasBlonde: Versioning WCF Service Contracts

It lists what changes will break existing clients:

1. Remove operations
2. Change operation name
3. Remove operation parameters
4. Add operation parameters
5. Change an operation parameter name or data type
6. Change an operation's return value type
7. Change the serialized XML format for a parameter type (data contract) or operation (message contract) by explicitly using .NET attributes or custom serialization code
8. Modify service operation encoding formats (RPC Encoding vs. Document Literal)

This article by Michele explains in more detail how you can design contracts to be more flexible.

Answer 2

Design recommendations for contracts

1. First version

   1.1. Carefully choose names for all contracts (interfaces, methods, classes and properties). These will be hard to change in future versions.

   1.2. Remember, that following cannot be changed in future: number of method parameters;type of parameters/return values/properties for types not under your control.

2. Next version

   2.1. If already exists, do NOT change Namespace or Name parameter on any xxxContractAttribute.

   2.2. If already exists, do NOT change Order property of the DataMemberAttribute.

   2.3. Only following changes are allowed:

   • Add method (OperationContract) to interface (ServiceContract)

   • Rename method on interface

   • Rename class (DataContract)

   • Add property (DataMember) to class (DataContract)

   • Rename property on class

   2.4. Any deletion breaks compatibility.

   2.5. Any other change breaks compatibility.

Here are few useful links:

• WCF Versioning Guidelines
• Service Versioning
• Best Practices: Data Contract Versioning
• Collection Types in Data Contracts

Answer 3

"Add/remove parameters from an OperationContract" in WCF is not always something that can break your client, but you have to know what you do. In particular, adding new parameters to an operation contract will cause legacy clients not to pass them, and on the service side they will be set with their default values. Moreover, removing parameters from an operation contract, will be silent from the client point of view, and they will be simply ignored on the service side. Of course, changing parameter's name/type will cause the client to break.

Answer 4

I think the best practice is to think of contracts as unbreakable, hmmm, contracts. Don't change them once they're published. It's easy enough to create a new contract with the changes you want, and to expose the new contract on a new endpoint.

Answer 5

OK. Question. Due to wrong naming syntax (parameter is specified with capital letter), I would like to adjust some code:

[OperationContract]
public void Foo(string Bar){}

to

[OperationContract]
public void Foo(string bar){}

Would adjusting the capital break contract?