Article source code: websvc_object.zip
This article will demonstrate how to pass a user-created object from a server to a client. The server will pass the object through a Web Service (therefore IIS will be required on the server). You will be able to view the serialized object through any standard web browser such as Internet Explorer, Opera, or Netscape Navigator. A simple Windows Client application will also be created in order to show how to take the object and use it directly in standard Windows components such as text boxes and labels. This article does assume that you have a base familiarity with Web Services, Object creation, and Internet Information Server.
What are Web Services?
Web Services allow programmers to easily solve one of the fundamental problems facing many programmers today: how to get information from "here" to "there". Web Services are easy to code, based on open XML standards, and can be scaled both up and out in the same manner that IIS web servers are (by adding more processing power to existing hardware or adding additional servers in a web farm layout). For more information regarding Web Services (and for samples on transferring XML and SQL DataSets through Web Services please see my previous DevCity.NET article at http://www.devcity.net/net/article.aspx?alias=20020331
Sending an Object through a Web Service
Using a Web Service to send an Object is almost as easy as sending standard object types (such as strings or integers). The main difference is that a user-created object is not intrinsically "known" to the calling application until a web reference is made. Of course, as with most things in .NET, making the reference to a remote object is painless.
Sending user-created objects through Web Services is a two-step process: first, the object needs be defined; then the object needs to be passed.
Step 1: Define Your Object
Public Class ApartmentDetails
Public ApartmentID As Integer
Public City As String
Public RoomCount As Integer
Public SquareFeet As Integer
Public HighSpeedCapacity As Boolean
Public MonthlyCharge As Integer
Step 2: Pass The Object Through A Web Service
<WebMethod()> Public Function ListApartmentDetails() as ApartmentDetails
Dim myObjectToSend as New ApartmentDetails()
.ApartmentID = 0
.City = "CityTest"
.RoomCount = 1
.SquareFeet = 1000
.HighSpeedCapacity = True
.MonthlyCharge = 5000
Deploying a Web Service
Much like a traditional website deploying a Web Service is not a difficult process though it is not without its potential hang-ups.
If you have built your Web Service through the Visual Studio.NET IDE then all local deployment issues have been taken care of automatically. If you wish to move your solution to another computer you can choose to deploy your service using Visual Studio.NET's build-in wizard or you can choose to copy the site to a folder on the other computer. If you choose to copy the site then you will need to perform one additional step using the IIS MMC interface. You will need to identify the folder as a Virtual Directory Application in order for the proper configuration settings to be handled by the ASP.NET processor. If you forget to designate the folder as an application you are likely to receive the following error message when attempting to load the URL into your web browser.
It is an error to use a section registered as allowDefinition='MachineToApplication' beyond application level. This error can be caused by a virtual directory not being configured as an application in IIS
Testing the Web Service
Visual Studio.NET provides a very simple way to test Web Services using nothing more than a web browser. Specify the ASMX file in your web browser's address bar to connect to your Web Service and test your code.
Windows Client Application Testing
Using the Web Service's object in your local application is a straightforward two-step process. On the Web Service's end you needed to both define the Object then make it available for outside use. Similarly, on the client end we need to retrieve the Web Service's definition of the object, then retrieve an instance of that object.
Step 1: Retrieve the Web Service's Object Definition
Dim localApartmentDetailsObject As New localhost.ApartmentDetails()
Step 2: Create an instance of the new object
Dim remoteWebService As New localhost.Service1()
localApartmentDetailsObject = remoteWebService.ListApartmentDetails
The sample application provided for download includes all code used in creating this article as well as a functioning sample web service and client application. A SQL Server 2000 script is included which will allow you to generate the exact dataset I used while writing the article. A sample web service and client application is provided demonstrating the transfer of both an object and a standard ADO.NET Dataset.
Related devCity.NET articles: