Build Your First Web Service With Visual Studio .NET  by Dave Perkovich

The Basics of Web Services
The concept of sharing data between computers is hardly new. For years, developers have used such technologies as Distributed COM (DCOM) and Remote Data Services (RDS) to access objects that reside on servers across local area networks and even the Internet. However, with the recent introduction of Web services, many of the issues previously encountered when deploying and supporting DCOM or RDS solutions have radically changed for the better. In this article, we'll take a basic look at Web services and how to implement them, with code examples.

High Level Review
Before we dive into code examples, let's take a moment to review the general architecture of a Web service. We'll do this at a rather high level just to be sure you are familiar with the primary components of a Web service. You can find lots of documentation online that describes the architecture of a Web service in far more detail. For now, however, we'll assume you are relatively new to the Web service concept.

Web services provide the ability to share data with a large variety of clients. As the developer of the service, you do not need to know anything about the system your clients use. You build Web services using open standards that allow client developers to create and interact with Web services from a variety of sources. Using the Extensible Markup Language (XML), the data generated to and from your service is formatted in a standard, non-proprietary way. A client has no specific requirements to develop solutions that use your service.

Components
A Web service consists of three primary components:

1. The SOAP "listener"
2. The business logic object
3. The discovery of Web service file (DISCO file)

Web services and clients use the Simple Object Access Protocol (SOAP) when communicating with one another. SOAP essentially allows a client to make a request to a registered object on a server via standard Internet protocols, such as HTTP. This means that, unlike DCOM or RDS, system administrators do not need to configure special ports to allow access to your Web service. Instead, the service can be implemented to run right over the same HTTP port that a typical Web server runs. This also allows your administrators to implement the appropriate security using tools they are already familiar with.

The second component of a Web service is what I call the "business logic object." This is the object that your clients need to access. This object can be a traditional COM object or a newer .NET component. However, the objects supported by Web services are not limited to Microsoft technologies. For instance, you can create and share a JavaBean or CORBA object.

The discovery file makes up the third component of a Web service. This is often called the DISCO file. Developers use the DISCO file at design time to obtain a reference to the Web service. When you create a service using Visual Basic or C#, Visual Studio will generate this file with the .vsdisco extension automatically. C developers will get a file with the .disco extension.

When your client developers link to a DISCO file using Visual Studio .NET, they can more easily develop against the service since it appears like a normal reference to an object. For example, your Web service fully supports the Intellisense features we've come to take for granted in previous versions of Microsoft development languages.

Together, these three components constitute a Web service. When you use Visual Studio .NET to create a Web service, all three components are built into a single Web service project. The SOAP listener and DISCO file are created automatically. This leaves you free to focus on implementing the business logic required by your object.

OK, now that we've set the stage for what a Web service consists of, let's get our hands dirty with some sample code. For purposes of illustration, let's say you are working for the Fly Right Airline Corporation. Fly Right prides itself on the support it provides for its network of travel agents. You want to create a simple Web service that will give the hundreds of independent agents access to real-time flight arrival and departure information. Since there are over 750 agents worldwide, and each has his or her own IT staff, developing a solution that meets all of their needs could be quite demanding. However, through the use of a Web service, you can easily create such a solution, and you don't even necessarily have to know what tools and systems the various travel agents implement.

Server-Side
Let's go ahead and create both a server-side Web service and a client-side application that will allow us to test the service.

First, we'll build the Web service itself. Go ahead and start up Visual Studio .NET and follow these steps:

1. From the File menu, point to New, and click New Project.
2. Select ASP.NET Web service.
3. Change the Location to: http://localhost/FlyRight

   Notice that the project name is automatically updated.

4. Click OK.

By default, new projects include an initial .asmx file (the file used by your Web server for the Web service.) We'll edit this file to create the service. For this simple example, the service will support a single method, called FlightStatus. Clients call this method, passing it a flight number, and our service will return the expected arrival time of the flight.

Follow these steps to create the service:

