Web Services

As part of ASP.NET support, PerlASPX provides developers with additional facility besides creating ASP.NET Web pages: creating Web services. Web services are much like the PerlNET components that we created throughout this book. You declare the class with methods that may then be invoked by the Web service clients. The major difference is that Web services run on the Web server and the methods are called remotely through the network. Hence, the infrastructure for Web services differs from one for regular PerlNET components.

By exposing Web services to the developers, the Web sites become “smarter.” Suppose you want to perform some orders through the Internet on a regular basis. You will either do it manually each time or you may create a very complicated application that will perform the HTTP connection, parse the HTML files, fill in the forms, and finally submit them. The second option is very challenging and interesting (I once did it!), but it is time consuming and is bound to the structure of the Web site and its HTML files that may change. It is a lot more convenient to create the same order by remotely invoking a couple of methods on the Web site like on the regular local object. This is what the Web services are about.

Web services rely on certain network protocols to perform the method invocation through the network. In the heart of these protocols lies XML, which helps to describe Web services definitions (methods, types of parameters, return values, and so on) to the clients on different platforms.

Creating Web Services

The code for Web services is placed on the Web server (like .aspx pages) in the file with an .asmx extension. You can test Web services using Internet Explorer simply by referring to the URL of the .asmx file.

Our first sample represents simple Web service with one method, which concatenates two strings passed to it as parameters. Here is the code for the StringServer.asmx Web service (it resides under the chapter samples folder).

<%@ WebService class="StringServer" Language="perl" %>

package StringServer;

=for interface
   [System.Web.Services.WebMethod]
   str Concat(str str1, str str2);
=cut

sub Concat 
{
   my ($this, $str1, $str2) = @_;

   return($str1 . $str2);
}

We start our Web service declaration with the ASP.NET WebService directive in the first line of the .asmx file. We define the class name and the language to use. Then we follow the regular procedure of defining a PerlNET component by defining the =for interface block and supplying the code for method's subroutine. Note that the methods you want to be accessible by the clients as part of the Web services API should be marked with the WebMethod attribute that resides in the System.Web.Services namespace.

Now, let us test our first Web service by navigating to its URL (http://localhost/NetPerl/StringServer.asmx) with Internet Explorer. Figure 16-16 shows the page that is displayed for our Web service.

For each method of a Web service, there is a link on its Web page. In our case, there is only one Concat link, which we will follow. On the displayed page (Figure 16-17) we may fill in the parameters for the Concat method of our StringServer Web service and press the Invoke button.

The result is displayed inside a new browser window in the XML format

<?xml version="1.0" encoding="utf-8" ?>
<string xmlns="http://tempuri.org/">Have a nice day </string>

Web Service Client Program

It is nice to test our Web service inside the Web browser. However, the more ambitious task is to write our own client program for Web service. This program will call the Web methods in the same way as other .NET methods are called.

To create client programs for certain Web service, we first write a proxy class that will handle all the infrastructure of passing parameters to the Web service and extracting the return values from the XML. Fortunately, there is an automatic tool that generates such proxy class: wsdl. This tool reads the XML description of the Web service. The description is written in WSDL (Web Service Definition Language). The wsdl tool extracts all the required information and generates the code for the proxy class. The default language of wsdl is C#.

To create a proxy file for our StringServer Web service, we run wsdl from the command line with the following parameters:

wsdl /out:StringProxy.cs
         http://localhost/NetPerl/StringServer.asmx?WSDL

The http://localhost/NetPerl/StringServer.asmx?WSDL URL returns the WSDL XML file for the StringServer Web service. The generated proxy is placed in the StringProxy.cs file. This file defines the StringServer class with the Concat method (along with other auxiliary methods).

. . .
public class StringServer : 
System.Web.Services.Protocols.SoapHttpClientProtocol {

   /// <remarks/>
   public StringServer() {
      this.Url = 
      "http://localhost/NetPerl/StringServer.asmx";
   }

   /// <remarks/>
   . . .
   public string Concat(string str1, string str2) {
      object[] results = this.Invoke("Concat",
      new object[] {str1,str2});
        return ((string)(results[0]));
   }
   . . .

We may compile this class into a DLL and then reference it in our PerlNET client program. Here is the simple testing PerlNET client for StringServer (we placed it in the StringServerCli folder along with the generated C# proxy class file).

#
# StringServerCli.pl
#

my $str_svr = StringServer->new();
my $str = $str_svr->Concat("Good", " Luck!");
print $str, "
";

First, we compile the proxy class.

csc /target:library StringProxy.cs

Then we may build our client program.

plc -reference="StringProxy.dll" StringServerCli.pl

Both compilation commands are inside the build.bat file in the sample directory. As a result of running StringServerCli.exe, we obtain the following output:

Good Luck!

Creating a Web Client

After we generate the proxy class, we may reference it in ASP.NET pages and create the Web client. The StringWebCli.aspx Web page from the StringWebCli folder implements such a client, providing the user with a simple form to supply parameters for the StringServer Web service. Pressing the Concatenate button will display the result returned by the Concat method of our Web service. Figure 16-18 demonstrates our Web client.

Since we create a Web client, we have to be cautious when displaying special characters, such as '<' and '>', that may occur in strings we concatenate. Hence, we use the HtmlEncode method of the HttpServerUtility class to display the resulting string correctly.

To keep it simple, we placed all the code inside the StringWebCli.aspx page without using the code-behind. Here is this code.

<!-- StringWebCli.aspx -->
<%@ Assembly Name="StringProxy" %>
<%@ Page Language="Perl" %>
<HTML>
<BODY>
<CENTER>
<H2>String Server Web Client</H2>

<SCRIPT RUNAT="SERVER">
=for interface
   public void btnConcat_Click(System.Object source, 
                               System.EventArgs e);
=cut

sub btnConcat_Click
{
   my $this = shift;

   my $str1 = $this->{txtStr1}->{Text};
   my $str2 = $this->{txtStr2}->{Text};
   my $str_svr = "StringServer"->new();
							my $result = $str_svr->Concat($str1, $str2);
							my $writer = "System.IO.StringWriter"->new();
							$this->{Server}->HtmlEncode($result, $writer);
							$this->{lblResult}->{Text} = $writer->ToString();
}
</SCRIPT>

<BR>
<FORM RUNAT="SERVER">
<TABLE border=0>
<TR>
   <TD>
   First String:
   </TD>
   <TD>
   <asp:TextBox RUNAT="SERVER" id="txtStr1"/>
   </TD>
</TR>
<TR>
   <TD>
   Second String:
   </TD>
   <TD>
   <asp:TextBox RUNAT="SERVER" id="txtStr2"/>
   </TD>
</TR>
</TABLE>
<BR>
<asp:button RUNAT="SERVER" TEXT="Concatenate" id=btnConcat
onClick=btnConcat_Click/>
</FORM>
<BR>
<B><asp:Label RUNAT="SERVER" id="lblResult"/></B>
</CENTER>
</BODY>
</HTML>

Please run the build.bat script to compile the proxy class and create the Web application using IIS for the sample folder before running the sample.

Web Services Summary

We demonstrated the main concepts and principles of developing Web services in Perl using simple examples. We are sure that you will be able to extrapolate our samples and explanation and build powerful and useful applications based on Web services and ASP.NET technologies.