Using the ATL Server Project Wizard

The ATL Server Project Wizard provides options for changing the way the project will be created. Although the wizard is a one-step wizard, it offers many potential scenarios for creating an ATL Server project. Some items may be changed in the project property pages window after the project is created, and others must be set in the wizard since they cannot be changed later. Visual Studio .NET does allow you to change any given project into another type of project, but the effort to perform such a task manually is time consuming. If you want to change a project from one type to another type of project, many problems can be avoided simply by saving the desired code and pasting it in to a project generated by the proper project template in Visual Studio .NET. Knowing what options are available in the ATL Server Project Wizard can save you time and help you become familiar with and reliably use the options that are available in ATL Server.

Project Settings

The Project Settings tab in the ATL Server Project Wizard (shown in Figure 16-7) allows you to set the virtual directory to which the project will be deployed when compiled, but this directory may be changed any time using the project property pages window. The project names and directories may also be changed after the ATL Server Project Wizard generates the solution files, but the ability to generate a single DLL to host both the ISAPI code and the web application code should be set prior to finishing the wizard.

click to expand
Figure 16-7: Project Settings in the ATL Server Project Wizard

A savvy developer could probably edit the project settings well enough to change any given project into any other project type, but for the sake of making the change reliably and saving time, it is far easier to change the wizard settings for some configurations that pertain to the production binary file type. Names of projects and parts of the solution and file path changes are easily made in the project property pages window at any time, and sometimes small edits are required elsewhere in the project.

Server Options in the ATL Server Project Wizard

The Server Options tab in the ATL Server Project Wizard (shown in Figure 16-8) provides support for some advanced integration with server host services and session management. For session management, a session may be written to a data source that has an OLE DB provider, such as a database. Such is the case in a web cluster deployment, where placing session data inside a data source is necessary if other servers participating in hosting the web solution must access the session.

click to expand
Figure 16-8: Server Options tab in the ATL Server Project Wizard

If the ATL Server project is designed to operate on a single server, or the solution requires no collaboration with other web servers using the session, the Memory-Backed Session State Services option can be chosen, and it offers greater performance. The OLE DB-Backed Session State Services option provides greater extendibility of the solution since the solution may be deployed to a distributed hardware environment without making any changes to the code. If the solution’s requirement calls for any sort of session support, check the checkbox for the Session Services. The respective OLE DB-Backed or Memory-Backed selection may be chosen based on the desired level of support.

When the ATL Server Project Wizard generates the code, a class with the same name as the project, but prefixed with a C and suffixed by the phrase Handler, is created. This class is designed to be the web application interface to IIS by hosting the tag handlers. For example, if the project shown in Figure 16-7 is named atlServer4, the class that is created by the wizard for hosting the tag handlers is named CatlServer4Handler.

Checking any of the following checkboxes on the Server Options tab of the wizard causes code to be included in the handler class that declares and initializes the pointers to each respective supporting class:

  • Blob Cache Adds a pointer for a class instance of IMemoryCache to the project for managing arbitrary chunks of memory.

  • File Cache Adds a pointer for a class instance of IFileCache to the project for managing filenames.

  • Data Source Cache Adds many classes to the ATL Server project and the ISAPI project for managing per-thread caching of OLE DB connections.

  • Predefined Performance Counters Add classes for integrating the project with perfmon performance counters.

  • Browser Capabilities Support Adds a pointer for a class instance of IBrowserCapsSvs to the project for managing browser capacities.

For example, if the server options for File Cache, Blob Cache, and Browser Capabilities Support were selected in the wizard, and the project was named SimpleATLServer, the class named CSimpleATLServerHandler would be generated and written to the header file SimpleATLServer.h. In the private section of the class CSimpleATLServerHandler, the following declarations would be generated with comments in front of the code:

   // File cache support //   CComPtr<<IFileCache>> m_spFileCache;    // Blob cache support //   CComPtr<<IMemoryCache>> m_spBlobCache;    // Data Source cache support //   CComPtr<<IBrowserCapsSvc>> m_spBrowserCaps;
