XML Web Services

The System.Web.Services namespace is the namespace that we normally use in most of the projects as the types we need are already defined in this namespace. Following are the members of the System.Web.Services namespace:

WebMethodAttribute: Adding a <WebMethod()> attribute to a method in a Web service makes the method callable from a remote client through HTTP. This attribute exposes the functionality of the method to which it is applied to the outside world.

WebService: This defines the optional base class for Web Services.

WebServiceAttribute: The WebService attribute can be used to add information to a Web service that can describe it's functionality.

WebServiceBindingAttribute: Declares a binding protocol a given Web service method is implementing.

Coding a Sample Service

We will now create a sample service. This a simple service that converts a given distance from Kilometers to Miles and vice versa. Start Visual Studio .NET and open a new project from File->New-> Project. In the Projects Type pane select Visual Basic Projects and in the templates select ASP .NET Web Service, name this service as ConvertUnits and click OK. The new project dialog looks like the image below

By default, Web service projects automatically create a new virtual directory under IIS and will store our files there. Switch to code view of the Web service to take you to the code behind file which is a file with .asmx.vb extension. If you notice the Solution Explorer window you will find four files which are the Global.asax, Service1.asmx, ConvertUnits.vsdisco and the Web.config file. The Global.asax file allows us to respond to global-level events, the Web.config file allows us to declaratively configure our new Web service, the .asmx file is a Web service file that define the methods of the service and the .vsdisco file is a Discovery file that contains an XML description of the Web services at a given URL.

By default the code behind file looks like this when you open it:

Imports System.Web.Services
<WebService(Namespace := "http://tempuri.org/")> _
Public Class Service2
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.
''<WebMethod()> Public Function HelloWorld() As String
' HelloWorld = "Hello World"
' End Function
End Class

We will build on the above mentioned code behind file. We will implement some simple functionality adding our own methods. The service which we will build will convert distance expressed in Kilometers to Miles and vice versa. The code for that looks like this:

Imports System
Imports System.Web.Services

<WebService(Namespace := "http://tempuri.org/")> _
Public Class Service1 Inherits System.Web.Services.WebService

#Region " Web Services Designer Generated Code "

#End Region

<WebMethod()> Public Function ConvertUnits(ByVal EnterUnit As Decimal, _
ByVal FromUnits As String, ByVal ToUnits As String)
'ConvertUnits function with three arguments
Select Case FromUnits.ToUpper.Chars(0)
'making a selection with Select Case
Case "K"
'for converting distance from kilometers to miles
Select Case ToUnits.ToUpper.Chars(0)
Case "K"
Return EnterUnit
'if both FromUnits and ToUnits are same, returns the entered distance
Case "M"
Return EnterUnit / 1.4
'converts distance from kilometers to miles, assuming 1 mile=1.4 kilometer
Case Else
'to throw exception
End Select

Case "M"
'for converting distance from miles to kilometers
Select Case ToUnits.ToUpper.Chars(0)
Case "M"
Return EnterUnit
Case "K"
Return EnterUnit * 1.4
'converts distance from miles to kilometers
Case Else
'to throw exception
End Select
End Select
End Function

End Class

After finishing with the code run it by selecting Debug->Start from the main menu or by pressing F5 on the Keyboard. By default our browser functions as a makeshift client and shows an HTML view of the methods market with the <WebMethod()> attribute. Click here to view the page that first loads when you run this service. Click on the link ConvertUnits. Clicking on the link takes you to a page that provides Textbox types that allow us to enter some values in them. Enter some value in the EnterUnit field and in the FromUnits field enter either M or K and in the ToUnits filed enter K or M. If you wish to convert 1000 Kilometers into Miles then you need to enter 1000 in the EnterUnit field, K in the FromUnits and M in the ToUnits. Once you are done with it, click invoke. This will invoke the method we wrote in code and the result will be returned via an XML attribute. Click here to run the service now. That's all it takes to create a simple Web service.

Sample Service 2

In this section we will create a Calculator Web service that works similar to a Calculator and performs operations like Add, Subtract, Multiply, Divide and we will consume this Web service with a Visual Basic Windows Application. To start, open a new project and select ASP .NET Web service or add a new Web service to the existing ASP .NET Web service project by right-clicking the project name in Solution Explorer and selecting Add->Add Web service. Name this project as Calculator, open the code behind file and start writing the following code.

Imports System
Imports System.Web.Services

<WebService(Namespace := "http://tempuri.org/")> _
Public Class Service1
Inherits System.Web.Services.WebService

#Region " Web Services Designer Generated Code "

#End Region

<WebMethod(Description:="Click to Add numbers")> Public Function Add_
(ByVal x As Integer, ByVal y As Integer) As Integer
'this method adds two numbers by accepting the input from the user
'Description property allows to document the functionality of the Web method.
Return x + y
End Function

<WebMethod(Description:="Click to Subtract numbers")> Public Function Subtract_
(ByVal x As Integer,ByVal y As Integer) As Integer
'this method subtracts by accepting the input from the user
Return x - y
End Function

