The ASMX file shown in Example 11-1 is a complete Web service. It implements two Web methods: Add and Subtract. Both take two integers as input and return an integer as well. Deploying the Web service is as simple as copying it to a directory on your Web server that is URL-addressable. If you put Calc.asmx in wwwroot, the Web service’s local URL is http://localhost/calc.asmx.

Calc.asmx demonstrates several important principles of Web service programming using the .NET Framework:

Despite its brevity, Calc.asmx is a full-blown Web service when installed on a Web server outfitted with ASP.NET. Its Web methods can be invoked with SOAP, HTTP GET, and HTTP POST, and it’s capable of returning output in SOAP responses or simple XML wrappers. All we need now is a way to test it out. The .NET Framework lends a hand there too.

How do you test an ASMX Web service? Simple: just call it up in your browser. To demonstrate, copy Calc.asmx to wwwroot and type

http://localhost/calc.asmx

in your browser’s address bar. You’ll be greeted with the screen shown in Figure 11-2. What happened? ASP.NET responded to the HTTP request for Calc.asmx by generating an HTML page that describes the Web service. The name and description in the ASMX file’s WebService attribute appear at the top of the page. Underneath is a list of Web methods that the service exposes, complete with the descriptions spelled out in the WebMethod attributes.

Figure 11-2. Calc.asmx as seen in Internet Explorer.

Like what you’ve seen so far? It gets better. Click “Add” near the top of the page, and ASP.NET displays a page that you can use to test the Add method (Figure 11-3). ASP.NET knows the method name and signature because it reads them from the metadata in the DLL it compiled from Calc.asmx. It even generates an HTML form that you can use to call the Add method with your choice of inputs. Type 2 and 2 into the “a” and “b” boxes and click Invoke. The XML returned by the Web method appears in a separate browser window (Figure 11-4).

Figure 11-3. Test page for the Add method.

Figure 11-4. XML returned by the Add method.

The forms that ASP.NET generates on the fly from ASMX files enable you to test the Web services that you write without writing special clients to test them with. They also let you explore a Web service built with the .NET Framework simply by pointing your browser to it. For kicks, type the following URL into your browser’s address bar:

http://terraservice.net/terraservice.asmx

That’s the URL of the Microsoft TerraService, an ultra-cool Web service that provides a programmatic interface to a massive database of geographic data known as the Microsoft TerraServer. Don’t worry about the details just yet; you’ll be using TerraService to build a Web service client later in this chapter. But do notice how much you can learn about TerraService simply by viewing the page that ASP.NET generated for it.

You can use code-behind to move Web service classes out of ASMX files and into separately compiled DLLs. Example 11-5 shows how Calc.asmx looks after it’s modified to take advantage of code-behind. The ASMX file now contains just one statement. The class referenced in that statement is implemented in Calc.cs. The following command compiles Calc.cs into a DLL named Calc.dll:

csc /t:library calc.cs

Once compiled, the DLL must be placed in the application root’s bin subdirectory (for example, wwwrootin).

<%@ WebService Class="CalcService" %>

using System;
using System.Web.Services;

[WebService (Name="Calculator Web Service",
    Description="Performs simple math over the Web")]
class CalcService
{
    [WebMethod (Description="Computes the sum of two integers")]
    public int Add (int a, int b)
    {
        return a + b;
    }

    [WebMethod
        (Description="Computes the difference between two integers")]
    public int Subtract (int a, int b)
    {
        return a - b;
    }
}

Code-behind offers the same benefits to Web services that it offers to Web pages: it catches compilation errors before the service is deployed, and it enables you to write Web services in languages that ASP.NET doesn’t natively support. For an example of ASP.NET code written in managed C++ and for a refresher on code-behind in general, turn back to Chapter 5.

Very often when you see ASMX code samples, the Web service classes inside them derive from a class named WebService, as in

class CalcService : WebService
{
  ...
}

WebService belongs to the System.Web.Services namespace. It contributes properties named Application, Session, Context, Server, and User to derived classes, enabling a Web service to access the ASP.NET objects with the same names. If you don’t use these objects in your Web service—for example, if you don’t use application state or session state—you don’t need to derive from WebService either.

The WebMethod attribute tags a method as a Web method. The .NET Framework automatically exposes such methods as Web methods when they’re implemented inside a Web service. WebMethod is capable of doing much more, however, than simply letting the framework know which methods are Web methods and which are not; it also supports the following parameters:

CacheDuration is the ASMX equivalent of an @ OutputCache directive in an ASPX or ASCX file: it caches a method’s output so that subsequent requests will execute more quickly. Suppose, for example, that you write a Web method that returns the current time:

[WebMethod]
public string GetCurrentTime ()
{
    return DateTime.Now.ToShortTimeString ();
}

Since ToShortTimeString returns a string that includes minutes but not seconds, it’s wasteful to execute it too often. The following method declaration uses CacheDuration to cache the output for 10 seconds at a time:

[WebMethod (CacheDuration="10")]
public string GetCurrentTime ()
{
    return DateTime.Now.ToShortTimeString ();
}

Now the data that the method returns could be stale by a few seconds, but if the Web service is getting pounded with calls to GetCurrentTime, the load on it will be reduced commensurately.

