ColdFusion WS Consumer for a WS Created in VS2003

Introduction

There are two examples in this tutorial. The first example creates a web service in VS 2003 that does not take any argument. The consumer (ColdFusion user) accesses this service using ColdFusion scripting, <cfscript/>. The second example creates a web service using the VS2003 IDE which accepts arguments. This time the ColdFusion client uses the tag based syntax to call this service by sending arguments. The motivation for this step by step guidance is for the user to develop the necessary hands-on skill to work with web services using two different programming languages.

ColdFusion Server with IIS

In order to run the code in this tutorial and to use ColdFusion with IIS, you need to install the ColdFusion server that is supported by IIS. The detailed step-by-step procedure is explained in the article Installing the ColdFusionMX Server. The ColdFusion MX 6.1 software is an application server that supports the ColdFusion specific scripting platform. ColdFusion MX 6.1 Server is supported by the Windows 2003 (IIS 6) server, Solaris 9, and Linux 8+ from several vendors. CFMX is a compiler that compiles CFMX to Java Bytecode; it used to be that CFML was first converted to Java source, which was then compiled. The 6.1 version goes directly from CFML to Bytecode. ColdFusion MX 7 and its updater ColdFusion MX 7.0.1 have also been released.

First example

The Web Service with VS2003 IDE

Creating the Web Service

Step 1: This is a very simple example. The web service when called returns a HTML page which contains a single line of text, which is linked to a web site. To create this, click File ->New->Project to open the following window. It is suggested that you give a descriptive name to your project instead of WebService1. Notice that the project will be on your localhost.

Step 2: Click OK to the above window to open the project. The project comes with a default Service1.asmx page. Again it is recommended that you use an identifiable name. Only methods or properties will be used in the tutorial, therefore switch to the code view. The code view already has a template for web service called HelloWorld () commented out (in green). This is a functioning program.

You will create a program as shown in the next screen shot of the code view. You will be adding everything between <WebMethod ()> ...End Function after removing the default HelloWorld () code.

Step 3: Your code is now ready. Just browse the Service1.asmx file in your preferred browser. Highlight Service1.asmx and right click. You can browse the file with your default browser. Or, if you prefer, you can the Browse With option, in which case you can either choose one from your listed browsers, or use an internal browser (similar to the Cassini browser). What you will see will be the following display,

The Service Description hyperlink will take you to what is called the WSDL. Make sure you read the linked items at the bottom of the page, as it provides links to the underlying protocols for web services. You may also get a bird's eye view of what it is by reading my other article.  

Step 4: Click on the FindJay hyperlink to open the following window. This window shows the Soap Request/Response that goes with the HTTP Request/Response to the server and back. You may also test the Webservice by clicking on the Invoke button, which executes the Web method () on the server. The result of this is the XML response shown in the following display:

Step 5: Now how does the client, your ColdFusion client know where the Service1.asmx file of the above web service is?  This information is what is available in the Service Description hyperlink discussed above. It gives all the details. The details can be captured by appending the query ?WSDL to the URL as follows: http://localhost/FindJay/Service1.asmx?WSDL.

The Consumer using ColdFusion

ColdFusion has two ways to create clients that consume web services. The first method creates a webservice object, and through it the methods are invoked by discovering the service description. This is the method that will be used for this example. In the next example, the tag based syntax directly calls the web service by sending arguments to it.

Step 6: Now create a file called CFFindJay.cfm and code as shown below. The client browses the file CFFindJay.cfm to access the service. The code follows:

<cfscript>
ws = CreateObject("webservice",
"http://localhost/FindJay/Service1.asmx?WSDL");
fndstrg = ws.FindJay();
</cfscript>
#fndstrg#

CreateObject() creates a ColdFusion Component (CFC) and the calling syntax is:

Hence the variable ws in the code above creates a "webservice" type of object, and the WSDL is the component-name. As mentioned earlier, the component-name is the URL with “? WSDL” appended to it. To invoke the components' methods, you call the functions in the component, in this case FindJay (). We know beforehand that the method returns a string; therefore we will be looking for a string and display it like any other function.

Step 7: Place the CFM file in the appropriate folder on your server (it is assumed that ColdFusion has been installed as discussed in the introduction). Now if you browse this folder you will see the following in the display.

Second Example

The web service that takes arguments

This service is a simple example from geometry. The two sides that make the right angle in a triangle are given and it is required to find the third side, called the hypotenuse. This theorem is attributed to Pythogoras, a Greek mathematician. The service accepts two arguments and returns the length of hypotenuse.

Step 1: We will abbreviate the steps as it follows a similar pattern to the one in the first example. Create a Web Service project, herein called SQRoot. Create an Asmx file called SQRUT. asmx. Insert the following code in the code page after removing the default, commented text as shown below. Observe that System.Math class has been imported. This class defines the Sqrt () method.

In this step a web service file has been created. You can find its WSDL as was shown previously. The WSDL file for this service is found at the URL: http://localhost/SQRoot/SQRUT.asmx?Wsdl

The Consumer using ColdFusion

Step 2: Create a ColdFusion file as shown below. ColdFusion special tags, <cfinvoke/>, <cfinvokeargument name="" value=""/> are used to call the web service from its URL and supply arguments with the "invoke argument" tags. The tag <cfinvoke> can be either a component, or a web service that starts looking for functions defined therein. This function is named CF_SQRUT.cfm in this tutorial.

<cfinvoke
webservice="http://localhost/SQRoot/SQRUT.asmx?Wsdl"
method="hypotenuse"
returnvariable="hypotenuse">
<cfinvokeargument name ="x" value="3"/>
<cfinvokeargument name="y" value="4"/>
</cfinvoke>
<cfoutput>
Hypotenuse of the triangle is : 
#hypotenuse#
</cfoutput>

Step 3: Upload the code to the root directory, or copy and paste to a suitable folder in your web root folder. When you browse this file, you will see the following displayed.

Summary

Interoperability is the mantra of web services. In an ideal world, any machine on the internet working with any kind of platform and language should be able to access the web service on the Internet. The technology is moving towards this ideal situation.  This tutorial shows how to create web services easily with VS2003 IDE and consume these with code written in ColdFusion.