Tutorials » Creating ActiveX Server Components in Visual Basic
The purpose of this tutorial is to explain how one can use Microsoft Visual Basic 6.0 to create, compile and update an ActiveX Server Component. For the purposes of this tutorial, we define an ActiveX Server Component as a component that is designed to be used from inside an Active Server Page.It is assumed that the reader is already familiar with the process of creating and viewing ASP pages, and has some knowledge of the Microsoft Internet Information Server and its configuration utility, the Internet Service Manager.
Finally, please note that this tutorial applies only to Windows NT 4.0 or Windows 2000 and IIS 4.0.
For a walk-through of the overall process, we’ll create the obligatory Hello World example.
Step 1: Like all things Visual Basic, creating an ActiveX server component is not an overly complex task. If, when you open Visual Basic, a New Project window appears, skip this first subtask and proceed directly to the second subtask – selecting the ActiveX DLL project type. Alternatively, if upon opening Visual Basic you are prompted with an empty work environment proceed as follows: Under the File menu, select New Project
In the New Project dialogue box that appears, select ActiveX DLL and click OK.
Visual Basic will now work some magic and you will shortly have in your possession the skeleton of an ActiveX server component. This essentially consists of a project named, by default, Project 1, and a class (by default named Class 1.) The project should be displayed with a worksheet opened for the first class.
Step 2: To display our pithy little greeting, we’ll make use of one of the intrinsic ASP objects, Response, which we’ll gain access to through the auspices of the Microsoft Transaction Server. In order to utilize external libraries of objects such as those found in MTS or ASP, we must tell the Visual Basic compiler where these libraries are located. This is achieved in Visual Basic by including references to the appropriate DLLs. To do this, you first need to select the References option on the Project menu. In the list of the libraries that appear, find the listing for "Microsoft Active Server Pages Object Library." In addition, if you are using Windows NT 4.0, find "Microsoft Transaction Server Type Library," or if you are using Windows 2000, find "Com+ Services type library." Mark the appropriate check-box to the left of your selection(s), and click OK.
To actually make use of any of the Active Server Page intrinsic objects such as Response, Session, Application, or Request, you’ll need to create and initialize instances of these objects. Fortunately, thanks to the Microsoft Transaction Server, this is a relatively painless task.
Whenever the Transaction Server instantiates a new MTS component, it checks to see whether or not that component implements a set of functions and subroutines collectively known as the ObjectControl interface. If, in fact, the component being created does implement this interface, then MTS will call this component’s implementation of the ObjectControl_Activate subroutine at some point during the creation process. Similarly, when the MTS object is being destroyed, MTS will automatically call the object’s implementation of the ObjectControl_Deactivate subroutine, if it exists.
Now the nice thing about this whole chain of events, is that inside the ObjectControl_Activate subroutine we can determine the context in which our component is currently being created. We may then get references to any context-specific objects, such as the ASP intrinsic Response object. Add the following lines of code to Class1 now to accomplish just such a trick:
Private oContext As ObjectContext
Private oResponse As Response
Implements ObjectControl
Private Sub ObjectControl_Activate()
Set oContext = GetObjectContext()
Set oResponse = oContext("Response")
End Sub
Private Sub ObjectControl_Deactivate()
Set oContext = Nothing
Set oResponse = Nothing
End Sub
Private Function ObjectControl_CanBePooled() As Boolean
ObjectControl_CanBePooled = False
End Function
Providing an implementation of the ObjectControl_CanBePooled function as in the above code, is a requirement of implementing the MTS ObjectControl interface. The purpose of the function is to tell MTS whether or not you want it to cache (pool) instances of your object that are no longer being used. If MTS does pool your component, then when another instance is required it can simply be returned from the pool, rather than being recreated from scratch. In our component we wish to disable pooling, since the reference to the Response object that we are obtaining will be specific to each instance of the component.
Step 3: Phew!
Next we’ll need to write the method that will perform our humble task. To do this, add the following lines of code to Class1 now:
Public Sub DisplayGreeting()
oResponse.Write "Hello, out there!<BR>" & VBCrLf
End Sub
The VBCrLf constant simply adds the carriage-return and line-feed characters
to the end of the line, and is purely an aesthetic addition to the code.
Step 4: That should comprise the whole of the code for
the component. For the next step, we’ll compile it into a DLL that can
subsequently be called from a server-side script. Before doing this,
though, you’ll probably want to give some meaningful names to your project
and its sole class. To alter the default name for the project from "Project1"
to something more agreeable, click on the project name in the Project
Explorer window, which lies to the right of the workspace. In the
Properties window below it, there should be only one property
listed, which is (Name). Alter this to suit your tastes, and
then click on the listing for Class, again in the Project Explorer
window. The (Name) property for the class will be the first of
several properties listed in the Properties window. For our example,
we’ve chosen the rather predictable names of "Example" and
"Greeting" for our project and class.
After entering the code as directed, and renaming everything, your Visual
Basic editor window should look something like the following (but note
that we have removed the toolbox from the left of the window so that
more of the code is visible.)
Now save your project and then, on the File menu, select
Make Example.dll, where "Example" is the name
that you’ve given to the project. The default location for the DLL is
the folder in which you saved your project, and this will do as well
as any. Once you’ve chosen a location for the DLL, your code will be
compiled and a listing for the resulting DLL will be added to the system
registry.
Step 5: Having created the DLL we must now register it
with the Microsoft Transaction Server. Components that are registered
with MTS are organized into packages which typically contain
all the components for a particular application. If you are using Windows
NT 4.0, to register the DLL with MTS, we must first create a new package.
To do this, open the Transaction Server Explorer by clicking the Windows
NT Start button, selecting Programs, then Windows NT
4.0 Option Pack, followed by Microsoft Transaction Server
and finally Transaction Server Explorer. When the MTS explorer
window appears, expand the Microsoft Transaction Server folder in the
left pane, then expand Computers, followed by My Computer.
Now select (by left-clicking on) the Packages Installed folder.
Next, right-click on Packages Installed and select New followed
by Package. If you are using Windows 2000, to register the DLL
with MTS, you must click the Start button, when the window pops
up select Settings, followed by Control Panel, then Administrative
Tools, and finally Component Services. Expand the My Computer
directory in the left pane and select Com+ Applications then
right click and select New followed by Application.
Click the Create an Empty Package button from the pop-up window
that appears, enter the name of your package (we’ve called the package
Example), click Next, if you are Using Windows 2000 click
Next once more, and then Finish. A new icon representing
your example package will then appear in the right pane of the explorer.
Having created the requisite MTS package, we must now add our newly
created DLL to this package. To achieve this, expand your package in
the MTS explorer, and then select (by left-clicking) the Components
folder. Next, right-click on Components, select New, and
then Component.
Click the Import component(s) that are already registered button.
After a short while a pop-up window will appear containing a list of
all the components registered on your computer. Select Example.Greeting
(or whatever you chose to call your component) and click the Finish
button.
An icon representing your component will appear in the previously blank
right pane of the MTS explorer. This completes the registration of your
component, and you can now begin testing.
Step 6: Having built and registered our new component,
we can now begin testing. To test your new ActiveX Server Component,
create an ASP page now (using Visual Interdev or the editor of your
choice) and paste in the following code:
Set oExample = Server.CreateObject("Example.Greeting")
oExample.DisplayGreeting
%>
The CreateObject method of the Server object creates an instance of
the component specified by its single String argument. In the above
example, we create an instance of our Example.Greeting component.
Now save your ASP page in a folder that is, or can be made, accessible
to IIS. If you are not sure where to save your ASP page, we suggest
making a folder C:\inetpub\wwwroot\test and storing it there.
Before viewing your test ASP page in a browser, it is important that
you configure the page to run in a separate process from the main Internet
Information Server (IIS) service. If you do not do this, you may have
to shut down the Web server each time you wish to rebuild your DLL.
This is because the web server process will attach itself to your DLL
and prevent the file from being overwritten when you attempt to recompile
your Visual Basic project. By configuring IIS to run your page in a
separate process however, we will only have to shut down that one process
in order to free up the DLL and enable the project to be rebuilt.
To make sure that your page is set to run out-of-process, start up the
Microsoft Management Console (MMC) for IIS. This should be accessible,
if you are using Window NT 4.0, by clicking the Start button,
selecting Programs, then Windows NT 4.0 Option Pack, followed
by Microsoft Personal Web Server (for NT workstation) or Microsoft
Internet Information Server (for NT Server) and finally selecting
Internet Service Manager. If you are Using Windows 2000, this
is accessible by clicking the Start button, selecting Settings,
followed by Control Panel, then Administrative Tools and
finally Internet Service Manager. You will notice that you can
configure both the Internet Information Server and the Transaction Server
from this interface.
Having opened MMC, locate your ASP page’s directory in the Internet
Information Server tree view in the left pane, and then right-click
on the directory name. On the menu that appears, select Properties.
In order for your test ASP page to run out-of-process from IIS, the
directory in which it’s located must be an application starting point.
To determine whether or not this is the case, look at the tree view
in MMC. Icons for the directories which are application starting points
are depicted as open boxes, whereas those directories which are not
application starting points are represented by the standard folder icon.
If the page’s directory is not an application starting point, click
the Create button on the property page. You can give the
new application a name after creating it, although this is not actually
necessary.
Once you’ve ensured that the directory is capable of running the page
out-of-process, make sure that the check-box to the left side of Run
in separate memory space is checked (in the above screenshot
this checkbox is disabled as we have not yet created the Application
starting point.) Finally, click Apply, followed by OK,
to close the property page.
Now, you may finally view your test ASP page containing the script to
call your object’s DisplayGreeting subroutine. When you do this,
you should see the string "Hello, out there!" displayed in
the browser.
Step 7: Having our simple "Hello World!" example
working, you can now modify it and extend it to perform the particular
tasks that you are interested in. Although our example component contains
only a single subroutine, you can extend it to implement as many functions
and subroutines as you desire. Each function or subroutine that is added
to your Visual Basic project and declared as Public will be accessible
from an ASP page, just as the DisplayGreeting subroutine was. And of
course, the procedures that you add can do far more than simply send
a string to the browser.
Having made changes to the code in your Visual Basic project, you must
detach the existing DLL from any active processes before you attempt
to rebuild it. If you do not do this, you will receive a "Permission
Denied" error when attempting to remake the DLL.
To detach your DLL from IIS, open the Internet Service Manager and view
the Properties of the directory containing the ASP page that uses your
component. Click the Unload button to detach your DLL from the
IIS process. Then click Apply followed by OK to close
the properties window.
You will also need to detach your DLL from MTS. To do this, right-click
on your package in the Transaction Server Explorer, and select Shut
Down.
If you have your ASP page open in an editor such as Microsoft Visual
Interdev, this application may also be attached to your DLL. To detach
the DLL, exit the application.
Having released all active references to your DLL you may now rebuild
your component by selecting Make Example.dll (or whatever you
DLL may be called) from the File menu in the Visual Basic editor.
If, after recompiling your DLL, your test page fails to load correctly,
you may also need to refresh MTS so that it knows that the component
has been updated. This can be achieved from the MTS explorer by right-clicking
on My Computer and selecting the Refresh All Components
option. Alternatively, you can run mtxrereg from any command prompt,
or by selecting Run from the Windows NT Start menu, entering
mtxrereg and then clicking the OK button.
With this in mind, you should now have all the tools necessary to begin
building your very own ASP/MTS Server components.
Step 8: Have fun. Go play!
For help with debugging your ActiveX component,
read our companion tutorial, Debugging
ActiveX Components in Visual Basic.