Web services enjoy access to the same session state facilities that conventional ASP.NET applications do. By default, however, session state is disabled for Web methods. You can enable it with WebMethod’s EnableSession parameter. If you want to use session state in a Web service, derive from WebService (to inherit its Session property) and tag each Web method that uses session state with EnableSession=“true”:

class CalcService : WebService
{
    [WebMethod (EnableSession="true",
        Description="Adds an item to a shopping cart")]
    public void AddToCart (Item item)
    {
        ShoppingCart cart = (ShoppingCart) Session["MyShoppingCart"];
        cart.Add (item);
    }
}

Session state utilization is less common in Web services than in conventional Web applications, but it is an option nonetheless.

The MessageName parameter lets you assign a Web method a name other than that of the method that implements it. For example, suppose that you build two Add methods into a Web service—one that adds integers and another that adds floating point values—and you tag both of them as Web methods:

[WebMethod]
public int Add (int a, int b)
{
    return a + b;
}

[WebMethod]
public float Add (float a, float b)
{
    return a + b;
}

The only problem with this code is that it doesn’t compile. C# methods can be overloaded, but Web methods cannot. The solution? Either change the method names or add MessageName parameters to the WebMethod attributes, as demonstrated here:

[WebMethod (MessageName="AddInts")]
public int Add (int a, int b)
{
    return a + b;
}

[WebMethod (MessageName="AddFloats")]
public float Add (float a, float b)
{
    return a + b;
}

Now the C# methods remain overloaded, but the corresponding Web methods are named AddInts and AddFloats.

If other developers are to consume (that is, write clients for) a Web service that you author, they need to know what Web methods your service publishes, what protocols it supports, the signatures of its methods, and the Web service’s location (URL), among other things. All this information and more can be expressed in a language called the Web Services Description Language, or WSDL for short.

WSDL is a relatively new standard. It’s an XML vocabulary devised by IBM, Microsoft, and others. Its syntax is documented at http://www.w3.org/TR/wsdl. I won’t describe the details of the language here for several reasons. First, the details are already documented in the spec. Second, WSDL is a language for machines, not humans. Third, it’s trivial to generate a WSDL contract for a Web service built with the .NET Framework: simply point your browser to the Web service’s URL and append a WSDL query string, as in

http://www.wintellect.com/calc.asmx?wsdl

Figure 11-6 shows the result. Scan through it and you’ll find a service element that describes the Web service; operation elements that document the “operations,” or Web methods, that the service supports; binding elements that document the protocols that the Web methods support; and other descriptive information.

Figure 11-6. WSDL contract for Calc.asmx.

When you publish a Web service, you should also publish a WSDL contract describing it. For a Web service built with the .NET Framework, the contract is usually nothing more than a URL with ?wsdl on the end. Other developers can use the contract to write clients for your Web service. Typically, they don’t read the contract themselves. Instead, they run it through a tool that generates a wrapper class containing all the elements needed to talk to a Web service. The .NET Framework SDK includes one such tool: it’s called Wsdl.exe. You’ll learn all about it later in this chapter when we turn our attention from Web services to Web service clients.

It’s not hard to understand how simple data types can be passed to and from Web methods. After all, integers and other primitive types are defined in one form or another on virtually every platform. But what about more complex types? What if, for example, you define a custom class or struct and want to use it as an input parameter or return value for a Web method? Are complex types supported, and if so, how do you declare them so that they become an intrinsic part of the Web service?

Complex types are supported, and they work very well because virtually any type can be represented in XML. As an example, consider the Web service in Example 11-7. It exposes a Web method named FindStores that accepts a state abbreviation (for example, “CA”) as input. FindStores calls a local method named FindByState, which queries the Pubs database that comes with Microsoft SQL Server for all the bookstores in the specified state and returns the results in an array of Bookstore objects. (Observe that FindByState is not a Web method because it lacks a WebMethod attribute.) FindStores returns the array to the client. Bookstore is a custom type defined in the ASMX file.

Figure 11-8 shows the XML returned when FindStores is called with the input string “CA”. The array of Bookstore objects has been serialized into XML. The serialization is performed by the .NET Framework’s System.Xml.Serialization.XmlSerializer class, otherwise known as the “XML serializer.” A client application that receives the XML and that has a schema describing the structure and content of the data can rehydrate the information into Bookstore objects. Or it can take the raw XML and do with it as it pleases.

<%@ WebService Language="C#" Class="LocatorService" %>

using System;
using System.Web.Services;
using System.Data;
using System.Data.SqlClient;

[WebService (Name="Bookstore Locator Service",
    Description="Retrieves bookstore information from the Pubs database")]
class LocatorService
{
    [WebMethod (Description="Finds bookstores in a specified state")]
    public Bookstore[] FindStores (string state)
    {
        return FindByState (state);
    }

