DevGuru Tutorials

Quick References

Features

Partners


			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.