Note 

In the preceding code, the Browser Capabilities Support pointer is incorrectly identified by the comment as “Data Source cache support” as a result of a minor bug in the ATL Server Project Wizard template.

If the developer decides to utilize the pointers for File Cache, Blob Cache, and Browser Capabilities Support, each respective pointer must be uncommented. The pointers are initialized in the public function named ValidateAndExchange. Each handler class generated by the ATL Server Project Wizard is provided a ValidateAndExchange function unless the Validation Support checkbox under the Application Options tab is not checked (see the next section). The initialization snippets for each respective pointer must also be uncommented if the developer decides to utilize the support.

HTTP_CODE ValidateAndExchange() {    // TODO: Put all initialization and validation code here    // Set the content-type    m_HttpResponse.SetContentType("text/html");    // uncomment the service initialization(s) if you want to use    // a service that was generated with your ISAPI extension    // Get the IFileCache service from the ISAPI extension //   if (FAILED(m_spServiceProvider->>QueryService //         (__uuidof(IFileCache),  //         &m_spFileCache))) //      return HTTP_FAIL;    // Get the IMemoryCache service from the ISAPI extension //   if (FAILED(m_spServiceProvider->>QueryService //         (__uuidof(IMemoryCache),  //         &m_spBlobCache))) //      return HTTP_FAIL;    // Get the IBrowserCapsSvc service from the ISAPI extension //   if (FAILED (m_spServiceProvider->>QueryService //         (__uuidof(IBrowserCapsSvc),  //          &m_spBrowserCaps))) //      return HTTP_FAIL;    return HTTP_SUCCESS; }

The associated ISAPI extension also has code added to it to provide the support for the items selected in the Server Options tab of the wizard. Unlike the code in the handler class, however, the support code in the ISAPI extension is not commented out and is left as part of the solution regardless of whether or not it is used. Support for functionality that is not absolutely required should not be chosen; this minimizes the resources that might be otherwise devoted to unnecessary functionality.

The file cache support provides a class pointer that supports functions for managing file pointers as they relate to reading and writing to files. Actual file content is not stored in the cache class, but rather the information that relates to the files location, name, and size is stored. When items are removed from the cache, they are removed from the hard drive, so the file cache is not meant to manage files other than temporary files.

The blob cache is a memory-caching system designed to deal with memory chunks of varying sizes. The other memory caching classes offered in ATL Server are designed to support memory chunks of a consistent size. The blob cache fills that void by supporting the need to cache memory of variable sizes.

The data source cache provides a similar type of functionality to the other cache classes except for the purpose of storing data source connections.

Choosing the Predefined Performance Counters option places code in the ISAPI extension so that the ISAPI counters for perfmon are updated based on the web application interaction with IIS. This particular feature requires no coding on the part of the developer to make it function. The wizard generates all the code necessary to support the functionality in the ISAPI extension implementation file.

The predefined performance counters are as follows:

  • Active Threads Active threads being used by the web application process

  • Average Response Time Average response time for the web application to return an HTTP response

  • Current Queued Requests HTTP requests awaiting processing

  • Maximum Queued Requests Running maximum of the queued HTTP requests

  • Server Failed Requests Requests that failed including file not found (404) or forbidden (403) error

  • Server Requests Per Second Requests per second made to the IIS web site

  • Server Total Requests Running total number of requests made to the IIS web site

The browser capabilities support provides a class pointer to IbrowserCapsSvc and initialization to set up the pointer to IbrowserCapsSvc. If a pointer to a pointer to IbrowserCaps is passed into the IbrowserCapsSvc GetCaps function along with a pointer to the server context, the instance of IbrowserCaps will allow the developer to query the web user’s browser’s capabilities. Information about the web browser’s capabilities are determined by the class instance of IbrowserCaps by comparing the HTTP User Agent (HTTP_USER_AGENT) value that is sent with the HTTP request to the web server to corresponding capabilities cited in the browsercap.ini file that is usually located at $(windows)\system32\inetsrv\. The browsercap.ini file is formatted such that the HTTP User Agent is cited and the known capabilities are defined. For example, the capabilities cited for Internet Explorer (IE) 5 in browsercap.ini are as follows:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; IE 5.0 [IE 5.0] browser=IE Version=5.0 majorver=5 minorver=0 frames=True tables=True cookies=True backgroundsounds=True vbscript=True javaapplets=True javascript=True ActiveXControls=True Win16=False beta=True AK=False SK=False AOL=False Update=False [Mozilla/4.0 (compatible; MSIE 5.*; Windows 95*)] parent=IE 5.0 platform=Win95 beta=True [Mozilla/4.0 (compatible; MSIE 5.*; Windows 98*)] parent=IE 5.0 platform=Win98 beta=True [Mozilla/4.0 (compatible; MSIE 5.*; Windows NT*)] parent=IE 5.0 platform=WinNT beta=True [Mozilla/4.0 (compatible; MSIE 5.*; Windows 2000*)] parent=IE 5.0 platform=Win2000 beta=True [Mozilla/4.0 (compatible; MSIE 5.*)] parent=IE 5.0

The Resource Language option in the Server Options tab provides support for other languages to be used to generate copy text in the resource files for the project. Visual Studio .NET must be installed with the language support for the respective resource that is desired for the option to make itself available in the drop-down box labeled Resource Language.

Application Options in the ATL Server Project Wizard

The Application Options are mostly based on the differences of the originally chosen project template (see Figure 16-9). If you wanted to build a web service using ATL Server, the Create As Web Service option box would be checked. This option is mutually exclusive to all other options on the Application Options tab, so no other options may be selected if the project is to be a web service. If the project is an ATL Server, all other options are available for selection. If the Stencil Processing Support option is not selected, the two items subordinate to the Options for the initial server response file section are not available for selection.

click to expand
Figure 16-9: Application Options tab in the ATL Server Project Wizard

Validation Support provides a function named ValidateAndExchange in the handler class header file. Other wizards will insert initialization code in the ValidateAndExchange function. ValidateAndExchange is a member function of the base class CRequestHandlerT that’s intended to be overridden with custom initialization and validation code that relates to the given web application DLL. The web application DLL inherits from CRequestHandlerT, which is one of the reasons that the web application DLL is also referred to as the Request Handler DLL (see Figure 16-1). CRequestHandlerT provides many of the basic HTTP interactions between the request handler DLL and ISAPI by providing a layer of abstraction to the ISAPI. Among the other features allotted to the request handler DLL that inherits CRequestHandlerT are the class instances m_HttpResponse and m_HttpRequest. Both classes provide the developer with a mechanism to read and write the HTTP request or response.

Stencil Processing Support places a sample hello world function and a sample tag handler for the hello world function. The Options For The Initial Server Response File become available when Stencil Processing Support option is checked, allowing for the settings to be made on the initial SRF generated by the wizard.

Not checking any options in the Application Options tab will generate a code framework that is similar to a simple ISAPI extension project. For many programmers who have dabbled in ISAPI and have no desire for the SRF functionality, this might be a preferred route. The ATL Server does not require the SRF file in order to function since calls directly to the response handler DLL may be performed at any time. In fact, choosing the Generate Combined DLL option under the Project Settings tab and not selecting any options in the Application Options tab will produce a framework for a solution that is similar to a generic ISAPI extension project that is free of many of the ATL support features.

The class framework code for a request handler DLL without any Application Options selected is as follows:

// singleDLLNoOptions.h :  //Defines the ATL Server request handler class // #pragma once [ request_handler("Default") ] class CsingleDLLNoOptionsHandler { private:    // Put private members here protected:    // Put protected members here public:    // Put public members here public:    HTTP_CODE HandleRequest(AtlServerRequest *pRequest,                 IServiceProvider *pProvider)    {      // Initialize the CHttpResponse      CHttpResponse Response;      BOOL bRet = Response.Initialize(                  pRequest->>pServerContext);      if (!bRet)         return HTTP_FAIL;      // Set the content-type      Response.SetContentType("text/html");      // TODO: Add your handler code here      // Write the response      Response <<<<        "<<html>><<body>><<H1>>Hello World!<</H1>><</body>><</html>>";      return HTTP_SUCCESS;    } }; // class CsingleDLLNoOptionsHandler 

Developer Support Options in the ATL Server Project Wizard

The Developer Support Options tab in the ATL Server Project Wizard provides three checkboxes, as shown in Figure 16-10:

click to expand
Figure 16-10: Developer Support Options tab in the ATL Server Project Wizard

  • Generate TODO Comments Places comments in the code that tell the developer what he or she should do in a given section

    Note 

    TODO comments are hints and phrases that the wizard places in the code to provide the developer with some instruction about the intent of the section of code that is being described.

  • Attributed Code Provides support for using the attribute tags to specify function calls

  • Custom Assert And Trace Handling Support Provides a globally accessible class instance of CDebugReportHook for capturing information from ATL debugging macros

The Attributed Code option causes the familiar tag handlers to be placed in the request handler DLL to map the tags that may be used in the SRFs to the functions in the request handler DLL that are to be called when the tag handler is encountered. For example, the sample hello world method with attributed code is as follows:

[ tag_name("Hello") ] HTTP_CODE OnHello(void) {    m_HttpResponse <<<< "Hello World!";    return HTTP_SUCCESS; }

The nonattributed code still supports tag handler names in the SRFs being mapped to a given function. The code simply uses the REPLACEMENT_METHOD_ENTRY macro to assign the tag name to the function name. Not using attributes may be a preferred means of assigning tag handlers to functions in large code projects. The request handler DLL is spared the cluttering of the bracketed tag handler syntax and the functions that have tags are all identified in the same location. The following listing shows a snippet of code that uses nonattributed tag handlers for the OnHello function:

// TODO: Add additional tags to the replacement method map BEGIN_REPLACEMENT_METHOD_MAP(CNonAttributedCodeHandler)    REPLACEMENT_METHOD_ENTRY("Hello", OnHello) END_REPLACEMENT_METHOD_MAP() HTTP_CODE ValidateAndExchange() {    // TODO: Put all initialization and validation code here    // Set the content-type    m_HttpResponse.SetContentType("text/html");    return HTTP_SUCCESS; } protected: // Here is an example of how to use  //a replacement tag with the stencil processor HTTP_CODE OnHello(void) {    m_HttpResponse <<<< "Hello World!";    return HTTP_SUCCESS; }

The Custom Assert And Trace Handling Support feature declares a globally accessible class instance of CDebugReportHook in the ISAPI extension DLL. Using ATLTRACE and other related macros allows the developer to write code into a request handler DLL that is executed only in the debug build and provides output only to a program designed to read named pipes, such as WebDbg.exe. In the following code listing, the declaration of CDebugReportHook is valid only when the _DEBUG macro is defined:

// For custom assert and trace handling with WebDbg.exe #ifdef _DEBUG CDebugReportHook g_ReportHook; #endif 

ATL Server Project Wizard Completion

When the ATL Server Project Wizard finishes generating the code for the ATL Server project, the code may be run immediately. As long as a function exists in the request handler DLL, the project can be compiled and deployed. Using a project with all of the default settings from the ATL Server Project Wizard, a project would be generated with the following options:

  • Separate DLLs for the ISAPI extension and the request handler DLL

  • Nothing selected from the Server Options tab

  • Validation support

  • Stencil processing support

  • Generate TODO comments

  • Attributed code

  • Custom assert and trace handling support




IIS 6(c) The Complete Reference
IIS 6: The Complete Reference
ISBN: 0072224959
EAN: 2147483647
Year: 2005
Pages: 193

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net