ATL Server Architecture | COM Programming with Microsoft .NET

The ATL Server architecture consists of four main elements:

A Web server, which passes HTTP requests from clients to ATL Server DLLs
ISAPI extension DLLs, which are passed requests by the Web server, and which route them to an appropriate Web application DLL
Web application DLLs, which provide application-specific functionality for handling requests and generating responses

Server Response Files (SRFs), which are text files that contain the static part of the response

Note	If you are familiar with ASP.NET, Server Response Files are analogous to .aspx files, and Web application DLLs are analogous to the code-behind files that implement the ASP application functionality.

An ATL Server project will be made up of one ISAPI extension DLL and one or more ATL Server application DLLs. The ISAPI extension DLL caches the loaded ATL Server DLLs and the parsed SRF files, and it contains a thread pool for handling client requests. The ATL Server application DLLs contain classes for parsing SRF files and replacing SRF file tags with HTML. The architecture of an ATL Server application is shown diagrammatically in Figure 7-1.

Figure 7-1: The architecture of an ATL Server application

Well now consider ISAPI extensions, Web application, DLLs, and SRF files in more detail.

ISAPI Extensions

ISAPI (Internet Server API) provides a way to write plug-in DLLs for Microsoft Internet Information Services (IIS). There are two types of ISAPI DLLs: filters , which are used by IIS to filter incoming HTTP requests, and extensions , which provide functionality for Web applications. In this section, Im talking only about extensions because ATL Server has no support for writing ISAPI filters.

Although ISAPI extensions have performance and scalability benefits when compared with ASP pages, they have traditionally been hard to write because they have to be coded in C or C++ and use API calls rather than classes. ATL Server makes the task of creating and using ISAPI extensions much easier by splitting off the application-specific functionality and placing it in a Web application DLL.

Web Application DLLs

An ATL Server Web application DLL contains one or more classes that implement request handler functions. An SRF file will have one or more Web application DLLs associated with it. Each tag occurring within the SRF file is mapped onto a request handler function in a DLL; when the SRF is processed , the request handler is called, which will usually result in text being echoed to the response stream.

Server Response Files

A Server Response File (an SRF file, also known as a stencil ) is the ATL Server equivalent of an ASP file, in that it contains a mixture of static HTML and tags that will be used to generate custom content at run time. In the case of SRF files, the tags are calls to methods in an ATL Server DLL. The tags, which appear within double curly brackets, are called replacement tags . As with ASP pages, the dynamic content is separated from the static layout because the code resides in a Web application DLL.

Browser clients use the URL of an SRFfor example, http://myserver/ myapp.srf to connect to the server. The ISAPI DLL is registered as the default handler for SRF files, and it processes the SRF file, making use of the ATL Server Web application DLL to provide dynamic content.

SRF files are often passed in as part of the HTTP request URL, but they can also be held as resources. SRF files contain three types of information:

The name of the handler class for this SRF and the DLL that houses it
Static HTML for the returned page
Placeholder tags in the HTML that are replaced with dynamic content at run time

Here is a simple SRF file that demonstrates the replacement tag syntax:

 {{handlerHelloHandler.dll/Default}} <html> <body> {{Hello}} </body> </html>

When a client requests the URL of this file, IIS loads the HelloHandler.dll if necessary, and then passes it the request. The SRF file is processed by the stencil processor code that is part of ATL Server. Once SRF files have been parsed by the processor, they are cached so that they can be used over again without the need for further parsing. Obviously, if the text in the SRF file is modified, the file will be reprocessed and the cache refreshed.

When the SRF has been processed, the {{Hello}} tag results in a call to a method in the DLL, which generates HTML output that is merged with the page.

Note	Static content within an SRF file is usually HTML or XML, but it can be any text that doesnt conflict with the formatting used by SRF tags.

SRF Syntax

The syntax of SRF files is simple because there are only six predefined replacement tags. These tags are listed in Table 7-12.

