Creating Commercial-Grade ActiveX Controls - Checklist

In spite of the fact that ActiveX technology is about 10 years old, I have not found a book or document that collects and summarizes the basic nuts and bolts of building a commercial-quality ActiveX control i.e. a control that you would be proud to deliver to paying customers, and that fulfills the expectations for such a product. What follows is basically a checklist, summary and bibliography. It's not a tutorial on marketing or programming.

Please send comments, suggestions, useful links, etc. to: Spike

Most similar document to this: Pharoah & Brooke, Creating Commercial Components

Basic bookshelf: Don Box, Essential COM. Rector & Sells, ATL Internals

Basic Online Reading: Deploying ActiveX Controls on the Web with the Internet Component Download

Preliminaries:
Select your target market. What problem will you solve for customers?
How do you plan to distribute your control?
Will your control be used on web pages? If so, on intranets, extranets, or both?
Will your control be used in VB, VFP, or other languages that do not use a linking step? (so-called dynamic languages.)
Will your control be used in compile & link languages, like C/C++ or Delphi?
Might a developer have multiple copies (instances) of your control in existence at the same time?
Might a developer use multiple copies of your control concurrently i.e. in two or more threads running at the same time?

Summary:
You will need to create your control as an ActiveX control.
You will have to decide how to handle licensing - really, license enforcement.
If your control will be used on web pages, think about security. Or, be like Microsoft and don't! Hey, if there's a problem people will tell you.
You will need to define and add one or more interfaces to the control, following good control design practices. If you want the interfaces usable from VB and similar languages, they must be dual interfaces.
When designing your interfaces, there are special considerations for error handling.
You will probably want to provide help to developers, and perhaps to end-users of your control.
You will need to make sure your control registers properly.
For Internet/intranet use, you will probably want to package your control in a .cab file and you should sign it.

The Act of Creation

The following environments have special support for creating ActiveX controls: Visual C/C++, Visual Basic >= 5.0, and Delphi. I'm not familiar with VB or Delphi. For Visual Studio: If your control is large & feature-rich with an extensive UI, you can consider creating it with MFC. Otherwise, MSVC++ programmers will want to use ATL (ActiveX Template Library). The following deals primarily with ATL-based controls.

Licensing

Microsoft has a control licensing scheme based on LPK files: Licensing ActiveX Controls. There are 3rd party licensing systems. Some are based on license servers - this could work for controls used in applications or on intranets, but is not very practical for controls which will be published on the Internet. Our (Dosadi's) ActiveX licensing is based on numeric keys which must match the top-level domain and/or application name. This is possible because a control can get the URL of the hosting page from IE.

Security

In spite of all the ActiveBullshit™ from Microsoft, ActiveX is of course profoundly dangerous and insecure when used on the web. If your control will be used on the web, even on an Intranet, you have security issues. There are design issues, and there are specific interfaces and methods you should implement. Microsoft: Designing Secure ActiveX Controls

If you enjoy acidic commentary, read Brian Hook's forum post on ActiveX and security.

Interfaces: Methods, Properties and Events.

You'll want to create your control with a dual interface otherwise many dynamically-bound languages (VB, many others) will not offer convenient access to your control's interface.

Making your control work correctly at Design-Time

Be aware that in some development environments, your control will be instantiated (be running) when the developer displays a form with your control on it, in the IDE. This state is called Design-Time. In many ActiveX documents, Run-Time is called UserMode. In an MFC-based control, see COleControl::AmbientUserMode. In an ATL-based control, you somehow use get_UserMode of IAxWinAmbientDispatch - but I don't understand exactly how! The mode is a property of the container.

Your control must not cause errors in design mode, or do things that do not make sense. For example, our EZTwainX scanning control cannot assume that TWAIN is installed and available, nor does it try to enumerate available TWAIN devices, when running in the Form Editor. One way to simplify life is to make run-time-only properties non-browsable so that object browsers (like Visual Studio) do not try to enumerate them or display them in the IDE.

Making properties Non-browsable

You may find that some properties of your control only make sense at run time, and should not be visible to the developer in the object browser of their IDE. Adding the attribute nonbrowsable to a property in the IDL file hides a property from object browsers. Example:

[propget, nonbrowsable, id(26), helpstring("how many pages is control holding")] HRESULT PageCount([out, retval] long *pVal);

See Platform SDK: Microsoft Interface Definition Language (MIDL) - nonbrowsable

Describing and implementing properties that return lists

For example, our EZTwainX control has a read-only property that returns a list of all available TWAIN devices. This (as usual with COM and ActiveX) is a whole topic unto itself.

Designing and implementing Error handling

Error handling is a specialized topic for ActiveX (COM) components. Error handling works one way when you call a component from VC++ for example, but in a very different way when the component is called from VB or a scripting language. You will save yourself trouble if you design your methods with error-handling in mind. I recommend the following two articles, especially if you are implementing a control in ATL:

ArcGIS SDK - Extending ArcObjects - Error handling in components

ArcObjects - Getting Started - Active Template Library - Handling Errors in ATL

Registering your control

For a control to be usable, when the control is installed on a client computer it must be registered - literally, recorded in the Registry. Each control is assigned a GUID (Globally Unique IDentifier), and the registry contains a listing of controls, by GUID. When an application (including Internet Explorer) needs to activate a control, it normally starts with the GUID, and uses the registry to find the control and properly load and initialize it.

Making your control transparent

Here's a good article on implementing Transparent ATL Controls.

Caution: This may apply only to older versions of ActiveX, I don't know if the "windowless controls" feature obsoletes this?

Creating CAB files

If your control will be used on web pages, it is very convenient to distribute it as a .cab (cabinet file)This is a compressed archive - the classic use is to put the .cab file on a web server, and refer to it from web pages that host the control. Internet Explorer is smart enough to download and install the control if it is not already installed on the client machine, and to selectively update any files that are newer in the .cab file. Microsoft provides Makecab.exe for creating and editing .cab files.

Digital Signatures / Code Signing

Downloading and running a piece of code from the Internet is a fundamentally dangerous act. Pre-.NET, Microsoft attempted to ameliorate the problem through a standard called authenticode. This is a technology for signing files with a non-forgeable digital signature. Signing a file this way ensures that (1) any alteration to the file is detectable, and (2) the signer of the file can be positively identified. To sign a file you must have a code-signing key. The key (plus password) is a way for you to prove that you are the legitimate owner of the key, and therefore have the right to use a certain signature. Signing keys can be purchased from several vendors, such as Verisign and Comodo. Of course, the security of all this depends on the security of the keys, before and after issuance - see this for example.

If you do not sign and timestamp your executables and .cab files, Internet Explorer may display a warning message (which gets more threatening with each major rev of IE) to let the user know they are taking a risk if they continue with the installation. This is normally suppressed when the source is in the 'Trusted Sites' zone.

The signing and timestamping process is arcane and tedious. Microsoft has thoughtfully changed the names and user interface of the tools multiple times.

Further reading:
Microsoft: File Signing Tool (Signcode.exe)
"Code Signing" using a personal digital signature.

Help

Just adding methods and properties to an interface in Visual Studio will create default help strings for each method and property. These appear in the .IDL file, and can be edited to provide more helpful information.

See: Adding Context-Sensitive Help to an ATL ActiveX Control (MSDN)
Adding Context-Sensitive Help to an MFC ActiveX Control (MSDN)