    Bookstore[] FindByState (string state)
    {
        SqlDataAdapter adapter = new SqlDataAdapter
            ("select * from stores where state = ’" + state + "’",
            "server=localhost;database=pubs;uid=sa;pwd=");
        DataSet ds = new DataSet ();
        adapter.Fill (ds);

        DataTable table = ds.Tables[0];
        Bookstore[] stores = new Bookstore[table.Rows.Count];

        for (int i=0; i<table.Rows.Count; i++) {
            stores[i] = new Bookstore (
                table.Rows[i]["stor_name"].ToString ().TrimEnd
                    (new char[] { ’ ’ }),
                table.Rows[i]["stor_address"].ToString ().TrimEnd
                    (new char[] { ’ ’ }),
                table.Rows[i]["city"].ToString ().TrimEnd
                    (new char[] { ’ ’ }),
                table.Rows[i]["state"].ToString ().TrimEnd
                    (new char[] { ’ ’ })
            );
        }
        return stores;
    }
}

public class Bookstore
{
    public string Name;
    public string Address;
    public string City;
    public string State;

    public Bookstore () {}

    public Bookstore (string name, string address, string city,
        string state)
    {
        Name = name;
        Address = address;
        City = city;
        State = state;
    }
}

Figure 11-8. XML returned by the FindStores method.

Where might a client obtain an XML schema describing the Bookstore data type? From the service’s WSDL contract, of course. Sneak a peek at Locator.asmx’s WSDL contract and you’ll see the Bookstore data type (and arrays of Bookstores) defined this way in the contract’s types element:

<s:complexType name="ArrayOfBookstore">
  <s:sequence>
    <s:element minOccurs="0" maxOccurs="unbounded"
      name="Bookstore" nillable="true" type="s0:Bookstore" /> 
  </s:sequence>
</s:complexType>
<s:complexType name="Bookstore">
  <s:sequence>
    <s:element minOccurs="1" maxOccurs="1" name="Name"
      nillable="true" type="s:string" /> 
    <s:element minOccurs="1" maxOccurs="1" name="Address"
      nillable="true" type="s:string" /> 
    <s:element minOccurs="1" maxOccurs="1" name="City"
      nillable="true" type="s:string" /> 
    <s:element minOccurs="1" maxOccurs="1" name="State"
      nillable="true" type="s:string" /> 
  </s:sequence>
</s:complexType>

Given these definitions, a client can define a Bookstore class of its own and initialize arrays of Bookstore objects by deserializing Bookstore elements. It’s not as hard as it sounds. If the client is written with the .NET Framework, tools generate the class definitions for you and the framework handles the deserialization.

As Locator.asmx demonstrates, it’s not difficult to write Web methods that use custom types. There are, however, two gotchas to be aware of:

Keep these caveats in mind and you’ll have few problems combining Web methods and custom data types.

Once a client has a WSDL contract describing a Web service, it has all the information it needs to make calls to that Web service. But when you publish a Web service by making it available on a Web server, how do clients find out where to get a WSDL contract? For that matter, how do clients know that your Web service exists in the first place?

The answer comes in two parts: DISCO and Universal Description, Discovery, and Integration, better known as UDDI. The former is a file-based mechanism for local Web service discovery—that is, for getting a list of available Web services from DISCO files deployed on Web servers. The latter is a global Web service directory that is itself implemented as a Web service. UDDI is discussed in the next section.

The DISCO (short for “discovery”) protocol is a simple one that revolves around XML-based DISCO files. The basic idea is that you publish a DISCO file on your Web server that describes the Web services available on it and perhaps on other servers as well. Clients can interrogate the DISCO file to find out what Web services are available and where the services’ WSDL contracts can be found. As an example, suppose you publish two Web services and their URLs are as follows:

To advertise these Web services, you can deploy the following DISCO file at a well-known URL on your server. The contractRef elements identify the URLs of the Web services’ WSDL contracts. URLs can be absolute or relative (relative to the directory in which the DISCO file resides). The optional docRef attributes identify the locations of documents describing the Web services, which, because of the self-documenting nature of Web services built with the .NET Framework, are typically the ASMX files themselves:

<?xml version="1.0" ?>
<discovery xmlns="http://schemas.xmlsoap.org/disco/"
  xmlns:scl="http://schemas.xmlsoap.org/disco/scl/">
  <scl:contractRef ref="http://www.wintellect.com/calc.asmx?wsdl"
    docRef="http://www.wintellect.com/Calc.asmx" />
  <scl:contractRef ref="http://www.wintellect.com/locator.asmx?wsdl"
    docRef="http://www.wintellect.com/Locator.asmx" />
</discovery>

If you’d prefer, you can write DISCO files for individual Web services and reference them in a master DISCO file using discoveryRef elements. Here’s a DISCO file that points to other DISCO files. Once more, URLs can be absolute or relative:

<?xml version="1.0" ?>
<discovery xmlns="http://schemas.xmlsoap.org/disco/">
  <discoveryRef ref="http://www.wintellect.com/calc.disco" />
  <discoveryRef ref="http://www.wintellect.com/locator.disco" />
</discovery>

A third option is to deploy a VSDISCO file to enable dynamic discovery. The following VSDISCO file automatically exposes all ASMX and DISCO files in a host directory and its subdirectories, with the exception of those subdirectories noted with exclude elements:

