Visual Basic Concepts

ActiveX Component Shutdown

See Also

To create a well-behaved component, you have to give up control over your component’s lifetime. Your component is started automatically when a client requests an object. It should shut down when all clients have released the objects they were using — and not a moment sooner.

The reason for this is that the objects your component provides become integral parts of the client applications that use them. A client that uses one of your objects must be able to count on the object existing until the client is done with it.

By the same token, if clients have released all references to the objects your component provides, your component should shut down and release the memory and resources it was using.

Therefore, in designing a well-behaved component the two most important guidelines are:

• Don’t force your component to shut down while client applications have references to your objects.
  
  
• Don’t force your component to remain in memory when all object references have been released.

Visual Basic provides a great deal of assistance in following these basic guidelines. This topic explains how you can do your part.

Don’t Force Your Component to Shut Down

This means that you should never use the End statement to shut down your component, as long as client applications are holding references to your objects.

This guideline is easy to follow for in-process components, because Visual Basic prevents the use of the End statement in ActiveX DLL and ActiveX control projects. If you include the End statement in your code, an error will occur when you make the compiled component.

Note   Visual Basic doesn’t allow the End statement in an in-process component because executing it would also terminate the client.

Out-of-Process Components

If you shut down an out-of-process component with the End statement, client applications are left holding references to objects that no longer exist. When they attempt to invoke the properties and methods of those objects, they will receive errors.

In addition, your component may not shut down correctly, because your objects never receive their Terminate events. This is because the End statement halts execution of your component abruptly, releasing objects and freeing memory. No further Visual Basic code is executed, including code you have placed in the QueryUnload and Unload events of forms, and in the Terminate events of forms and classes.

If you observe the four rules Visual Basic uses to determine when to shut your component down, as described in "Visual Basic Component Shutdown Rules," you should never need to force your component to shut down.

Don’t Force Your Component to Remain Loaded

Visual Basic will automatically unload your component according to the shutdown rules enumerated In "Visual Basic Component Shutdown Rules." As you’ll see from the discussion of those rules, it’s possible to keep your component loaded after clients have released their references to its objects.

Generally speaking, this is a bad idea. Your component goes on taking up memory, even when it’s not supplying objects. In fact, an out-of-process component that refuses to shut down may go on taking up memory long after all clients have terminated.

Note   You can’t force an in-process component to remain loaded beyond the termination of its client. When the client closes, the component is unloaded regardless of any outstanding object references, open forms, and so on. This includes references the client may have obtained, and then passed to other client processes.

Reasons to Keep a Component Loaded

What rule is without exceptions? There are two important circumstances in which you may want to keep your component in memory deliberately:

• If your component is a standalone desktop application that also provides objects, the way Microsoft Excel does, and it’s been started by the end user, then it’s inappropriate for it to close when the last client releases its last reference.

  Note   Visual Basic helps you with this, by not shutting down an out-of-process component that has a loaded form, as described in "Visual Basic Component Shutdown Rules" under Rule 2: Forms.

• If you’re designing a component to work with a particular client — for example, if client and component are parts of a larger system — and the client frequently releases all of its references to objects the component provides, you may want to keep the component running to avoid the delay caused by reloading it into memory.

  Note   You can keep your component loaded in this situation using the information in "Visual Basic Component Shutdown Rules," under Rule 1: References and Rule 2: Forms.

In either of these special cases, forcing your component to remain loaded means that you must find some other way to determine when it should unload. For more information, see "Visual Basic Component Shutdown Rules."