Create a Simple ATL Server Project

Let's create an ATL Server project.

1. Open Visual Studio .NET.

2. Choose File | New | Project to open the New Project dialog box, shown in Figure 16-3.

   
   Figure 16-3: New Project dialog box with ATL Server project template

3. Visual Studio .NET offers many ATL templates for web solutions or ATL solutions, but for this exercise, select the ATL Server Project template. Be careful not to choose the ATL Project template since it does not offer a web component. As it always has, however, the ATL Project template will provide the framework for producing a classic ATL DLL or executable that utilizes ATL Libraries.

   The ATL Server Web Service template will produce a Web Service project that is similar to web service project templates produced in Visual Basic and C#, except, of course, the project is coded in C++. An associated ISAPI extension is produced for the web service that may be deployed and managed separately from the Web Service DLL. Just as the web services in C# had the .asmx file that acted as a dispatching mechanism to the web service DLL, the ATL Server Web Service uses HTML files for this purpose.

4. Enter the name of the project, and then click the Next button to start the ATL Server Project Wizard, which opens with an overview of the project that will be produced.

5. The ATL Server Project Wizard is a one-step wizard with four separate screens that may be used to change project settings of the ATL Server prior to the point at which the files are actually generated. The settings are summarized as part of the wizard's Overview (Figure 16-4) screen for the project. If the default settings are known and desired, you can click the Finish button, and the project files will be created.

   
   Figure 16-4: Overview screen for ATL Server Project Wizard

After you click the Finish button of the ATL Server Project Wizard, Visual Studio .NET will begin to generate the files according to the default settings of the ATL Server Project Wizard. Either of the ATL Server project templates mentioned in step 3 (ATL Server Web Service or ATL Server Project) will generate two projects in Visual Studio .NET. The start-up project is the main project whose name you provided in the New Project dialog box. The second project that is generated uses the same name as the start-up project, but ISAPI is concatenated to the end of the filename. For example, in Figure 16-3, the name NewSimpleATLServer was given to the ATL Server project being created. Visual Studio .NET provides a window, called the Solution Explorer, for examining projects and the associated files. The Solution Explorer window displays the projects and files in a hierarchical tree format that are associated with the currently opened solution. The Solution Explorer may be opened from the Visual Studio .NET menu View | Solution Explorer. In the Solution Explorer, the project NewSimpleATLServer will exist and a second project named NewSimpleATLServerISAPI will also exist. The NewSimpleATLServer project contains the application-specific code. The product of the NewSimpleATLServer project is a Web Application DLL and Server Response File (SRF). The product of the NewSimpleATLServerISAPI project is a single ISAPI DLL.

Unlike the web service templates for C# and Visual Basic, a virtual directory is not automatically added to the local instance of IIS. Visual Studio .NET can be set up to deploy the files that make up your ATL Server solution to IIS. The first IIS web instance loaded in IIS, however, is the only instance that Visual Studio .NET will deploy to. If you need to deploy to another web instance other than the first one, which usually is the default web site, you will have to perform this operation manually. To configure Visual Studio to deploy the ATL Server solution to IIS automatically, follow these steps:

1. Select Project | Properties from the Visual Studio .NET menu and the property pages window will open, as shown in Figure 16-5. An ATL server project actually consists of two projects (unless the project was configured to use a single DLL). The property pages window will display the properties for the currently selected Visual Studio project. The currently selected project may be changed by selecting the project in the Solution Explorer window.

   
   Figure 16-5: Project property pages window and solution explorer

2. After the property pages window opens, select the Web Deployment node in the left panel of the window at the bottom. Each of the nodes in the left panel of the window is identified with a folder icon. Selecting any node in the left panel of the property pages window will cause the window to refresh the contents of the right panel so that the controls that are used to edit configurations related to the selected node in the left panel are displayed.