<?xml version="1.0" ?>
<dynamicDiscovery
  xmlns="urn:schemas-dynamicdiscovery:disco.2000-03-17">
  <exclude path="_vti_cnf" />
  <exclude path="_vti_pvt" />
  <exclude path="_vti_log" />
  <exclude path="_vti_script" />
  <exclude path="_vti_txt" />
</dynamicDiscovery>

How does dynamic discovery work? ASP.NET maps the file name extension .vsdisco to an HTTP handler that scans the host directory and subdirectories for ASMX and DISCO files and returns a dynamically generated DISCO document. A client that requests a VSDISCO file gets back what appears to be a static DISCO document.

For security reasons, Microsoft disabled dynamic discovery just before version 1.0 of the .NET Framework shipped. You can reenable it by uncommenting the line in the httpHandlers section of Machine.config that maps *.vsdisco to System.Web.Services.Discovery.DiscoveryRequestHandler and granting the ASPNET account permission to access the IIS metabase. Microsoft highly discourages dynamic discovery for fear of compromising your Web server, and a bug in version 1.0 of the .NET Framework SDK prevents most DISCO-aware tools from working with VSDISCO anyway. My advice is to forget that VSDISCO files even exist and use static DISCO files instead.

To further simplify Web service discovery, you can link to a master DISCO file from your site’s default HTML document. For example, suppose the default HTML document at www.wintellect.com is Default.html and that the same directory also holds a discovery document named Default.disco. Including the following HTML in Default.html enables most tools that read DISCO files to accept the URL www.wintellect.com (as opposed to www.wintellect.com/default.disco):

<html>
  <head>
    <link type="text/html" rel="alternate" href="Default.disco">
  </head>
</html>

Visual Studio .NET (specifically, its Add Web Reference command) reads DISCO files; so does the Disco.exe utility that comes with the .NET Framework SDK.

DISCO’s chief disadvantage is that you can’t read a DISCO file if you don’t have its URL. So how do you find a Web service if you don’t even have a URL to start with? Can you spell U-D-D-I?

UDDI is an abbreviation for Universal Description, Discovery, and Integration. Jointly developed by IBM, Microsoft, and Ariba and supported by hundreds of other companies, UDDI is a specification for building distributed databases that enable interested parties to “discover” each other’s Web services. No one company owns the databases; anyone is free to publish a UDDI-based business registry. Operator sites have already been established by IBM and Microsoft and are likely to be the first of many such sites that will come on line in the future.

UDDI sites are themselves Web services. They publish a pair of SOAP-based APIs: an inquiry API for inquiring about companies and their Web services and a publisher API for advertising a company’s Web services. Anyone can call the inquiry API, but operator sites typically limit the publisher API to registered members. Documentation regarding these APIs and other information about UDDI can be found at http://www.uddi.org. At the time of this writing, Microsoft was beta testing a UDDI .NET SDK featuring managed wrapper classes that simplify interactions with UDDI business registries. For the latest information on this and other UDDI development tools proffered by Microsoft, visit http://uddi.microsoft.com/default.aspx.

Most developers will never deal with UDDI APIs directly. Instead, they’ll use high-level tools such as Visual Studio .NET to query UDDI business registries and generate wrapper classes that allow them to place calls to the Web services that they find there. The actual placing of UDDI calls will be limited primarily to tools vendors and to clients that wish to locate and bind to Web services dynamically.

The key concept to grasp when writing Web service clients is that of the Web service proxy. A Web service proxy is an object that provides a local representation of a remote Web service. A proxy is instantiated in the client’s own application domain, but calls to the proxy flow through the proxy and out to the Web service that the proxy represents. The Wsdl.exe utility that comes with the .NET Framework SDK (and that is integrated into Visual Studio .NET) generates Web service proxy classes from WSDL contracts. Once a proxy is created, calling the corresponding Web service is a simple matter of calling methods on the proxy, as shown here:

CalculatorWebService calc = new CalculatorWebService ();
int sum = calc.Add (2, 2);

The methods in the proxy class mirror the Web methods in the Web service. If the Web service exposes Web methods named Add and Subtract, the Web service proxy also contains methods named Add and Subtract. When you call one of these methods, the proxy packages up the input parameters and invokes the Web method using the protocol encapsulated in the proxy (typically SOAP). The proxy insulates you from the low-level details of the Web service and of the protocols that it uses. It even parses the XML that comes back and makes the result available as managed types.

Using Wsdl.exe to generate a Web service proxy is simplicity itself. Suppose you want to call a Web service whose URL is http://www.wintellect.com/calc.asmx. If the Web service was written with the .NET Framework, which means you can retrieve a WSDL contract by appending a ?wsdl query string to the service URL, you can generate a proxy for the Web service like this:

wsdl http://www.wintellect.com/calc.asmx?wsdl

Or you can leave off the query string and let Wsdl.exe supply it for you:

wsdl http://www.wintellect.com/calc.asmx

If Calc.asmx wasn’t written with the .NET Framework, it might not support WSDL query strings. In that case, you find the WSDL contract and pass its URL (or local path name) to Wsdl.exe. The following example assumes that the contract is stored in a local file named Calc.wsdl:

wsdl calc.wsdl

However you point it to the WSDL contract, Wsdl.exe generates a CS file containing a class that represents the Web service proxy. That’s the class you instantiate to invoke the Web service’s methods.

