Creating a COM Server

Creating an ATL Project

The first step in any Visual Studio development endeavor is to build the solution and the initial project. Choosing File, New Project displays the New Project dialog box shown in Figure 1.1, which focuses on Visual C++ projects.

Figure 1.1. Creating a new Visual Studio project

[View full size image]

Selecting the Visual C++ Projects folder displays the various types of C++ project templates available. The name of the project (shown in the figure as PiSvr) is the name of your generated DLL or EXE server.

The job of the ATL Project Template is to build a project for your COM server. A COM server is either a dynamic link library (DLL) or an executable (EXE). Furthermore, the EXE can be a standalone application or an NT service. The ATL Project Template supports all three of these server types. By default, a DLL server is selected as shown in Figure 1.2.

Figure 1.2. Project settings for an ATL project

[View full size image]

ATL Project Wizard Options

The ATL Project Wizard in Figure 1.2 lists several options that merit discussion. The first option sets up the project to use ATL attributes. As described in the Preface, nonattributed projects are preferred in ATL 8, so we concentrate on nonattributed projects in this book. If you decide to use attributes anyway, see Appendix D, "Attributed ATL," for coverage of attributed projects.

In the Additional Options section, the first option enables you to bundle your custom proxy/stub code with your DLL server. By default, this option is not selected. As a result, Visual Studio generates a separate project named <projectname>PS.vcproj for the proxy/stub and adds it to the solution for your server. This project is for building a separate proxy/stub DLL to distribute to all client and server machines that need to marshal and unmarshal your custom interfaces. However, the proxy/stub project is not selected to be built in either of the default build configurations (Debug, Release) for the solution, as you can see from the property pages for the solution in Figure 1.3. Checking the Build check box next to the proxy/stub project causes this project to be built along with the main server whenever the solution is built.

Figure 1.3. Application settings for a new ATL COM server

[View full size image]

If you want to bundle the proxy/stub DLL into the server DLL (requiring the server to be installed on the client machine), you can check the Allow Merging of Proxy/Stub Code option (for nonattributed projects). Doing so results in a solution with only a single project (the one for your main server), with a bunch of conditionally compiled statements inserted into your server code to merge the proxy/stub code. The preprocessor definition _MERGE_PROXYSTUB controls whether the proxy/stub code is compiled into the server; this definition is added to all project configurations by default.

Unless you have a good reason (which is beyond the scope of this book), you'll want to avoid the option to merge the proxy/stub code into your server, instead preferring dual or oleautomation-compatible custom interfaces.

The second ATL Project Wizard option enables you to use the Microsoft Foundation Classes (MFC). Frankly, you should avoid this option. The following are a few common objections developers have to turning off this check box:

"I can't live without CString (or CMap, CList, and so on)." The MFC utility classes were built as a stopgap until the C++ standards committee defined a standard library. They've done it, so we can stop using the MFC versions. The classes string, map, list, and so on provided in the standard library are more flexible and more robust than their MFC equivalents. Moreover, CString is now a shared class between MFC and ATL, and thus is available in ATL projects without having to include the rest of MFC and link to the MFC library. Other MFC utility classes have also been made shared, including CPoint and CRect. And for those who liked the MFC collections classes, ATL now includes MFC style collections (CAtlMap, CAtlList, and so on).
"I can't live without the wizards." This chapter is all about the wizards that Visual Studio provides for ATL programmers. The ATL wizards are arguably as extensive as the ones MFC provides.
"I already know MFC, and I can't learn anything new." Luckily, none of these people are reading this book.

The third ATL COM AppWizard option, Support COM+, causes your project to link to the COM+ component services library comsvcs.dll and includes the appropriate header file comsvcs.h so that your server can access the various interfaces that comprise COM+. With Support COM+ selected, you can also check the option Support Component Registrar, which generates an additional coclass in your project that implements the IComponentRegistrar interface.^[2]

^[2] The IComponentRegistrar interface was thrown in for early implementations of COM+ but isn't actually used, as far as we know.

Results of the ATL Project Wizard

With or without these three options, every COM server that the ATL Project Wizard generates supports the three jobs of every COM server: self-registration, server lifetime control, and class objects exposure. As an additional convenience, the wizard adds a post-build event that registers the COM server upon each successful build. This step runs either regsvr32.exe <project>.dll or <project>.exe /regserver, depending on whether it is a DLL or EXE server.

For more information about ATL's support for the three jobs of every COM server, as well as how you can extend it for more advanced concurrency and lifetime needs, see Chapter 5, "COM Servers."