It’s been a long time since I’ve written a technical post, or any post actually, so forgive me if I’m a bit rusty. OK, in this post I’ll talk about creating a client program that consumes a web service using C#. As regulars of this blog and my social media accounts probably know, I am a Unix fan. So I will show you how to develop this program using Mono, the Unix port of Microsoft’s .NET architecture. I tested this code on my Mac, but it should work in any Unix environment unchanged.
First, let us provide a brief description of web services. A web service is a set of functions that are provided by a remote computer. These functions can be invoked by a client as if they were local functions as needed by the program logic. The philosophy behind this is to make software a service. People write functions that perform certain behaviour, and an application programmer uses these functions to implement the logic of his/her program. The applications programmer can use any combination of remote and local functions that he/she deems necessary.
This has several advantages, first is specialisation of function, and second is that it makes code re-use very easy. Consider for example the case of currency exchange, instead of having everybody design his or her ad hoc method of obtaining exchange rates, the central bank could implement a web service that reports official exchange rates. Any programmer that needed to perform a currency exchange could then use this web service to determine the current exchange rate before using it.
Functionality that exists in only one location could also be implemented as a web service. Consider for example the process of booking tickets in the iMax cinema in Egypt. Currently, you need to go to their Web site in order to book a ticket. However, if iMax implemented the ticket booking process as a web service, third party developers could then develop applications that used this web service to allow people to book tickets from mobile and desktop applications. The possibilities are endless.
Ok, enough with the marketing talk, let’s get our hands dirty with some coding. For the purpose of this example, I searched for publicly available web services on the Internet. We do not want to waste money on buying subscriptions to web services until we’re confident enough that we can write programs whose sale can cover the cost of subscription 😀
I found this web service that provides a currency exchange rate reporting service, which, fortunately, fits into the narrative I used above while explaining the rationale of web services.
http://www.webservicex.net/CurrencyConvertor.asmx?WSDL
Do not try to visit the url above, if you do, you’ll be greeted with a lot of garbled text on the screen. Web services are not meant to be consumed by people, they are meant to be consumed by computers. We will need to write a computer program to take advantage of that web service.
As previously mentioned, a web service provides a set of functions that perform a certain operation. And since this is a currency exchange rate web service, it can be safely assumed that the function implemented in this web service is one that returns the exchange rate between two currencies. The question now arises, what is the format of this function? What parameters does it take in? Are the two currencies that we want to know the conversion rate between represented as strings, integers or enums?
These very valid question lead us to the first piece of the web services puzzle. Each web service contains an XML file that describes the format of the functions it implements. This XML file is written according to a standard called WSDL (web services description language). What we need to do is to get this WSDL file and then use it to create a wrapper class that contains the interface that can be used to access the web service. Note that the wrapped class will contain no implementation of the functionality required, that would defeat the purpose of web services. It will only contain the header of the functions that the client program can call, and code that performs the network operations necessary to contact the server that offers the web service being used and then return the result to the client — this is done transparently to the client, for all intents and purposes the client does not even know that the function he/she is calling is remote.
If you are really interested, the function call and return value are exchanged between the client and server in XML files that follow the SOAP protocol. These XML files are exchanged over HTTP. But as previously mentioned, you do not need to know this, all you need to know is that if you use the interface provided by the WSDL, you can call the functions hosted by the remote server as if they are local.
First, we need to retrieve the WSDL file from the server and convert it into a wrapper class. Mono offers a very easy command line tool to accomplish this. The command below does this
wsdl http://www.webservicex.net/CurrencyConvertor.asmx?WSDL
The line above retrieves the WSDL XML file and creates a C# class in CurrencyConvertor.cs that describes the interface of the web service offered by the server. Go ahead, try it and then open CurrencyConvertor.cs using your favourite text editor to inspect the resulting class.
We now want to compile CurrencyConvertor.cs into a dll that can be used in the program. This can be easily done using the following command
mcs /target:library CurrencyConvertor.cs -r:System.Web.Services
Note two things, first we choose “library” as our target to make sure that the result is a dll and not an executable file, and that we reference, the -r part, System.Web.Services while compiling the library. We do this because System.Web.Services contains the classes that are needed by any web service interface. System.Web.Services is provided by the Mono framework.
We are now ready to write the code that actually uses the web service, a quick look at CurrencyConvertor.cs shows us that the web service exposes a class called CurrencyConvertor that has a public method called ConverstionRate. This method takes two enums as parameters that represent the two currencies that we want to find the conversion rate between. The code below shows how we can use this class to perform the conversion.
using System;
class Test
{
public static void Main (string [] args)
{
//var to hold rate
double rate;
// Create a Currency Convertor object
CurrencyConvertor Service1 = new CurrencyConvertor ();
//Actually call the method
rate=Service1.ConversionRate(Currency.EUR,Currency.ALL);
Console.WriteLine("Rate is {0}",rate);
}
}The code is pretty self-explanatory, suffice it to say that EUR is the enum used to represent the EURO and ALL is the enum used to represent the Albania Lira, I got this information from the CurrencyConvertor.cs file that was created using the wsdl tool in the first step described in this blog.
Now for the final step. We want to compile the program above, which I wrote in test.cs. into a final executable. Here is the command that does this.
mcs /r:CurrencyConvertor.dll test.cs -r:System.Web.Services
Note that I link the dll file and refer to System.Web.Service while compiling test.cs. This step will produce an executable file, text.exe, that can be run from the command line as follows.
mono test.exe
That’s it folks. It’s as easy as pie, go forth and program.
1 Comment