Procedure 3-1. Create the VISAValidator Project

1. Start Visual Studio .NET

2. Create a new Visual Studio .NET project using either the C# or Microsoft Visual Basic .NET ASP.NET Web Service project template.

3. In the New Project dialog box, shown here, specify the following URL, at which the new project will be created: http://localhost/XMLWebServices/Chapter03/VisaValidator

   

Procedure 3-2. Add a Reference to the CreditCardValidator library

1. Right-click on the References folder in Solution Explorer and select Add Reference from the shortcut menu.

   

2. Click the Browse button in the Add Reference dialog box.

3. In the Select Component dialog box, navigate to the directory where the CreditCardValidator.dll library is located; it will be in the SamplesCreditCardValidator subdirectory of the location where you stored the sample code.

4. Select the CreditCardValidator.dll file, and then click Open.

   You will return to the Add Reference dialog box and can see that the Selected Components list now contains an entry for the CreditCardValidator.dll, as shown here:

   

5. Click OK.

6. On the Solution Explorer toolbar, click the Show All Files button to reveal the project’s hidden files and directories.

7. Expand the bin folder. You’ll see that it contains a copy of CreditCardValidator.dll.

   

Procedure 3-3. Implement the VISA Card Validation Functionality

1. Select Service1.asmx in Solution Explorer. Press F2, or right-click on the file name and select Rename from the shortcut menu. Rename Service1.asmx Validation.asmx.

   The default name of Service1.asmx is not descriptive enough and could cause confusion when developing client applications that consume the XML Web service. Visual Studio .NET automatically renames the code-behind file and the resource file associated with the .asmx file, which you can see in the following screenshot.

   

2. In Solution Explorer, right-click Validation.asmx and select View Code from the shortcut menu.

   This opens the code-behind file, either Validation.asmx.cs or Validation.asmx.vb depending on the language you are using.

3. Ignore the rest of the template-generated code, but locate and delete the commented out HelloWorld method that we used in Chapter 2. We do not need it and it clutters up our code. Make sure you delete the following lines.

   Example 3-1. C#

   // 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, press F5
   
   //    [WebMethod]
   //    public string HelloWorld()
   //    {
   //        return "Hello World";
   //    }

   Example 3-2. Visual Basic.NET

   ‘ 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

4. Add the appropriate statement to the top of the file to import the XMLWebServicesStepByStep.CreditCardValidator namespace. The implementation of this namespace is contained in the CreditCard­Validator.dll library that we added a reference to earlier.

   The C# project template imports more namespaces by default than the Visual Basic .NET project template; most of these namespaces are currently superfluous, so you can ignore them for now. After adding the new import statement, the full list of imports should appear as follows.

   Example 3-3. C#

   using System;
   using System.Collections;
   using System.ComponentModel;
   using System.Data;
   using System.Diagnostics;
   using System.Web;
   using System.Web.Services;
   
   // the following statement allows the 
   // credit card library to be used
   using XMLWebServicesStepByStep.CreditCardValidator;

   Example 3-4. Visual Basic .NET

   Imports System.Web.Services
   
   ‘ the following statement allows the 
   ‘ credit card library to be used
   Imports XMLWebServicesStepByStep.CreditCardValidator

5. Locate the Service1 class declaration. We need to change its name to CreditCardValidator and apply the WebService attribute to it. The Visual Basic .NET project template supplies a default WebService attribute that must be replaced. Change the Service1 class declaration to appear as follows.

   Example 3-5. C#

   [WebService(Namespace="http://mycompany.com/webservices/",
       Name="VISAValidator",
       Description="A service to validate VISA card numbers.")]
   public class CreditCardValidator: System.Web.Services.WebService

   Example 3-6. Visual Basic .NET

   <WebService(Namespace:="http://mycompany.com/webservices/", _
       Name:="VISAValidator", _
       Description:="A service to validate VISA card numbers.")> _
   Public Class CreditCardValidator
       Inherits System.Web.Services.WebService

6. If you are using C#, because we changed the name of the Service1 class to CreditCardValidator, we must also change the constructor name; this is not necessary in Visual Basic .NET. For C# projects, change the Service1 constructor declaration to the following.

   public CreditCardValidator ()

