Musings of a Software Engineer v2.0

home code curriculum vitae

Step by step guide to Web Services

03 May 2006

Firstly, this is no documentation for Web Services and neither do i wish to make any. I dont discuss any inernals on how web services work. It is just a step-by-step guide to develop Web Services and consuming them in .NET. I prefer VB.NET for this tutorial. I use layman terms and if you have some problem with my language, visit MSDN and learn-dont bother to visit again.
What are Web Services??
I would say a Web Service is a DLL that is referenced through the internet using HTTP protocol. Instead of shipping your business logic along with the application, as a DLL, we can make it a web service and host it as a website. But all it does is to provide the same services as a DLL - i.e no presentation involved.
How to create a web Service?
1. Start Visual Studio 2003. Go to VB Projects -> ASP.NET Web Service -> Give a project name and click OK.
2. Click on Switch to code view on the designer view you get. We dont need a designer so we go to the code view.
3. You can notice a Hello World method commented. Copy the same and paste it and this time uncomment it. That is your code file should look like this.

_
Public Class Service1
Inherits System.Web.Services.WebService

#Region " Web Services Designer Generated Code "

' WEB SERVICE EXAMPLE
' The HelloWorld() example service returns the string Hello World.
' To build, uncomment the following lines then save and build the project.
' To test this web service, ensure that the .asmx file is the start page
' and press F5.
'
' _
'Public Function HelloWorld() As String
' Return "Hello World"
'End Function

<WebMethod()>
Public Function HelloWorld() As String
Return "hello world"
End Function
End class

4. Ok your web service is ready. Just "Build" the project clicking on CTRL + f5). It starts up IE showing a sample page. That looks like the one shown below!

Service1
The following operations are supported. For a formal definition, please review the Service Description.

HelloWorld

5. Click on the "HelloWorld" and you are taken to a page that has the SOAP Headers and HTTP Post descriptions along with a Invoke button. Click on the "Invoke" button. the output you get is as follows.
<xml version="1.0" encoding="utf-8" ?>
<string> xmlns="http://tempuri.org/LearnWebServices/Service1">hello world</string>
The webservice is working perfectly. I dont intend to discuss the above XML, its self explanatory.

How do you consume a Web Service?
1. The above described way is to check if a webservice is working properly. It is not the actual way to use a Web Service. In order to use a web service in Visual Studio, add a new Windows project to the same solution. Right-click on the newly added project and click on "Add Web Reference.." and in the page you get, click on the "Web Services on the Local Machine".
2. Then you get a list of the webservices that are available on your machine. Click on the one which you just created(i renamed my .asmx file in the web services project to SampleService, so i ll click on the SampleService in the window). Give some proper "Web Reference Name" above the button - "Add Reference". Click on the button to add the reference.( I gave the Web reference name as "LearnWebServices" )
3. Reference has been added. It actually checks to see if the service is upto date without any errors. Only then it adds the reference. You can then see a web References folder inside the Solution Explorer for the WindowS application project.
4. Now add a button to the form in the win app project. In the click event, write the following code.

Dim s As New LearnWebServices.Service1
MsgBox(s.HelloWorld())

5. When you run the Windows application and click on the button you get a "
hello world" message displayed. The first execution is always slow, but later on you see the message displayed immediately. What i did in the above code is to instantiate the Service1 class and then call the method on its object. You can notice that its just as if you are using a Local library!

Some Issues?
The coverage is not complete. There are books on writing Web services and i dont have any intention for competiting them. I discuss few more issues as days pass by but for now, some notes follows.
1. You can write as many classes inside the web service, just the methods should have the <WebMethod()> attributes. There could a non-webmethods inside the webservice, but they cannot be accessed directly like the Web methods.
2. Method overloading is not directly supported. in order to overload methods we need to use specific attributes. If we overload Helloworld() method and try to test the web service, we get this exception -

Overloaded methods

 <WebMethod()> _
Public Function HelloWorld() As String
Return "hello world"
End Function

 <WebMethod()> _
Public Function HelloWorld(ByVal name As String) As String
Return "hello world " + name
End Function

The exception we get when we try to run the web service is
Both System.String HelloWorld(System.String) and System.String HelloWorld() use the message name 'HelloWorld'. Use the MessageName property of the WebMethod custom attribute to specify unique message names for the methods.

The correction needed is to add a MessageName property to the web Method!! As shown.

<WebMethod()> _
Public Function HelloWorld() As String
Return "hello world"
End Function

 <WebMethod(MessageName:="HelloWorldWithParamter")> _
Public Function HelloWorld(ByVal name As String) As String
Return "hello world " + name
End Function

As you can notice we use the named paramters in VB.NET. Figure it out on how to use this in C#.

3. Another difference with Web Methods is that Parameters when reference types are passed as paramters and changes are to be reflected, then ByRef has to be used unlike in the case of local methods where ByVal and ByRef mean the same for the reference types.

4. When you make a changes and compile the Web Service again, you shoud REBUILD the web service project. Also you should "update web reference". For this right click on the Web references/LearnWebServices in the solution explorer and click on Update Web reference.

Well thats all for now. See you later with more tutorials.

Krishna Vangapandu, Associated Director, Technology @ Jet.com
krishnbhargava@gmail.com
github.com/krishnabhargav
twitter.com/truebuddi