Consuming Web Services

The first step to using a Web Service is to add a reference to it, using the Add Web Reference menu item from the solution context menu. You will then see the Add Web Reference dialog (see Figure 16.4) that allows you to browse to the URL of the service. Once you click the Go button, the service will be examined for Web methods (that is, those with a WebMethod attribute), which will be displayed in the lower part of the window. You then give the Web reference a name (which becomes the name the Web Service will have when it is added to the solution) and click the Add Reference button (see Figure 16.5).

Figure 16.4. Adding a Web reference

Figure 16.5. Naming the Web reference

Once the reference is added, you can access it like any other type. For example, Listing 16.3 shows how to instantiate a Web Service and call a method. In this case, the GetShippers method, which returns a DataSet, is used as the source of data for a grid.

Listing 16.3. Using a Web Service Synchronously

localhostNorthwind.Northwind nws =   new localhostNorthwind.Northwind(); GridView1.DataSource = nws.GetShippers(); GridView1.DataBind();

Listing 16.4 shows that passing parameters to a Web Service is exactly like any other method call; here, the InsertShipper method is called, passing in the values of two TextBox fields.

Listing 16.4. Passing Parameters to a Web Service

localhostNorthwind.Northwind nws =   new localhostNorthwind.Northwind(); int ShipperID = nws.InsertShipper(   ShipperNameTextBox.Text, PhoneNumberTextBox.Text); ShipperIDLabel.Text = "ShipperID = " & ShipperID.ToString();

Calling Web Services Asynchronously

When calling Web Services, you are generally calling another machine, often over the Internet, and are therefore dealing with a relatively slow service (compared to standard method calls, which are in-process). Because of this, you should consider the asynchronous pattern to call Web Services.

In ASP.NET 1.1, you had to use the Begin and End methods created by the proxy, as shown in Listing 16.5. You call the Begin method, passing in a callback, the method to be run when the Web Service finishes.

Listing 16.5. The Asynchronous Pattern in ASP.NET 1.1

private System.IAsyncResult _asyncResult; private void Page_Load(object sender, System.EventArgs e) {   localhost.Northwind nws = new localhost.Northwind();   _asyncResult = nws.BeginGetShippers(_name,     new AsyncCallback(WriteResult), null); } private void WriteResult(IAsyncResult result) {   DataSet result = _service.EndGetShippers(result); }

In ASP.NET 2.0, that pattern is supported, but the recommended approach is to use a new pattern, as seen in Listing 16.6. You use the Async method to call the event, and the Completed event to process the results. The Completed event is raised when the Web Service call is done. You can see this in Listing 16.5, where the GetShippersCompleted event is hooked into an event handler called _service_GetShippersComplete (you could use an anonymous method if you require). The Web Service is then started asynchronously with a call to GetShippersAsync, and when complete the event will be raised.

Within the event, the second parameter contains a property called Result, which is the actual result of the Web Service call, and in the code this is simply used as a data source for a grid.

Listing 16.6. Using a Web Service Asynchronously

private localhostNorthwind.Northwind _service; protected void Button2_Click(object sender, EventArgs e) {   _service = new localhostNorthwind.Northwind();   _service.GetShippersCompleted +=     new localhostNorthwind.GetShippersCompletedEventHandler(     _service_GetShippersComplete);   _service.GetShippersAsync(); } void _service_GetShippersComplete(object sender,      localhostNorthwind.GetShippersCompletedEventArgs e) {   GridView1.DataSource = e.Result;   GridView1.DataBind(); }

This is a much simpler and more intuitive pattern for dealing with Web Services asynchronously.

Handling Errors

You handle errors from Web Services in the same manner as other code, by using exceptions. You generally only deal with network exceptions (for example, the service was unavailable) or SOAP exceptions. You can use the SoapException (in the System.Web.Services.Protocols namespace) to detect specific problems, or WebException (in the System.Net namespace) for network problems, as seen in Listing 16.7.

The WebException will deal with network problems, such as a 401 error, while the SoapException will be used for exceptions within the Web Service. With SoapException you don't have access to an inner exception (it will be null), because it's an XML SOAP packet you receive back from the Web Service, rather than a local exception object. You do, however, have access to the message, stack trace, help links, and so on, just like other exceptions. If you raise exceptions within Web Service code, these will be wrapped in a SoapException.

Listing 16.7. Trapping SOAP Exceptions

try {   localhostNorthwind.Northwind nws =     new localhostNorthwind.Northwind();   int ShipperID = nws.InsertShipper(     ShipperNameTextBox.Text, PhoneNumberTextBox.Text);   ShipperIDLabel.Text = "ShipperID = " + ShipperID.ToString(); } catch (SoapException soapex) {   MessagLabel.Text = "SOAP Exception" +     soapex.ToString(); } catch (WebException webex) { }