3. Select the ISAPI extension DLL project from the Solution Explorer. Unless the project name was changed from the project template default, this project usually has the phrase ISAPI appended to the name given the ATL Server project.

4. For the Relative Path property displayed in the right panel, type the value bin. This will cause the ISAPI extension DLL to be placed in a subdirectory named bin subordinate to the directory that the IIS virtual directory points to. If you want a different name than bin, any name you would like the files to be deployed to will do.

5. Set the Virtual Directory Name property to the name of a virtual directory you would like the ATL server project files to be deployed to in IIS. If the virtual directory does not exist, it will be created. The drop-down list box provides an option to simply choose the name of the project for the setting.

6. The Application Mappings should be set to .srf;.dll. The virtual directory created will have these mappings set.

7. Now, select the project for the web application dll in the Solution Explorer so that the property pages window will refresh with the settings for the web application dll project.

8. Just as was done for the ISAPI project, select the Web Deployment node in the left panel of the window at the bottom if it is not already selected.

9. Make the same settings as described in steps 4 and 5. The virtual directory name must be the same name used for the ISAPI project. The relative path property can be set to a different path than the ISAPI project's relative path. The application mappings should not be set to any value for the web application dll project.

10. Click the OK button to keep the configuration changes and dismiss the window.

After the relative path, virtual directory name, and application mappings are set for the projects in an ATL server solution, the files will be deployed after the first build is performed.

Pressing the F5 key, regardless of what window in Visual Studio .NET is selected, will cause Visual Studio .NET to begin to build, deploy, and run NewSimpleATLServer. A prompt will appear, informing you that the files are out of date and requesting permission to recompile. After the binaries for the request handler DLL and the ISAPI extension are compiled successfully, they will be moved along with the sample SRF to a location within the web root of the default web server instance in IIS. Visual Studio .NET will attempt to attach itself to IIS and provide step-through code debugging, and the likely result will be that you will be presented with the following error message:

Remember 

The name of the StartUp project in any given Visual Studio .NET solution is identified in boldface font in the Solution Explorer. For a solution that contains multiple projects, the project template will likely automatically set the proper project as the StartUp project. If multiple projects are being added to a given solution, however, the developer will need to ensure that the desired project is set as the StartUp because Visual Studio .NET will establish a StartUp project arbitrarily. To set a project as the StartUp, right-click the project in the Solution Explorer and choose Set As StartUp Project from the context- sensitive menu.

By default, Visual Studio .NET does not install with support for ATL Server debugging in place. Full Remote Debugging is installed by default, and it will support the debugging requirements of managed code solutions such as Visual Basic and C# web forms and web services. C++ solutions require the use of Native Remote Debugging. The Visual Studio .NET installation program may be used to add the support, as shown in Figure 16-6. Simply access the install program that was used to install Visual Studio .NET on your workstation and start the installation process. When the window shown in Figure 16-6 is displayed, choose Native Remote Debugging.

Figure 16-6: Installing native remote debugging

If native remote debugging is in place and everything is set up properly, a browser instance should have been opened showing the phrase, This is a test: Hello World! The only other likely failure that might occur at this point is if the file extensions .dll and .srf are not mapped to the associated ISAPI extension DLL for the project in a given IIS instance or virtual directory. If you believe this might be the case, open the application mappings for the IIS instance or virtual directory as shown in Figure 16-2 and inspect the mappings to see if the .srf and .dll files are mapped to the proper ISAPI extension DLL.

Because of the complicated ATL Server configuration required to get a Hello World program to run, the developer must have an intricate knowledge of the workings of IIS and the .NET Framework. Harnessing the power of the ATL Server can benefit the development shop a great deal, but the learning curve is a formidable consideration.

Tip 

Whenever something does not function properly when you're working with IIS and ATL Server, and you can find no apparent reason for it not to work, you might try restarting the web services. This is especially true when a developer or system engineer has to map an ISAPI extension manually or after configuration changes for the IIS instance or the virtual directory are made.