oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button O'Reilly Book Excerpts: Programming .NET Web Services

Creating ASP.NET Web Services, Part 1

Related Reading

Programming .NET Web Services
By Alex Ferrara, Matthew MacDonald

by Alex Ferrara and Matthew MacDonald

In part one in this series of book excerpts from Programming .NET Web Services, learn how to write an ASP.NET HelloWorld Web service application.

Using the .NET Framework, it's easy to get a basic service up and running. In just a few minutes and fewer lines of code, you can put together a simple "Hello World" service without any understanding of HTTP, SOAP, WSDL or any of the several technologies that form the basis for web services. In fact, if you're a Microsoft Visual Studio .NET user, all you need to do to create a simple "Hello, World" service is to open a new Visual C# or Visual Basic ASP.NET Web Service project and uncomment the sample code provided by the template.

In this chapter, you'll learn about ASP.NET, the new Microsoft technology for building web applications and services, and how to use the .NET platform and Visual Studio .NET to create some simple web services. We'll also talk about some of the features of .NET that will get you on the road to developing well-documented scalable web service applications. By the end of this chapter, you'll have a solid understanding of how .NET supports web services and how to use the .NET platform to create them. We'll start with the ubiquitous "Hello, World" example exposed as a web service.

Creating a Web Service: "Hello, World"

In this section, you'll create a simple web service in the "Hello, World" tradition. Through this brief example, you'll see how easy it is to use ASP.NET to create a working web service (with a text editor or with VS.NET) and learn about the basic technologies behind .NET web service.

Creating a Web Service with Inline Code

While Visual Studio .NET provides a feature-rich integrated development environment for .NET development, it's not required to create .NET web services. Applications can also be created using your favorite text editor and the command-line tools that ship with the .NET Framework SDK. Here, we use Notepad as a text editor, but you should feel free to use whatever editor you're most comfortable with (Emacs or vi).

If you chose to develop with a text editor, you must place all of your code in one or more text files, assign them each the file extension .asmx and place them in an IIS folder on a server or workstation that has the .NET Framework installed. Once you save the code to a folder served by the IIS web server, it's ready to run--that's it! How you get the file to your web server is your business. If you're running IIS locally on your workstation (and you've installed the .NET Framework), this is as simple as saving the file to a suitable location on your local drive (e.g., c:\inetpub\wwwroot\). If you're using a remote server (in which case there's no need to have the .NET Framework installed locally), you might have to use FTP or a network share instead (more about this later).

Once you've chosen a text editor and file location, all that's left is to write the code.

Example 2-1 lists the code for a C# version of the ubiquitous "Hello, World" application; unlike the classic desktop version, this one delivers its familiar message over the Web through an exposed method called HelloWorld(). To identify the class and method as a web service to the compiler, this code uses some special notation. It also includes an ASP.NET directive at the head of the file.

To create a C# version of the HelloWorld web service, enter the code from Example 2-1 exactly as it appears, and save the file to your web server under the c:\inetpub\wwwroot folder (or whatever folder is the web root folder for your system) with the name HelloWorld.asmx.

Example 2-1. HelloWorld: C# web service

<%@ WebService Language="C#"
Class="ProgWS.Ch02.HelloWorldService" %>
using System.Web.Services;
namespace ProgWS.Ch02
  public class HelloWorldService: WebService 
    public string HelloWorld()
      return "Hello World";

In the following sections, we'll explain the standard elements of this web service source file and then show you how to test it.

The WebService directive

Example 2-1 begins with a WebService directive, an ASP.NET statement declaring that the code that follows is a web service:

<%@ WebService Language="C#" Class="ProgWS.Ch02.HelloWorldService" %>

TIP: The WebService directive is similar to the Page directive that begins most .aspx pages.

For the HelloWorld web service to work, you must assign values to two WebService directive attributes: Language and Class.

The required Language attribute lets .NET know which programming language the class has been written in. As you might guess, the acceptable values for the language attribute are currently C#, VB, and JS for JScript.NET.

The Class attribute, also required, tells ASP.NET the name of the class to expose as a web service. Because a web service application can comprise multiple classes, some of which may not be web services, you must tell .NET which class to expose, a step analogous to declaring a Main() method to indicate the entry point of a .NET console application or component. Note that even if your web service contains only one class, setting this attribute is required.

The using directive: importing .NET namespaces

The next line in the example is a using statement that tells the compiler to alias the System.Web.Services namespace to the local namespace. For C#, this directive is:

using System.Web.Services;

This directive allows you to refer to objects in the System.Web.Services namespace without having to fully qualify the request. This statement is optional, but if it is not included, every reference to an object in this namespace must be fully qualified. An example is the next line, which is our class declaration. With the using statement, it looks as follows in C#:

using System.Web.Services;
public class HelloWorldService: WebService

Without the using statement, it would have to be written fully qualified:

public class HelloWorldService: System.Web.Services.WebService

Note: Importing a namespace does not give you access to any of the additional namespaces that appear to be nested in that namespace. In other words, if you were to import the System.Web namespace, you would not be able to refer to the System.Web.Services.WebService class as Services.WebService. While a namespace like System.Web.Services may "appear" to be nested in the System.Web namespace, that is not the case. They are implemented as two different assemblies that bear little relation to each other aside from a partial name sharing. The apparently hierarchical nature of the .NET Framework's namespaces exists in name only as an organizational convenience and has no bearing on class structure.

The namespace keyword

.NET allows you--and Microsoft encourages you--to put the classes of an application into a unique namespace. In C#, this is done with the namespace keyword and the following syntax:

namespace name
... type declaration ...

In Example 2-1, the HelloWorldService class is placed in the ProgWS.Ch02 namespace with the following statement:

namespace ProgWS.Ch02

Namespaces can contain definitions for classes, interfaces, structs, enums, and delegates, as well as other namespaces. In addition, the source code for objects in a namespace does not have to be stored in the same file--it can span multiple files.

Note: For Java programmers: a namespace is similar to a package. However, unlike a package, in a namespace there are no directory structure requirements, because all of the source code is presumed to be in the same directory or a global assembly cache.

Namespaces provide a means of grouping pieces of code that might be written and maintained by other developers. When the class definitions of your web service exist within a namespace, you must specify the namespace along with the class name in your WebService directive as in Example 2-1:

<%@ WebService Language="C#" Class="ProgWS.Ch02.HelloWorldService" %>

This line tells ASP.NET to look for the class HelloWorldService in the namespace ProgWS.Ch02.

The WebService class

At the heart of Example 2-1 is a class called HelloWorldService. This class is a subclass of System.Web.Services.WebService. By inheriting from the WebService class, a web service gains direct access to the ASP.NET intrinsic objects, such as Application and Session, just like any other ASP.NET application.

TIP: While inheriting from the WebService class is a common approach for creating a .NET web service, it is by no means necessary. You can rewrite the previous examples without this inheritance, and your service will run just fine. However, if you need access to the Application and Session objects without inheriting from WebService, you'll need to use the System.Web.HttpContext object explicitly, as we'll explain in a later chapter.

Pages: 1, 2, 3, 4

Next Pagearrow