Table 7-12: Predefined Replacement Tags for SRFs
Name	Description
codepage	Used to define the code page to be used for processing the file, if the file contains characters that are not part of the ANSI character set.
comment	Places a comment in the SRF file that will be removed during processing. Comments can continue over more than one line, and are placed between {{// and }} markers.
handler	Identifies a request handler class that will be used to process some or all of the replacement tags within the SRF file. There should be only one handler tag in an SRF file.
include	Inserts the contents of another SRF file.
locale	Used to indicate the locale that should be used for any response generated from the file, from the locale tag onwards.
subhandler	Used to identify a request handler that will be used to process some or all of the replacement tags within a file. There can be more than one subhandler tag in an SRF file.

Handler and Subhandler Tags

Often, all the user -defined replacement tags within an SRF file will be part of a single DLL. A handler replacement tag is placed at the top of an SRF file to name this DLL, using the following syntax:

 {{ handler  path_to_dll/request_handler  }}

In the handler tag, path_to_dll is the path to the handler DLL. This path can be absolute or relative to the directory containing the SRF file. Also in the handler tag, request_handler is the name of the request handler within the file that is going to handle the request. You need the name because a handler DLL can contain more than one handler class. Note that the name of the request handler is not necessarily the name of the class within the DLL that implements the handler. Using a separate name allows you to hide code-naming conventions and provide user-friendly names .

Note	See the Writing Web Applications Using ATL Server section for details of how handler classes are implemented, and how request handlers are named.

There should be only one handler tag per SRF file; any subsequent handler tags will be silently ignored when the file is processed. Here is an example of a handler tag:

 {{//Thefollowinglinedefinesahandlertag}} {{handlerMyHandler.dll/TheHandler}}

The handler DLL is MyHandler.dll, which is located in the same directory as the SRF file, and the name of the handler is TheHandler .

You can have replacement tags within an SRF file handled by more than one DLL. Any secondary handler DLLs are defined using subhandler tags, which use the following syntax:

 {{ subhandler  namespace path_to_dll  /  request_handler  }}

As with the handler tag, the subhandler tag gives the path to the handler DLL and specifies the name of the request handler within the DLL. It also defines a namespace, which is used to prefix tags within the SRF file so that the processor can tell which DLL should be used to locate the function:

 {{//Thehandlertagforthefile}} {{handlerMyHandler.dll/TheHandler}} {{//Asubhandlertag}} {{subhandlerauxMyOtherHandler.dll/OtherHandler}} {{//ThismethodispartofTheHandler}} {{Method1}} {{//ThismethodispartofOtherHandler}} {{aux.Method2}}

You can see how the subhandler tag defines the aux namespace, which is then used to prefix Method2 . Since Method1 does not have a prefix, it is taken as being part of TheHandler .

Including Files

The include tag can be used within an SRF file to include the contents of another file. The included file can be one of three types:

A file containing static HTML, which is merged with the enclosing SRF file.
Another SRF file, in which case handlers are loaded as appropriate, and the file is processed in the normal manner.
An ATL Server Web application DLL. In this case, the file name can contain a query string, which will be passed to the DLL when it is loaded.

Here is an example of how the include tag is used:

 {{//IncludeanHTMLfile}} {{includeBoilerplate.html}} {{//ProcessanotherSRFfile}} {{includeFile2.srf}}

Defining Replacement Tags

Replacement tags are added to SRF files to show where dynamic content should be inserted. As I mentioned previously, processing a replacement tag results in calling a method implemented by a handler class in an ATL Server Web application DLL.

The simplest use of replacement tags encloses the name of the tag within double curly brackets. This is used to call handler methods that have no arguments:

 {{//CalltheWelcomemethod}} {{Welcome}}

By default, the DLL specified in the handler tag will be used to execute the tag. If you have used subhandlers, you need to specify the name of the subhandler to use a tag that is implemented by the subhandler DLL. The preceding example for defining subhandlers showed how the syntax works.

You can pass arguments to replacement methods by placing them in parentheses after the method name:

 {{//Passtwoarguments}} {{AMethod(5,Sunday)}}

Arguments are always passed through as strings and will be converted by the handler method. The following section, Writing Web Applications Using ATL Server, shows how to implement replacement methods that take arguments.

You can use the if / else / endif and while / endwhile constructs within replacement tags to perform conditional processing. Here is a simple example:

 {{//Conditionalprocessing}} {{ifDayIsSunday}} TodayisSunday {{else}} TodayisnotSunday {{endif}}

The key to conditional processing in SRF files is that handler methods always return a status code. If that code is HTTP_SUCCESS , the text within the if block will be passed to the output stream. In the preceding example, the DayIsSunday handler method will return HTTP_SUCCESS if the day is Sunday, and the string Today is Sunday will be echoed to the output file. If any other value is returned, the string Today is not Sunday will be echoed instead.

A while loop can be constructed in the same way:

 {{//Conditionalprocessing}} {{whileMoreData}} <tr><td>{{GetData}}</td></tr> {{endwhile}}

In this example, as long as the replacement method MoreData returns HTTP_SUCCESS , the text within the body of the loop will be repeatedly echoed to the output, which will result in rows being added to a table. Note how the text within the body of the loop calls another replacement method to retrieve the data.