Versioning Web Services in ASP.NET 2.0

[DevilDog74]

There is some debate on what an ideal web service interface would look like
at my organization. The debate revolves around how to write our web service
interface so that new methods do not break existing consumers.

Some people would have us write web methods like this:
Code:

// this is very granular
[WebMethod]
public int CreateClient(string clientName, string clientId, string address1,
string address2){}

Others would have us write the method like this....
// this is very object oriented and less granular
[WebMethod]
public int CreateClient(ClientDocument clientToAdd){}
And others would have us write the method like this:
// this is very generic
[WebMethod]
public int CreateClient(string manifest, string payload){}
I think the only people that agree on the first example, are the architects
that have never maintained code or written code for backward compatibility,
so 90% of all the tech leads and developers do not dig the first approach.

The majority of the shop thinks the second approach is preferred because in
the event that you need to add new methods, you just add them and redeploy
the web service. Meanwhile, existing clients work the same and new clients
consume the new method with the new foot print. I also beleive that we can
base our services around an Interface and use the adapter pattern to create
new functionality.

People that prefer the third approach are relying on the client passing in a
proper manifest definition. The contents of the manifest variable would be
used to load a factory that parsed the payload into business objects, and
then delegated the work to a template method in the factory object. The
template method of the factory object would invoke an xml reader and parse
the payload and do the work. My personal opinion is that this puts too much
weight on the consumer of the service, meaning that the consumer has to know
too much about the method they are invoking.

So my personal feeling is that the second method is the way to go. Since
everyone knows what opinons are like, i.e. everyone has one, I thought I
would ping the users of my favorite forum and see how the other down to earth
people handle versioning of web services.

I did read this article on the MSDN site, but I think it might be a bit
dated.
http://msdn.microsoft.com/webservice...ebserv/toc.asp

[DevilDog74]

Actually, in my first post, I posted the wrong link, here is the article that
I read concerning extending an interface...
http://msdn.microsoft.com/webservice...ce04032002.asp

[Jeremy Chapman]

I don't like the 3rd method at all. It requires smarts on the client side,
and you have to distribute some sort of specification because the format of
the manifest and the payload is not self evident through the web service.
Additionaly you need more error handling and reporting - Yuck. Instead of
doing this, I would think it would be easier just to write seperate web
services with the same method names, but requiring different parameters.
It's sort of an inheritance mechanism and doesn't require manifest
information.

The first method is very explicit which is nice, but I agree that it does
not lend itself well to maintenance and evlolution.
"DevilDog74" <De********@discussions.microsoft.com> wrote in message
news:7F**********************************@microsof t.com...

There is some debate on what an ideal web service interface would look
like
at my organization. The debate revolves around how to write our web
service
interface so that new methods do not break existing consumers.

Some people would have us write web methods like this:
Code:

// this is very granular
[WebMethod]
public int CreateClient(string clientName, string clientId, string
address1,
string address2){}

Others would have us write the method like this....
// this is very object oriented and less granular
[WebMethod]
public int CreateClient(ClientDocument clientToAdd){}
And others would have us write the method like this:
// this is very generic
[WebMethod]
public int CreateClient(string manifest, string payload){}
I think the only people that agree on the first example, are the
architects
that have never maintained code or written code for backward
compatibility,
so 90% of all the tech leads and developers do not dig the first approach.

The majority of the shop thinks the second approach is preferred because
in
the event that you need to add new methods, you just add them and redeploy
the web service. Meanwhile, existing clients work the same and new clients
consume the new method with the new foot print. I also beleive that we can
base our services around an Interface and use the adapter pattern to
create
new functionality.

People that prefer the third approach are relying on the client passing in
a
proper manifest definition. The contents of the manifest variable would be
used to load a factory that parsed the payload into business objects, and
then delegated the work to a template method in the factory object. The
template method of the factory object would invoke an xml reader and parse
the payload and do the work. My personal opinion is that this puts too
much
weight on the consumer of the service, meaning that the consumer has to
know
too much about the method they are invoking.

So my personal feeling is that the second method is the way to go. Since
everyone knows what opinons are like, i.e. everyone has one, I thought I
would ping the users of my favorite forum and see how the other down to
earth
people handle versioning of web services.

I did read this article on the MSDN site, but I think it might be a bit
dated.
http://msdn.microsoft.com/webservice...ebserv/toc.asp

[N Bethmann]

The granular method is universally callable and can easily be versioned. The
server-side constuctors are a much better place to handle the version
changes. You'll also have a good place to put comments explaining why you
made each change. You can't go wrong with this method.

[WebMethod]
public int CreateClient(string clientName, string clientId, string address1,
string address2){
ClientDocument client = new
ClientDocument(clientName,clientId,address1,addres s2);
return client.Create();
}

[WebMethod]
public int CreateClient_2(string clientName, string clientId, string
address1,
string address2, string state){
ClientDocument client = new
ClientDocument(clientName,clientId,address1,addres s2,state);
return client.Create();
}

[WebMethod]
public int CreateClient_3(string clientName, string clientId, string
address1,
string address2, string state, string zip){
ClientDocument client = new
ClientDocument(clientName,clientId,address1,addres s2.state.zip);
return client.Create();
}