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.

Ioves

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.

Denominate

If you need to do one of these things, update your clients. It's easy with VS2015. – Bifocal

Would making a non-nullable Guid contract property to be Nullable break the clients? – Chromogenic

how about namespaces ? does a namespace change breaks the contract? It will be serialized the same after all – Naamana

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

Countrybred

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.

Zehe

Answer 4

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?

Claudiaclaudian

yes, but if you just want the lowercase bar for your code purposes I think you can decorate the parameter itself with [MessageParameter(Name ="Bar")], which makes it look the same to clients, but be different to your service internally. – Melosa

Answer 5

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.

Gilgamesh

I agree with the overall concept of not changing contracts, but if you make small changes to a contract, I don't know if it's always a good idea to publish a new endpoint for every new contract. Any thoughts on this? – Ioves

My thought is, "give 'em an inch, and they'll take a mile". Don't get into the habit of allowing "small" changes, or they'll make big ones. – Gilgamesh