The “Hello World” Operation

Before you get the idea that “Hello World” is just a silly little example, consider that “Hello World” can do a great job diagnosing some basic problems. If a machine has an endpoint that returns a simple string when called correctly, programs using that code can perform simple tests to see if they can connect to the server.

The good news for us is that the wizards inside Visual Basic .NET will write this operation for us. To get there, we need to go through the Visual Studio IDE and create a new project. To do so, perform the following steps:

At this point, the IDE will create the Web Application on your local machine and generate the files needed for your Web Service. A skeleton class for a Web Service will be created as well. This class is always named Service1. Few people actually want a class named like this. To get a class with a meaningful name, you have two options—rename everything or delete Service1.asmx from the project and create a new class with a better name. Deleting the existing class has the added advantage that you will not miss some tiny detail. To delete Service1.asmx from the project, simply right-click the filename and select Delete. When the IDE warns you that the file will be permanently deleted, press OK. Now, let's add a new, better-named class to the project.

You should now be looking at a screen similar to the one shown in Figure 1.3. From here, click the text Click Here to Switch to Code View. The wizard generated the sample in Listing 1.1 just for you.

Listing 1.1. Wizard-Generated Code for Web Service

Public Class FirstService
    Inherits System.Web.Services.WebService

#Region " Web Services Designer Generated Code "

    Public Sub New()
        MyBase.New()

        'This call is required by the Web Services Designer.
        InitializeComponent()

        'Add your own initialization code after the InitializeComponent() call

    End Sub

    'Required by the Web Services Designer
    Private components As System.ComponentModel.Container
    'NOTE: The following procedure is required by the Web Services Designer
    'It can be modified using the Web Services Designer.
    'Do not modify it using the code editor.
<System.Diagnostics.DebuggerStepThrough()> _
    Private Sub InitializeComponent()
        components = New System.ComponentModel.Container()
    End Sub

    Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
        'CODEGEN: This procedure is required by the Web Services Designer
        'Do not modify it using the code editor.
    End Sub

#End Region

    ' 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

To enable the HelloWorld function, simply uncomment three lines of code.

<WebMethod()> Public Function HelloWorld() As String
   HelloWorld = "Hello World"
End Function

If you have not used Visual Basic .NET before, the statement before the keyword Public may look a bit odd. The value in angle brackets (< >) is an attribute. The languages shipping with .NET all allow for the use of attributes before class declarations, member variables, or methods. The attributes are specific to the data immediately following them. Instead of creating extra executable code, attributes provide metadata for the functions. When the Common Language Runtime (CLR) encounters that metadata, it may execute code or generate some other behavior. We will cover the attributes specific to Web Services in Chapter 4, “Using Attributes to Shape WSDL and XML.”

When the CLR sees the attribute <WebMethod()> when loading a class through an .asmx file, it knows to expose the method as a part of a Web Service. Web Services themselves only need to derive from the base class System.Web.Services.WebService to be able to access the ASP.NET Session and Application objects. You could just as easily not derive from System.Web.Services.WebService and still have a fully functional Web Service.

To build the project, go to the Build menu and select the Build option. To see if everything worked, open Internet Explorer and navigate to http://localhost/Chapter1/FirstService.asmx. After doing this, you should be presented with the screen shown in Figure 1.4. The page contains a warning that we will explore shortly.

To get the screen shown in Figure 1.4 and any other links we might follow from this page, we had to do no work. Instead, ASP.NET generates the pages for us by using the .NET reflection APIs. We will cover how this all works in Chapter 4. Just know that .NET makes your life very easy.

On the generated page, you will see a link to the HelloWorld operation. If you follow that link, you will be presented with a page that allows you to call the function and that outlines how to call the function using SOAP, HTTP/GET, and HTTP/POST. You see the general format of the message exchange—what to send and what to expect in return. This is another helpful piece of documentation that ASP.NET writes for you (see Figure 1.5). This page also allows you to call the Web Service by clicking the Invoke button.

When you press Invoke, Internet Explorer will not use SOAP to call the underlying function. Instead, it will call the Web Service using HTTP GET.

The actual exchange will look like the following:

Request:

GET /Chapter1/FirstService.asmx/HelloWorld? HTTP/1.1
Host: localhost

Response:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://tempuri.org/">string</string>

Clicking Invoke, we get the following response:

<?xml version="1.0" encoding="utf-8"?>
<string xmlns="http://tempuri.org/">Hello World</string>

For most of this book, we will only work with SOAP requests and responses. A SOAP Request/Response typically has this format:

<Envelope>
    <Header></Header>
    <Body>[interesting stuff here]</Body>
</Envelope>

But, Web Services can exist outside of the SOAP protocol. You can also send XML in a regular HTTP GET or POST request and return raw XML from that same request. When you do this, you are using Web Services in their simplest forms. To create the fancier, more powerful messages, only SOAP will work.

You will see a lot of messages in this chapter and the next. The idea is for you to become comfortable reading the messages. Outside of some special properties of the SOAP Envelope, your messages will be primarily Body content. That content is regular XML and only loosely related to SOAP. This book assumes you are already familiar with XML and that is why we start out with the simplest Web Service messages possible: HTTP GET/POST.