Recently I was in the need of a web service. At first sight I only needed a back door on a website to retrieve some bulk data. VS (2003) tempts you to make the web service part of the web project itself. This can be done but it will result in a service which is very very dependent on the site. For some parts this was good as the service uses a lot of the same configuration settings as the site. New versions of the site are rolled out on a regular basis (I'm not going to use the A-word) and as the IT department is not completely used to .NET yet, setup just has to be as simple as possible. Including the service in the same setup would be nice. The wost part of the dependency lies in security. You cannot use different authentication methods within one web project. As the site (like many others) uses forms authentication the web service will (try to) use forms authentication as well. Which is out of the question. As a workaround you can disable authorization for the specific web service urls. Which is out of the question as well. And that also does require quite some web.config fiddling and complicates the setup; exactly the thing I was trying to prevent. There are far simpler ways for web applications to share configuration, more on that in a later post.
So however simple my initial web service was going to be; it is a separate project. Which gave me the occasion to work in real life with Christian Weyers Web Service Contract First tool, known as WSCF.
There are two ways to approach a web service. The best known one is the Visual Studio template. Which starts with the code. My service would look something like this.
public class IndatoWebService : System.Web.Services.WebService
{
public IndatoWebService()
{
//CODEGEN: This call is required by the ASP.NET Web Services Designer
InitializeComponent();
}
[WebMethod]
Indato.Data.Lookups.RoosterExport Activiteiten(int school, int opleiding, int jaar, int periode)
{
// implementation code
}
[WebMethod]
Indato.Data.Lookups.StudentSets StudentSets(int school, int opleiding, int jaar, int periode)
{
// more implmentation code
}
[WebMethod]
Indato.Data.Lookups.Personeel Personeel(int school, int opleiding, int jaar, int periode)
{
// and even more implementation code
}
}
The service is built around this class which has methods with a WebMethod attribute. They all take a couple of selection parameters and return a typed dataset. It comes close to the programming model in the consumer of the service. A typical consumer will have a proxy (which is generated when you add a web reference in a VS project) containing members for these WebMethod's. The consumer's code will call the methods of the proxy. How the proxy communicates with the service is encapsulated. In Christian Weyer's flamboyant talk (go and see it whenever you get the chance or else read this) he makes it very clear that Remote Procedure Calls are just one aspect of web services.
What's actually happening between a service and its consumer should be seen as an exchange of messages. Just like your web browser issues a request for a certain page on a certain site and is returned a bunch of HTML a web service consumer sends a request message to the service and is returned a response message. The latter can even be missing, the consumer just sends a message to the service, No Reply Necessary. Compare it to people exchanging emails.
To focus looking at web services this way Christian created WSCF. On the site is a very elaborate walkthough how to work with it; in the remainder of this post I hope to tickle your curiosity.
You start with describing the messages your service will exchange. These message will be in XML, the XML schema editor in VS makes a good tool to do the job. Here's another look at the same service:
The list of parameters to the method are bundled in the Selection element. A service operation (webmethod) has only one parameter, it is a message containing the former parameter list. The messages returned by the services are modeled in the other xxxResponse messages. WSCF installs a right mouse button click for every XSD in your project. It reads create WSDL interface description and will fire up a wizard to generate a Web Service Description Language (WSDL) document which describes your service. The wizard can infer operations (web methods) out of the schema and you have full control on specifying the operations.
For each operation you specify the message coming in:
and the message returned:
As all operations use the same selection criteria I can reuse the Selection message for several operations.
Now I have a WSDL WS–I BP (Basic Profile) 1.1 conformant description of my service which describes it in a standard understood by a great number of tools in a large variety of environments. Including WSCF. Right clicking the wsdl in the project reveals Generate Web Service Code which pops up the next wizard. The wizard, which again has a number of fascinating options, can generate the code for the server stub to implement the service itself as well for the client proxy to consume the service.
The walkthough starts with three projects. An empty one to house the contract in the form of the messages schema, an empty web project for the service implementation and a client implementation. Having generated the WSDL you have to copy it, with schema, to the client and the service project before generating the code. When generating the server stuff quite a lot happens. A couple of classes are added to the project including one inheriting from the System.Web.Services.Webservice class. Which looks like an highly decorated version of the thing the VS template came up with
[System.Web.Services.WebServiceBindingAttribute(Name="IndatoWebService", Namespace="http://hanze.nl/Indato/Rooster")]
[System.Web.Services.WebServiceAttribute(Namespace="http://hanze.nl/Indato/Rooster")]
public class IndatoWebServicePort : System.Web.Services.WebService, IIndatoWebServicePort
{
public IndatoWebServicePort()
{
}
/// <remarks/>
[System.Web.Services.WebMethodAttribute()]
[System.Web.Services.Protocols.SoapDocumentMethodAttribute("http://hanze.nl/Indato/Rooster:activiteitenZonderL1L2ResponseIn", Use=System.Web.Services.Description.SoapBindingUse.Literal, ParameterStyle=System.Web.Services.Protocols.SoapParameterStyle.Bare)]
[return: System.Xml.Serialization.XmlElementAttribute("ActiviteitenZonderL1L2Response", Namespace="http://hanze.nl/Indato/Rooster/RoosterMessages.xsd")]
public virtual ActiviteitenZonderL1L2Response ActiviteitenZonderL1L2([System.Xml.Serialization.XmlElementAttribute(Namespace="http://hanze.nl/Indato/Rooster/RoosterMessages.xsd", ElementName="Selection")] Selection selection)
{
throw new System.NotImplementedException();
}
// Other members are quite likewise
// Other members
}
Now I have reached the same point as the VS template and I can start writing the service implementation. What I have gained is that I have started with an outside view of the service in a language of XML formatted messages and not with an inside view of just some lines of generated C# (VB) code.
Working on the service (but before publishing it to the world outside the dev department !) you will always find out some things have to change. WSCF supports round tripping. You can edit the message schema and edit the WSDL. The latter is in the right-click menu and will fire up the wizard.
WSCF looks like a tool which fits perfectly in architecture centered development. And the moment you start building web services you are in that world. My service started as a backdoor to a website but as soon as the end users had seen it (yes we have very regular meetings discussing the application and I'm still not going to mention the A-word :)) we started discussing interaction with other applications. The user does understand the (graphical) schema which makes perfectly clear what the service can and cannot do. This is good for the applications as it's usability will increase and it is good for me as it can bring more nice things to do.
So far using WSCF for building the web service is quite a success. But I did not use it for building the consuming client. My main problem was that every roundtrip of the contracts requires deploying (plain copy) the generated wsdl and the accompanying schema's to the client code. Instead I created just a server project which included the contract schema's. One clean and independent project. As all info needed by a consumer of the service is in the wsdl all the consuming client application needs is a reference to the wsdl. Which is exactly what add web reference in VS does. Having updated the service all I need to do in the client project is Update Web Reference. However, the proxy generated by WCSF does offer some nice extra's. It returns the data (when the option in the wizard is set) as a collection, the VS web reference just sees an plain array. I also have to set the service endpoint (the URL with it's location) by hand. The latter is something I'll have to do anyhow, as it will be read from a config file. And I can live with the arrays as a trade off for a cleaner development process. This is a point where WSCF could be improved.
I have only scratched the surface of the many, many options of WSCF. Go the site and read on, even if you don't plan to actually use WSCF. You will find loads and loads of interesting stuff. In the old days we used to say Think First, Program Later. As a variation: Contract First, Program Later.