7. Add the ValidateVISACard method as a member of the CreditCardValidator class.

   The ValidateVISACard method has public accessibility and is annotated with the WebMethod attribute, making it available to XML Web service consumers. When invoked, the ValidateVISACard method instantiates a Validator object (implemented in the CreditCardValidator.dll library) and calls the Validator.ValidateVisa method to validate the supplied VISA card number. The Boolean result is returned to the caller. As described in the code comments, the Validator.ValidateVisa method can throw an exception if the VISA card number is incorrectly formatted. We will ignore the exceptions for now, saving a discussion of them until Chapter 7.

   Example 3-7. C#

   [WebMethod(Description="Validate a VISA card number.")]
   public bool ValidateVISACard(string p_card_number) {
       try {
           return new Validator().ValidateVisa(p_card_number);
       } catch (System.ApplicationException) {
           // although the ValidateVisa method in the Validator
           // class throws exceptions, we will ignore them 
           // for now.
           return false;   
       }
   }

   Example 3-8. Visual Basic .NET

   <WebMethod(Description:="Validate a VISA card number.")> _
   Public Function _
       ValidateVISACard(ByVal p_card_number As String) _
       As Boolean
       Try
           Return New Validator().ValidateVisa(p_card_number)
       Catch x_ex As System.ApplicationException
           ‘ although the ValidateVisa method in the Validator
           ‘ class throws exceptions, we will ignore them for now.
           Return False
       End Try
   End Function

8. The final step is to build the project. Select Build Solution from the Build menu or press Ctrl+Shift+B. We will test our new XML Web service later in this chapter, after we have provided more detail on the XML Web service you just created.

Procedure 3-4. Load the VISAValidator Service Help Page

1. With the VisaValidator project open in Visual Studio .NET, press F5.

   Internet Explorer is launched and loads the Validation.asmx file from the VisaValidator project. You will see the service help page for the VISAValidator XML Web service, as shown here.

   

   The page structure for VISAValidator is similar to that of the Hello­World example, but if you compare them, you will notice the following differences that result from the changes we made to the VISAValidator code.

   • The name of the XML Web service and the title of the page are VISAValidator. This is the name we specified in the Name property of the WebService attribute applied to the CreditCardValidator class. By default, the name of the class to which the WebService attribute is applied (CreditCardValidator) would have been used, as was the case with the HelloWorld example.

   • A description of the VISAValidator XML Web service appears at the top of the page immediately below the service name. We specified this description using the Description property of the WebService attribute that was applied to the CreditCardValidator class.

   • The link to the ValidateVISACard method is followed immediately by its description. We specified this information using the Description property of the WebMethod attribute applied to the CreditCardValidator.ValidateVISACard method.

   • The warnings about the use of default XML namespaces that you can see on the HelloWorld page are no longer present. These warnings are absent because we specified our own namespace using the Namespace property of the WebService attribute applied to the CreditCardValidator class.

2. Click the Service Description link.

   Clicking this link displays the Web Services Description Language (WSDL) contract for the VISAValidator service, but we will not go into the details of the content.

Procedure 3-5. Test the ValidateVISACard Web Method

1. Click the ValidateVISACard link on the VISAValidator service help page. This link takes you to a page, shown here, where you can test the ValidateVISACard operation.

   

   At the top of the page, below the operation name and description, is a Test section. The Test section consists of a simple form containing a text field named p_card_number and an Invoke button. When we tested the HelloWorld example, there was only an Invoke button, no text fields, because the HelloWorld method did not require any input arguments. When testing an XML Web service operation that takes arguments, a form is automatically generated with a text field for each parameter. Note that no type checking is performed at the client end before the arguments are sent to the XML Web service.

   Important

   If you test the VISAValidator XML Web service in an environment in which network traffic travels across an insecure network, you should not use real credit card numbers. The credit card numbers are transmitted in clear text and are easily readable if intercepted.

2. To test the ValidateVISACard operation, type a VISA card number into the p_card_number text field and click the Invoke button.

   Because the HTTP-GET protocol is used to submit the request to the VISAValidator service, the response is not a Simple Object Access Protocol (SOAP) message, but it is XML. For example, if you type in the invalid card number 1234567890, the response would be

   <?xml version="1.0" encoding="utf-8" ?> 
   <boolean xmlns="http://mycompany.com/webservices/">false</boolean> 

   Below the Test section are three further sections named SOAP, HTTP-GET, and HTTP-POST. As with the HelloWorld example, these sections contain the request and response message formats for each of the three protocols. Although we will not describe the content of these messages, it is interesting to compare the messages for the HelloWorld and ValidateVISACard operations and look at the effect the use of input parameters has on the message structure.