The proxy class’s name comes from the service name (that is, the name attribute accompanying the service element) in the WSDL contract. For example, suppose you attribute a Web service as follows in its ASMX file:

[WebService (Name="Calculator Web Service")]

The resulting <service> tag in the WSDL contract looks like this:

<service name="Calculator Web Service">

and the resulting proxy class is named CalculatorWebService. By default, the name of the CS file that Wsdl.exe generates also derives from the service name (for example, Calculator Web Service.cs). You can override that name by passing Wsdl.exe a /out switch. The command

wsdl /out:Calc.cs http://www.wintellect.com/calc.asmx

names the output file Calc.cs regardless of the service name.

Wsdl.exe supports a number of command line switches that you can use to customize its output. For example, if you’d prefer the proxy class to be written in Visual Basic .NET rather than C#, use the /language switch:

wsdl /language:vb http://www.wintellect.com/calc.asmx

If you’d like Wsdl.exe to enclose the code that it generates in a namespace (which is extremely useful for preventing collisions between types defined in the generated code and types defined in your application and in the FCL), use the /namespace switch:

wsdl /namespace:Calc http://www.wintellect.com/calc.asmx

Classes generated by Wsdl.exe derive from base classes in the FCL’s System.Web.Services.Protocols namespace. By default, a proxy class derives from SoapHttpClientProtocol, which enables it to invoke Web methods using SOAP over HTTP. You can change the invocation protocol with Wsdl.exe’s /protocol switch. The command

wsdl /protocol:httpget http://www.wintellect.com/calc.asmx

creates a Web service proxy that derives from HttpGetClientProtocol and calls Web methods using HTTP GET commands, while the command

wsdl /protocol:httppost http://www.wintellect.com/calc.asmx

creates a proxy that derives from HttpPostClientProtocol and uses HTTP POST. Why would you want to change the protocol that a proxy uses to invoke Web methods? In the vast majority of cases, SOAP is fine. However, if the methods that you’re calling are simple methods that use equally simple data types, switching to HTTP GET or POST makes calls slightly more efficient by reducing the amount of data transmitted over the wire.

Incidentally, if you use Visual Studio .NET to write Web service clients, you don’t have to run Wsdl.exe manually. When you use the Add Web Reference command found in the Project menu, Visual Studio .NET runs Wsdl.exe for you and adds the proxy class to your project. Add Web Reference also speaks the language of UDDI, making it easy to search Microsoft’s UDDI registry for interesting Web services.

Want to write a client for Calc.asmx? Here are the steps:

Look through a CS file generated by Wsdl.exe, and you’ll see the Web service proxy class as well as the methods that wrap the Web service’s Web methods. You’ll also see that the Web service’s URL is hardcoded into the CS file in the proxy’s class constructor. Here’s an example:

public CalculatorWebService() {
    this.Url = "http://www.wintellect.com/calc.asmx";
}

If the Web service moves, you’ll have to modify the CS file and regenerate the proxy.

To avoid having to update code when a Web service’s URL changes, you can use Wsdl.exe’s /appsettingurlkey (abbreviated /urlkey) switch. The command

wsdl /urlkey:CalcUrl http://www.wintellect.com/calc.asmx

produces the following class constructor:

public CalculatorWebService() {
    string urlSetting =
System.Configuration.ConfigurationSettings.AppSettings["CalcUrl"];
    if ((urlSetting != null)) {
        this.Url = urlSetting;
    }
    else {
        this.Url = "http://www.wintellect.com/calc.asmx";
    }
}

Now you can assign a value to “CalcUrl” in the appSettings section of a local Web.config file, like so:

<configuration>
  <appSettings>
    <add key="CalcUrl" value="http://www.wintellect.com/calc.asmx" />
  </appSettings>
</configuration>

If the URL changes, you can update the proxy simply by editing Web.config. No code changes are required.

Something else you’ll notice if you open a CS file generated by Wsdl.exe is that the proxy class contains asynchronous as well as synchronous wrappers around the Web service’s methods. The former can be used to invoke Web methods asynchronously. An asynchronous call returns immediately, no matter how long the Web service requires to process the call. To retrieve the results from an asynchronous call, you make a separate call later on.

Here’s an example using Calc.asmx’s Add method that demonstrates how to invoke a Web method asynchronously. The client calls the proxy’s BeginAdd method to initiate an asynchronous call and then goes off to attend to other business. Later it returns to finish the call by calling EndAdd:

CalculatorWebService calc = new CalculatorWebService ();
IAsyncResult res = calc.BeginAdd (2, 2, null, null);
  .
  .
  .
int sum = calc.EndAdd (res);

If the call hasn’t completed when EndAdd is called, EndAdd blocks until it does. If desired, a client can use the IsCompleted property of the IAsyncResult interface returned by BeginAdd to determine whether the call has completed and avoid calling EndAdd prematurely:

IAsyncResult res = calc.BeginAdd (2, 2, null, null);
  .
  .
  .
if (res.IsCompleted) {
    int sum = calc.EndAdd (res);
}
else {
    // Try again later
}

