Choosing a Project Type and Setting Project Properties

See Also

When you open a new project, you have three choices for project type: ActiveX EXE, ActiveX DLL, and ActiveX Control. The type you choose determines what kinds of objects your component can provide.

The following list may assist you in selecting the correct project type for your component.

1. If your component is going to provide ActiveX controls, open a new ActiveX control project. Controls can only be provided by control components (.ocx files), which must be compiled from ActiveX control projects. Control components always run in process.

   Note   Control components are limited in their ability to provide other kinds of objects because class modules in ActiveX control projects can only have two Instancing settings, PublicNotCreatable or Private. Objects in control components are best used to enhance the features of controls; put objects with other uses in a separate ActiveX DLL project.

2. If your component is going to provide ActiveX documents, you can open either an ActiveX EXE project or an ActiveX DLL project. (The New Project dialog box provides templates for new projects that will provide ActiveX documents.)

   See "Building ActiveX Documents" for a discussion of the reasons to choose an in-process or out-of-process component to provide active documents.

3. If you’re creating an out-of-process component, open a new ActiveX EXE project. Reasons to create an out-of-process component include:
   • The component can run as a standalone desktop application, like Microsoft Excel or Microsoft Word, in addition to providing objects.
     
     
   • The component can process requests on an independent thread of execution, notifying the client of task completion using events or asynchronous call-backs. This frees the client to respond to the user.
     
     
   • If you’re using COM or Remote Automation to run components on remote computers (Enterprise Edition only), some components may need to be .exe files.
4. If you’re creating an in-process component, open a new ActiveX DLL project. Reasons to create an in-process component include:
   • An in-process component shares its client’s address space, so property and method calls don’t have to be marshaled. This results in much faster performance.
     
     
   • An in-process component designed for unattended execution (that is, no user interaction) can be marked thread-safe. When used by a multithreaded client, it can provide objects on any of the client’s threads of execution, while retaining the performance benefits of in-process method and property calls.

Once you’ve opened a project for your new component, there are some project properties you should always set.

To set properties for a new component project

1. On the Project menu, click Project1 Properties to open the Project Properties dialog box.
   
   
2. On the General tab, set the Project Name.

   This is the most important property of any new component. It identifies your component in the Windows registry and the Object Browser; its uniqueness is therefore important.

   It’s also the default name of the compiled component, and the name of the type library that contains descriptions of the objects and interfaces provided by your component. See "Polymorphism, Interfaces, Type Libraries, and GUIDs," later in this chapter.

3. On the General tab, set the Project Description.

   Project description is the text string a developer or user will see when setting a reference to your component, or when selecting your control component in the Components dialog box.

4. On the General tab, set the Startup Object.

   Click None if there is no code you need to execute to initialize your component. If your component requires initialization, click Sub Main, add a module to your project, and in that module declare a Public Sub named Main. Place your initialization code in this Sub procedure.

   Important   See "Starting and Ending a Component" later in this chapter for an explanation of the need to keep the processing in Sub Main to a minimum.

   Note   Do not place Sub Main in a class module. Placing Sub Main in a class module turns it into a method named Main, rather than a startup procedure.

Setting Other Properties

Depending on the type of component you’re creating, other project properties may be of interest to you.

Unattended Execution

Located on the General tab, this property can be set for code components that have no user interaction. In an ActiveX DLL project, this makes the DLL thread-safe (via Apartment-model threading).

In an ActiveX EXE project, it allows the component to be multithreaded. The implications and limitations of this property are discussed in "Building Code Components."

Note   Components that contain UserDocuments, UserControls, and forms cannot be marked for Unattended Execution.

Help File Name and Project Help Context ID

Providing a Help file for your component is highly recommended. See "Providing User Assistance for ActiveX Components" in "Debugging, Testing, and Deploying Components" for information on linking help topics to the properties and methods of the classes your component provides.

Start Mode

For out-of-process components that will double as standalone desktop applications, the Start Mode property on the Components tab allows you to debug both startup modes, as discussed in "Debugging Out-of-Process Components" in "Debugging, Testing, and Deploying Components."

Make Tab Properties

Properties on the Make tab allow you to control file version numbers and version information about your component. Use of this tab to provide such information is highly recommended.

Important   Incrementing file version numbers is extremely important for components, as it helps ensure that Setup for your component will never overwrite a newer version with an older one.

Version Compatibility

On the Component tab, you can select a Version Compatibility mode. For new projects, this option is automatically set to Project Compatibility the first time you compile your component, as discussed in "How to Test ActiveX Components" in "Debugging, Testing, and Deploying Components."

For successive versions of your component, you can select Binary Compatibility to ensure that programs compiled with old versions continue to work with the new version. See "Version Compatibility" in "Debugging, Testing, and Deploying Components."

Compile Tab Properties

Properties on the compile tab allow you to select p-code or native code for your compiled component, as discussed in "More About Programming" in the Visual Basic Programmer’s Guide.

Remote Server

In the Enterprise Edition of Visual Basic, setting this Component tab property generates the support files required to run your component on a remote computer.