1. In the Solution Explorer, select Service1.asmx.
2. Under Properties, change the FileName to FlightInfo.asmx.
3. Open the code window for this file. Right-click FlightInfo.asmx and click View Code.
4. We first need to specify the class name of the service. To do this, change the default code at the top of FlightInfo.asmx to read:

   <WebService(Namespace:="http://localhost/FlyRight/")> _
   Public Class FlightStatus
   

5. In the code window, create a new public function called ArrivalTime that accepts a single parameter called FlightNum. The code should look like this:

   <WebMethod(Description:="Submit the Flight Number _
   and a time will be returned.")> _
   Public Function ArrivalTime(ByVal FlightNum As String) As String

6. Since we are not actually connecting to a real database, let's use a simple SELECT...CASE statement to simulate the return of actual data. Enter the following code in the ArrivalTime function:

   Dim theTime as String
   
   Select Case FlightNum
         Case 1001
   			theTime = "12:30 AM EST"
      Case 2002
            theTime = "4:15 PM EST"
         Case Else
            theTime = "INVALID FLIGHT NUMBER"
   End Select

7. So far, the code is quite similar to Visual Basic 6.0 syntax. However, to return data from a function in Visual Basic .NET, the syntax has changed. Enter the following code after the Select...Case to return the actual data to the client:

   Return theTime

8. That's it. Save your project by clicking Save All from the File menu.
9. You can now build the project. From the Build menu, click Build Solution.
10. The Output window will show any errors in your code.

Client-Side
Now that you've created the server-side Web service, let's create a new application in Visual Studio .NET that will act as a client. Although you will probably be developing all of this on a local computer, the steps would be the same if you were working for a travel agent attempting to build an application that connects to the Fly Right Web site.

In Visual Studio .NET:

1. From the File menu, point to New and click Project.
2. Under Projects, select Windows Application.
3. Enter a project name of FlyRightClient and click OK.
4. In the Solution Explorer window, right-click References and click Add Web Reference.

   This is how you can connect your application to a Web service in order for Visual Studio to provide integrated support, such as using Intellisense.

5. In the Address box, enter the complete URL to the .asmx file created on the Web site when you built your Web service. This should be:

   http://localhost/FlyRight/FlightInfo.asmx

6. Click the green arrow next to the Address box to connect to the .asmx file and ultimately the DISCO file for this service. Note that the reference itself has not yet been created.
7. Click Add Reference to actually create the reference and return to your project.
8. If all goes well, you will see the ArrivalTime function and its description shown in the left pane.

Testing
Visual Studio .NET includes a simple test feature.

1. Click ArrivalTime.
2. Enter a value of 1001 in the test box and click Invoke.
3. You should receive the XML response document from the Web service stating the arrival time as 12:30 AM EST.

Now you can write code in your Visual Basic application to use this service.

1. Back in your client application in Visual Studio, expand Web References to verify the reference has been added.
2. Now, on the form, add two text boxes, named txtFlightNum and txtArrivalTime.
3. Add a command button to the form called cmdSubmit.
4. In the click event for cmdSubmit, enter the following code:

   Dim fr as localhost.FlightInfo
   Set fr = new localhost.FlightInfo
   txtArrivalTime.text = fr.ArrivalTime(txtFlightNum.text)

5. You can now run your application and enter one of the valid flight numbers to test the Web service.

So, creating and implementing a Web service using Visual Studio .NET is pretty straightforward. Using SOAP, clients connect to your Web service using standard Internet protocols, such as HTTP. Standard objects can then be called to execute the necessary business logic. These objects can be COM objects, .NET components, or even JavaBean or CORBA objects. Through the use of a DISCO file, which Visual Studio .NET creates automatically, third-party developers can interact with your Web service to develop their own independent solution. This is particularly useful in the event that you must support a variety of different clients running on different platforms.

 Note:

If you use Visual Studio.Net 2002, in the click event for cmdSubmit, enter the following code:

      Dim fr As New FlightRightClient.localhost.FlightStatus()
      txtArrivalTime.text = fr.ArrivalTime(txtFlightNum.text)