Another option is to ask to be notified when an asynchronous call returns by providing a reference to an AsyncCallback delegate wrapping a callback method. In the next example, EndAdd won’t block because it isn’t called until the client is certain the method call has returned:

AsyncCallback cb = new AsyncCallback (AddCompleted);
IAsyncResult res = calc.BeginAdd (2, 2, cb, null);
  .
  .
  .
public void AddCompleted (IAsyncResult res)
{
    int sum = calc.EndAdd (res);
}

Whatever approach you decide on, the proxy’s asynchronous method–call support is extraordinarily useful for calling methods that take a long time to complete. Add isn’t a very realistic example because it’s such a simple method, but the principle is valid nonetheless.

If a client invokes methods on a Web service from behind a proxy server, the Web service proxy needs to know the address of the proxy server. You can provide that address in two ways. The first option is to pass Wsdl.exe a /proxy switch specifying the proxy server’s URL:

wsdl /proxy:http://myproxy http://www.wintellect.com/calc.asmx

Option number two is to programmatically initialize the Web service proxy’s Proxy property (which it inherits from HttpWebClientProtocol) with a reference to a WebProxy object (System.Net.WebProxy) identifying the proxy server:

CalculatorWebService calc = new CalculatorWebService ();
calc.Proxy = new WebProxy (http://myproxy, true);
int sum = calc.Add (2, 2);

The true passed to WebProxy’s constructor bypasses the proxy server for local addresses. Pass false instead to route all requests through the proxy server.

CityView consists of three files:

CityView.aspx is a Web form that defines CityView’s user interface. Its source code appears in Example 11-12. The user interface consists of a TextBox for typing city names, a DropDownList for selecting states, a RadioButtonList for choosing scales, and a Button for posting back to the server and fetching images. It also includes an Image control whose ImageUrl property is programmatically initialized following each postback. Here’s the code that assigns a URL to the Image control:

MyImage.ImageUrl = builder.ToString ();

If you enter Redmond, WA, and accept the default scale of 8 meters, the string assigned to ImageURL looks like this:

CityView.ashx?city=Redmond&state=WA&scale=8

which sets the stage perfectly for a discussion of the second component of CityView: namely, CityView.ashx.

CityView.ashx is an HTTP handler. Specifically, it’s an HTTP handler that generates and returns a bitmap image of the location named in a query string. When we deployed an HTTP handler in Chapter 8, we coded the handler in a CS file, compiled it into a DLL, and dropped the DLL into the application root’s bin directory. We also registered the handler using a Web.config file. CityView.ashx demonstrates the other way to deploy HTTP handlers. You simply code an IHttpHandler-derived class into an ASHX file and include an @ WebHandler directive that identifies the class name and the language in which the class is written:

<%@ WebHandler Language="C#" Class="CityViewImageGen" %>

When a client requests an ASHX file containing a WebHandler class, ASP.NET compiles the class for you. The beauty of deploying an HTTP handler in an ASHX file is that you don’t have to register the handler in a CONFIG file or in the IIS metabase; you just copy the ASHX file to your Web server. The downside, of course, is that you must test the handler carefully to make sure ASP.NET can compile it.

The CityViewImageGen class inside CityView.ashx (Example 11-12) generates the images that CityView.aspx displays. Its heart is the ProcessRequest method, which is called on each and every request. ProcessRequest calls a local method named GetTiledImage to generate the image. Then it returns the image in the HTTP response by calling Save on the Bitmap object encapsulating the image:

bitmap.Save (context.Response.OutputStream, format);

Should GetTiledImage fail, ProcessRequest returns a simple bitmap containing the words “Image not available” instead of an aerial photograph. It also adjusts the format of the bitmap to best fit the type of content returned: JPEG for photographs, and GIF for bitmaps containing text.

GetTiledImage uses three TerraService Web methods:

A “tile” is a 200-pixel-square image of a particular geographic location. To build larger images, a TerraService client must fetch multiple tiles and stitch them together to form a composite. That’s how GetTiledImage generates the 600 x 400 images that it returns. It starts by creating a Bitmap object to represent the image. Then it uses Graphics.DrawImage to draw each tile onto the image. The logic is wholly independent of the image size, so if you’d like to modify CityView to show larger (or smaller) images, find the statement

Bitmap bitmap = GetTiledImage (city, state, res, 600, 400);

in CityView.ashx and change the 600 and 400 to the desired width and height.

The third and final component of CityView is TerraService.dll, which contains the TerraService proxy class named TerraService. CityView.ashx’s GetTiledImage method instantiates the proxy class and uses the resulting object to call TerraService’s Web methods:

TS.TerraService ts = new TS.TerraService ();

TerraService.dll was compiled from TerraService.cs, which I generated with the following command:

wsdl /namespace:TS http://terraservice.net/terraservice.asmx

The namespace was necessary to prevent certain data types defined in TerraService’s WSDL contract from conflicting with data types defined in the .NET Framework Class Library. Once TerraService.cs was created, the command

csc /t:library terraservice.cs

compiled it into a DLL.

<html>
  <body>
    <h1>CityView</h1>
    <hr>
    <form runat="server">
      <table cellpadding="8">
        <tr>
          <td>
            City
          </td>
          <td>
            <asp:TextBox ID="City" Width="100%" RunAt="server" />
          </td>
          <td>
            <asp:RequiredFieldValidator
              ControlToValidate="City"
              ErrorMessage="*"
              Display="static"
              Color="red"
              RunAt="server"
            />
          </td>
        </tr>
        <tr>
          <td>
            State
          </td>
          <td>
            <asp:DropDownList ID="State" Width="100%" RunAt="server">
              <asp:ListItem Text="AL" RunAt="server" />
              <asp:ListItem Text="AK" RunAt="server" />
              <asp:ListItem Text="AR" RunAt="server" />
              <asp:ListItem Text="AZ" RunAt="server" />
              <asp:ListItem Text="CA" RunAt="server" />
              <asp:ListItem Text="CO" RunAt="server" />
              <asp:ListItem Text="CT" RunAt="server" />
              <asp:ListItem Text="DC" RunAt="server" />
              <asp:ListItem Text="DE" RunAt="server" />
              <asp:ListItem Text="FL" RunAt="server" />
              <asp:ListItem Text="GA" RunAt="server" />
              <asp:ListItem Text="HI" RunAt="server" />
              <asp:ListItem Text="IA" RunAt="server" />
              <asp:ListItem Text="ID" RunAt="server" />
              <asp:ListItem Text="IL" RunAt="server" />
              <asp:ListItem Text="IN" RunAt="server" />
              <asp:ListItem Text="KS" RunAt="server" />
              <asp:ListItem Text="KY" RunAt="server" />
              <asp:ListItem Text="LA" RunAt="server" />
              <asp:ListItem Text="MA" RunAt="server" />
              <asp:ListItem Text="MD" RunAt="server" />
              <asp:ListItem Text="ME" RunAt="server" />
              <asp:ListItem Text="MI" RunAt="server" />
              <asp:ListItem Text="MN" RunAt="server" />
              <asp:ListItem Text="MO" RunAt="server" />
              <asp:ListItem Text="MS" RunAt="server" />
              <asp:ListItem Text="MT" RunAt="server" />
              <asp:ListItem Text="NC" RunAt="server" />
              <asp:ListItem Text="ND" RunAt="server" />
              <asp:ListItem Text="NE" RunAt="server" />
              <asp:ListItem Text="NH" RunAt="server" />
              <asp:ListItem Text="NJ" RunAt="server" />
              <asp:ListItem Text="NM" RunAt="server" />
              <asp:ListItem Text="NV" RunAt="server" />
              <asp:ListItem Text="NY" RunAt="server" />
              <asp:ListItem Text="OH" RunAt="server" />
              <asp:ListItem Text="OK" RunAt="server" />
              <asp:ListItem Text="OR" RunAt="server" />
              <asp:ListItem Text="PA" RunAt="server" />
              <asp:ListItem Text="RI" RunAt="server" />
              <asp:ListItem Text="SC" RunAt="server" />
              <asp:ListItem Text="SD" RunAt="server" />
              <asp:ListItem Text="TN" RunAt="server" />
              <asp:ListItem Text="TX" RunAt="server" />
              <asp:ListItem Text="UT" RunAt="server" />
              <asp:ListItem Text="VA" RunAt="server" />
              <asp:ListItem Text="VT" RunAt="server" />
              <asp:ListItem Text="WA" RunAt="server" />
              <asp:ListItem Text="WI" RunAt="server" />
              <asp:ListItem Text="WV" RunAt="server" />
              <asp:ListItem Text="WY" RunAt="server" />
            </asp:DropDownList>
          </td>
          <td>
          </td>
        </tr>
        <tr>
          <td>
          </td>
          <td>
            <fieldset>
              <legend>Scale</legend>
              <asp:RadioButtonList ID="Scale" RunAt="server"
                RepeatColumns="2" RepeatDirection="Horizontal">
                <asp:ListItem Text="1 meter" RunAt="server" />
                <asp:ListItem Text="2 meters" RunAt="server" />
                <asp:ListItem Text="4 meters" RunAt="server" />
                <asp:ListItem Text="8 meters" Selected="true"
                  RunAt="server" />
                <asp:ListItem Text="16 meters" RunAt="server" />
                <asp:ListItem Text="32 meters" RunAt="server" />
              </asp:RadioButtonList>
            </fieldset>
          </td>
          <td>
          </td>
        </tr>
        <tr>
          <td>
          </td>
          <td>
            <asp:Button Text="Show Image" OnClick="OnShowImage"
              Width="100%" RunAt="server" />
          </td>
          <td>
          </td>
        </tr>
      </table>
    </form>
    <hr>
    <asp:Image ID="MyImage" RunAt="server" />
  </body>
</html>

<script language="C#" runat="server">
  void OnShowImage (Object sender, EventArgs e)
  {
      StringBuilder builder = new StringBuilder ();
      builder.Append ("CityView.ashx?city=");
      builder.Append (City.Text);
      builder.Append ("&state=");
      builder.Append (State.SelectedItem.Text);
      builder.Append ("&scale=");

      switch (Scale.SelectedIndex) {
      case 0:
          builder.Append ("1");
          break;

      case 1:
          builder.Append ("2");
          break;

      case 2:
          builder.Append ("4");
          break;

      case 3:
          builder.Append ("8");
          break;

      case 4:
          builder.Append ("16");
          break;

      case 5:
          builder.Append ("32");
          break;
      }

      MyImage.ImageUrl = builder.ToString ();
  }
</script>

<%@ WebHandler Language="C#" Class="CityViewImageGen" %>

using System;
using System.Web;
using System.Drawing;
using System.Drawing.Imaging;
using System.IO;

public class CityViewImageGen : IHttpHandler
{
    public void ProcessRequest (HttpContext context)
    {
        // Extract user input from the query string
        string city = context.Request["City"];
        string state = context.Request["State"];
        string scale = context.Request["Scale"];

        if (city != null && state != null) {
            // Determine the scale
            TS.Scale res = TS.Scale.Scale8m;

            if (scale!= null) {
                switch (scale) {
                case "1":
                    res = TS.Scale.Scale1m;
                    break;

                case "2":
                    res = TS.Scale.Scale2m;
                    break;

                case "4":
                    res = TS.Scale.Scale4m;
                    break;

                case "8":
                    res = TS.Scale.Scale8m;
                    break;

                case "16":
                    res = TS.Scale.Scale16m;
                    break;

                case "32":
                    res = TS.Scale.Scale32m;
                    break;
                }
            }

            // Generate the requested image
            string type = "image/jpeg";
            ImageFormat format = ImageFormat.Jpeg;
            Bitmap bitmap = GetTiledImage (city, state, res, 600, 400);

            // If GetTiledImage failed, generate an error bitmap
            if (bitmap == null) {
                bitmap = GetErrorImage ("Image not available");
                type = "image/gif";
                format = ImageFormat.Gif;
            }

            // Set the response’s content type
            context.Response.ContentType = type;

            // Write the image to the HTTP response
            bitmap.Save (context.Response.OutputStream, format);

            // Clean up and return
            bitmap.Dispose ();
        }
    }

    public bool IsReusable
    {
        get { return true; }
    }

    Bitmap GetTiledImage (string City, string State, TS.Scale Scale,
        int cx, int cy)
    {
        Bitmap bitmap = null;
        Graphics g = null;

        try {
            // Instantiate the TerraService proxy
            TS.TerraService ts = new TS.TerraService ();

            // Get the latitude and longitude of the requested city
            TS.Place place = new TS.Place ();
            place.City = City;
            place.State = State;
            place.Country = "USA";
            TS.LonLatPt point = ts.ConvertPlaceToLonLatPt (place);

            // Compute the parameters for a bounding box
            TS.AreaBoundingBox abb = ts.GetAreaFromPt (point,
                TS.Theme.Photo, Scale, cx, cy);

            // Create an image to fit the bounding box
            bitmap = new Bitmap (cx, cy,
                PixelFormat.Format32bppRgb);
            g = Graphics.FromImage (bitmap);

            int x1 = abb.NorthWest.TileMeta.Id.X;
            int y1 = abb.NorthWest.TileMeta.Id.Y;
            int x2 = abb.NorthEast.TileMeta.Id.X;
            int y2 = abb.SouthWest.TileMeta.Id.Y;

            for (int x=x1; x<=x2; x++) {
                for (int y=y1; y>=y2; y--) {
                    TS.TileId tid = abb.NorthWest.TileMeta.Id;
                    tid.X = x;
                    tid.Y = y;
                    Image tile = Image.FromStream
                        (new MemoryStream (ts.GetTile (tid)));
                    g.DrawImage (tile,
                        (x - x1) * tile.Width  -
                        (int) abb.NorthWest.Offset.XOffset,
                        (y1 - y) * tile.Height -
                        (int)abb.NorthWest.Offset.YOffset,
                        tile.Width, tile.Height);
                    tile.Dispose();
                }
            }

            // Return the image
            return bitmap;
        }
        catch (Exception) {
            if (bitmap != null)
                bitmap.Dispose ();
            return null;
        }
        finally {
            if (g != null)
                g.Dispose ();
        }
    }

    Bitmap GetErrorImage (string message)
    {
        // Determine the width and height of the error message
        Bitmap bitmap =
            new Bitmap (1, 1, PixelFormat.Format32bppRgb);
        Graphics g = Graphics.FromImage (bitmap);
        Font font = new Font ("Verdana", 10);
        SizeF size = g.MeasureString (message, font);
        int cx = (int) size.Width;
        int cy = (int) size.Height;
        bitmap.Dispose ();
        g.Dispose ();

        // Generate a bitmap containing the error message
        bitmap = new Bitmap (cx, cy, PixelFormat.Format32bppRgb);
        g = Graphics.FromImage (bitmap);
        SolidBrush redBrush = new SolidBrush (Color.Red);
        SolidBrush whiteBrush = new SolidBrush (Color.White);

        g.FillRectangle (whiteBrush, 0, 0, 256, 64);
        g.DrawString (message, font, redBrush, 0, 0);

        whiteBrush.Dispose ();
        redBrush.Dispose ();
        font.Dispose ();
        g.Dispose ();

        // Return the image
        return bitmap;
    }
}