<WebMethod(Description:="Click to Multiply numbers")> Public Function Multiply_
(ByVal x As Integer,ByVal y As Integer) As Integer
'this method multiplies two numbers by accepting the input from the user
Return x * y
End Function

<WebMethod(Description:="Click to Divide numbers")> Public Function Divide_
(ByVal x As Integer,ByVal y As Integer) As Integer
'this method divides two numbers by accepting the input from the user
If (y = 0) Then
Throw New Exception("Can't divide by zero")
'if number entered is 0 throws an exception
End If
Return x / y
End Function

End Class

Once when you finish with the code run the service by selecting Debug->Start from the main menu or by pressing F5 on the keyboard. The Service that loads can be viewed by clicking here. You can view all the methods we created in code along with the method description on that page. Also you can enter some values in the Textboxes and test the service. We will consume this service in a Windows Form.

Consuming this Web service

Open a new Visual Basic Project and select Windows Application from the template. From the toolbox add a Button to the form. Our intention here is to consume the Web service which we created with this Windows Application. When we click the Button it will call the method which we specify in it's click event and will return the calculated result in a MessageBox.

Adding Web Service Reference to the Windows Application

We can add a reference to the Web service in two ways, with Solution Explorer and using WSDL tool. In the Solution Explorer right click on references and select Add Web Reference. That opens up a template similar to the image below.

In the address bar type the URL of the Calculator service which we created. Since it's in the root directory of IIS you need to type the following address: http://localhost/Calculator/Service1.asmx. It should look like the image below.

After the Calculator service is loaded, click Add Reference. That adds a reference to the Calculator service.

To use WSDL tool to add a reference to this Web service, open Visual Studio .NET command prompt, change the folder in the command prompt to the location where you created Calculator and type the following:

WSDL "http://localhost/Calculator/Service1.asmx" /l:VB. After you finish typing the command, in Solution Explorer, right-click Calculator, select Add and then click Add Existing Item. Locate Service1.vb, and then click to select it. Click Open.

Calling the Service from Windows Form

Open Form1 and place the following code. Recall that we are calling a method when the Button in this application is clicked. We need to create an instance of the proxy class localhost.Service1 and call the function, passing a string argument. The code for that looks like this:

Public Class Form1
Inherits System.Windows.Forms.Form

#Region " Windows Form Designer generated code "

#End Region

Dim myService As localhost.Service1 = New localhost.Service1()
'creating an instance

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As_
System.EventArgs) Handles MyBase.Load

End Sub

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As_
System.EventArgs) Handles Button1.Click
MessageBox.Show("Sum is " & myService.Add(10, 20))
'calling the Add method in the Web Service returning the result in a messagebox
End Sub

End Class

Once you finish with the application, run the form and click on the Button. The sum of two numbers will be displayed in a MessageBox. We not only created a Web service but also consumed the service in other application.

Sample Service 3

In this section we will build a more interesting Web service that returns a ADO .NET DataSet, containing the full set of records from a table. We will create our own database table and access the data from the table with this Web service. To Start, open Microsoft Access and create a new Database named Currency. Create a new table Table1 and add three columns named, Country Code, Country Name and Currency. Enter some values in the table and close it. Open Visual Studio .NET and select ASP .NET Web service from the projects type template. Drag a OleDb connection from the Data tab in the toolbox and using the properties window build a connection string that connects to the Currency database which we created. Switch to the code view and start writing the following code.

Imports System
Imports System.Web.Services
Imports System.Data.OleDb
'import this namespace as we are working with an OleDb source

<WebService(Namespace := "http://tempuri.org/")> _

Public Class Service1 Inherits System.Web.Services.WebService

#Region " Web Services Designer Generated Code "

#End Region

<WebMethod()> Public Function GetData() As DataSet
'WebMethod name is GetData,generate data set
Dim da as OleDbDataAdapter=new OleDbDataAdapter("Select * From Table1",_
OleDbConnection1)
'dataadapter
Dim ds As DataSet=new DataSet()
'declaring a new DataSet
da.Fill(ds, "Table1")
'filling dataadapter
Return ds
'returning dataset
End Function
End Class

Consuming the Service

Once you finish with coding the Web service we need to consume this service. To do that, open a new Windows Application and from the toolbox drag a DataGrid and a Button. Our intention here is to load the data from Table1 in the Currency database into the DataGrid when we click the Button. Now, add a Web reference to the Web service by selecting Reference->Add WebReference in the Solution Explorer Window. Enter the URL of the service in the address bar and click "Add Reference". That adds a reference to the Web Service. Now double-click on the Button and write the following code.

Public Class Form1 Inherits System.Windows.Forms.Form

#Region " Windows Form Designer generated code "

#End Region

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e_
As System.EventArgs)Handles Button1.Click
Dim myService As New localhost.Service1()
'an instance of the Web service
Dim ds1 As DataSet = myService.GetData
DataGrid1.DataSource = ds1.Tables("Table1")
'filling the datagrid with table
End Sub
End Class

Once you finish with the code, run the Windows Application and click on the Button. The data you entered in Table1 of the Currency database will be displayed in the datagrid. The difference, we are accessing the data with a Web service. The image below displays that.