Developing a COM Server Using Visual Basic and ADSI

Although many administrators will soon feel comfortable performing large-scale administrative tasks interactively using Visual Basic, many situations may require a more formal environment from which to initiate their code. This environment may be a Visual Basic application or even a Web page.

To allow code reuse and increased stability of Web applications, you can compile a COM server to contain your administrative tasks. Once compiled, developers using a variety of languages can utilize the functions within the object.

In Exercise 2.3, you will explore the creation of a simple COM server that generates a new user account in the Windows NT namespace.

Exercise 2.3 Creating an ActiveX DLL for Account Creation

To eliminate multiple compiles during the development effort, begin by pasting the following code into the Click event procedure for the testing application created earlier. If code exists behind the command button, paste over the top of it, creating the following subroutine:

 Private Sub cmdTest_Click()      Dim Container As IADsContainer      Dim ContainerName As String      Dim User As IADsUser      Dim NewUser As String      ContainerName = "Computer_Name"      Set Container = GetObject("WinNT://" & ContainerName)      NewUser = "ADSI_Test_01"      Set User = Container.Create("User", NewUser)      User.SetInfo End Sub

After replacing the ContainerName variable assignment with the name of the target computer name , run the code segment using the F5 key. Click the proper command button once to test the code. Close the form.
Launch User Manager and select the target computer to examine the machine's local SAM. Alternatively, you can launch User Manager from a command line as follows :
```
 usrmgr \Computer_Name 
```
You should see a new user account named ADSI_Test_01 . Delete this account and return to Visual Basic.

You have now proven that the Visual Basic code creates a new user account in your environment. Next you will create a procedure from this code, so that it can be used more effectively.

If the code did not execute successfully, make sure your user account has administrative rights on the workstation or server you are targeting.
In the General Declarations section, (the top of the code window), add the following:
```
 Private Sub CreateUser(ContainerName As String, NewUser As String)      Dim Container As IADsContainer      Dim User As IADsUser      Set Container = GetObject("WinNT://" & ContainerName)      Set User = Container.Create("User", NewUser)      User.SetInfo End Sub 
```
Notice that the ContainerName and NewUser variable declarations and assignments have been removed. The subroutine is now responsible for declaring the variables. The calling statement is responsible for assigning values to the variables .

Next, modify the Click event code for cmdTest to call the new subroutine:

 Private Sub cmdTest_Click()      Call CreateUser("Computer_Name", "New_User_To_Create") End Sub

Replace the Computer_Name and New_User_To_Create placeholders with the appropriate values and run the code. Click the command button once to test the code and verify that the account was created properly.

With this procedure in place, you can now reuse the code anywhere you want in the form ”as many times as you need, simply by assuring that unique values are passed in for the new user account name.

Note

Notice that you are not using the form and command button for anything other than calling the procedure. This is a vital concept, as COM servers cannot have any form of graphical user interface. In this example, the form represents the client, and the procedure is on its way to becoming a method defined in a COM server.

Next, you can modify the procedure code to complete its metamorphosis into a COM server.
To begin this procedure, you must first change the declaration of the Sub to be Public :
```
 Public Sub CreateUser(ContainerName As String, NewUser As String) 
```
Next, you must ensure that data passed in using arguments is passed by value and not by reference (as is the default for Visual Basic):
```
 Public Sub CreateUser(ByVal ContainerName As String, ByVal NewUser As String) 
```
Copy the entire CreateUser procedure onto the clipboard so that you can insert it into a new class module, which will become your first COM server.
Close the current Visual Basic project without saving.
Open a New Project, but this time select the ActiveX DLL Project Template.
Paste the code into the class module's code window. Rename the project ADSI_COM and the class module UserMgmt . Meaningful names for projects and class modules is essential in COM development, because these become part of the name required to instantiate the object.

Note

You can put additional class modules into a single ActiveX DLL to allow logical grouping of administrative functions. For example, you could easily create an additional class module for group management, and another for managing services. This is the strategy that will be employed for the COM server creation exercises throughout this text.

Because you are in a new project, you must set a reference to the Active DS Type Library, as performed previously for the Standard EXE project.
Click the File menu, then select Make ADSI_COM.DLL Specify the location for the finished DLL. Visual Basic compiles a new DLL containing the CreateUser function. Close the ADSI_COM project.

Note

Notice that only the procedure's first line changed between the code segments used in the Standard EXE project and the ActiveX DLL.

If the code compiles without error, you have compiled your first COM Server using Visual Basic.

Testing the COM Server Using Visual Basic

With your first COM server developed (or using the precompiled COM server from the Web site), you can now look at how the COM server affects development of Visual Basic client applications.

Exercise 2.4 Using a Custom COM Server in a Visual Basic Project

To test your first ADSI COM server, create a new project based on the Standard EXE template project. Click Project, References. Notice that ADSI_COM appears in the list. Set a reference to this object.
Add a command button to the form. Double-click the button, and type the following code into the click event for Command1:
```
 Private Sub Command1_Click()      Dim FirstCOM As ADSI_COM.UserMgmt      Set FirstCOM = New ADSI_COM.UserMgmt      Call FirstCOM.CreateUser("ComputerName", "ADSI_COM_Test1") End Sub 
```
If you have Auto List Members enabled, a dialog box appears when you type Call_FirstCOM. The dialog box shows you that a method named CreateUser is available. In addition, when you open the left parenthesis, the proper syntax displays to enable proper use of the CreateUser method.

Tip

If you have not already done so, replace the ComputerName variable declaration with the name of the target machine.
Run the project and click the Command1 command button to test the COM server. Verify that the user account was created using User Manager.
If the account named ADSI_COM_Test1 appears in the list of accounts, you have successfully created an account using your first COM object developed with Visual Basic and ADSI.

Instantiating the COM Object from a VBScript Active Server Page

As businesses evolve into multi-national entities, the development model of these organizations must also evolve to adapt to the bandwidth limitations of WAN communications.

HTML development allows organizations to share rich multimedia applications with remote sites across even the slowest network connection. Content arrives at the client as text and graphic images to be rendered using client resources. This thin-client model is what most organizations are focusing on for new applications as the model scales well and is relatively simple to implement despite the constant evolution of the business.

As such, this text would be far from complete to ignore the desire for readers to implement ADSI functions in a Web environment. While we have been focusing on Visual Basic as the development environment for all code utilizing ADSI, you can easily instantiate a COM object from an ASP, taking full advantage of the power of ADSI from an ASP.

Exercise 2.5 Instantiating the ADSI_COM.DLL Object from an Active Server Page Script

If you want to use this COM object from IIS, copy the ADSI_COM.DLL to the IIS server. Then, from the server console, open a command window and navigate to the DLL's location. Type the following command to register the DLL:
```
 REGSVR32 ADSI_COM.DLL 
```
If the registration is successful, a dialog box appears, stating :
```
 DllRegisterServer in ADSI_COM.DLL succeeded. 
```

With the proper registry entries now made, you can instantiate the object from an ASP, as follows:

 <%@ Language=VBScript %> <%Dim FirstCOM Set FirstCOM = Server.CreateObject("ADSI_COM.UserMgmt") Call FirstCOM.CreateUser("Computer_Name","ADSI_COM_ASP1") Response.Write Err.Number %>

Save the ASP file and set the NTFS permissions so that only Administrators and System can read the file.
Verify that either Basic or NTLM authentication is enabled using Internet Service Manager.
Test the page using any HTML browser. If a 0 is returned, you successfully created a new user named ADSI_COM_ASP1 .

Although this is a simple example, you should begin to see the power and ease of COM development when combined with an ASP. With a bit of imagination , you can easily add a form to collect the name of the server on which to create the user account and verify that the user account name follows the naming standard for the enterprise. After instantiating the COM server, only a single line of code is needed to actually create a user account.

Tip

Be sure to set the NTFS permissions on the file so that only Administrators and System have access to the file. If the anonymous account has access to the ASP, the anonymous user account credentials are used. A General Access Denied error message displays, and the operation fails (unless the anonymous account is in the Administrators group).

If you receive a General Access Denied message, the problem is usually in NTFS permissions and/or the IIS authentication mode used for the ASP.

Creating a Delegation Model Using DCOM

If you want non-administrative users to perform administrative tasks in a namespace, you must give users the ability to impersonate another identity when accessing resources.

If you do not care about the security of your enterprise, you could add the anonymous user account to the administrators group, which establishes this impersonation. While functional, taking such an approach allows crafty users to query the IIS Metabase and find the value of the password assigned to this account, thus obtaining the use of a privileged account in the enterprise. Additionally, this opens a floodgate of potential hacking against your enterprise from a Web client.

For those who value the security of their enterprise, more secure methods for impersonating an account identity must be sought. By adding Microsoft Transaction Server (MTS) and the Distributed Component Object Model (DCOM) into the picture, you can run your ADSI-based functions under a different user account ”allowing the basis for a delegated administration model.

Note

MTS is a free component (included in the Windows NT Option Pack) and is installed as an integral component of IIS. Although most people think of MTS as simply providing database transaction support, it is also the best method to allow IIS in-process components to participate in DCOM.

Advanced usage of MTS and DCOM is well outside the scope of this text, much less a chapter on COM development. If you want to find more information about these innovation-enabling technologies, check out Appendix C "Further Reading".

Imagine being able to allow your help desk users to reset passwords, disable accounts, or clear an account lockout condition without granting them membership in the "Account Operators," "Domain Admins," or equivilent security group for the user domain. If you have too many administrators in your organization, you can use ADSI, COM, and MTS to create a delegation model that alleviates this risk-laden condition.

Running COM Components in MTS

To avoid running ADSI functions using a privileged account, you can create a delegation model. This model lets users perform administrative tasks without actually being an administrator. For Windows 2000 enterprises , this is usually accomplished using the Active Directory; however, many Windows NT users may want to allow greater levels of granularity to their enterprise administration model.

To further prove the power of COM, Exercise 2.6 will allow you to run the ADSI_COM.DLL COM server you created earlier under an administrative account identity.

Exercise 2.6 Establishing a Delegation Model Using Microsoft Transaction Server and the Distributed Component Object Model

To begin using MTS, you must first create a new package to run the COM server in (see Figure 2.4).

Figure 2.4. Create a new MTS package.
Open Internet Service Manager, and locate the Microsoft Transaction Server snap-in folder. Expand the folders until you get to the Packages Installed folder. Right-click the folder, select New, Package.

Tip

If you need to install a package on multiple servers, you can export existing packages. Then use the Install pre-built package feature in the Package Wizard (see Figure 2.5) to perform the import.

Figure 2.5. Creating an MTS Package Using the Package Wizard.

For purposes of this example, you should create an empty package (see Figure 2.6).

Figure 2.6. Creating an empty package.
Select a descriptive name for the MTS package. This name has no programmatic meaning. It is there strictly as a container for COM components and bears no meaning when components are instantiated from the client application.

Figure 2.7. Setting the Package Identity.
If you want to run the components contained within this package under an alternate identity (thus establishing a delegation model), you can do so by specifying the account to use in the Package Identity dialog box. In most cases, you should always use a privileged account for the package identity.

Warning

If you assign a privileged account to this identity, non-administrative users can use the functions in the COM server. Although this may be desirable in many cases, you should consider all ramifications before taking such an action.
Click Finish to complete the package creation.

With the package created, you must now populate the package with COM components.
Open the new package, and navigate to the Components folder. Right-click the folder, select New, Component.

If you have already registered the component, you can import it into the package by selecting the Import components that are already registered command button.

For most cases, however, the path of the .DLL is known and can be easily located in the file system. After clicking the Install New Components command button, click the Add Files command button to browse the file structure for the COM server.
After you locate the server, click Finish to finalize the installation of the COM server.

To prevent unauthorized use of the COM server, you may want to assign MTS roles to the individual class modules within the COM server. MTS allows you to assign Windows NT security groups to the roles, which are then assigned to each class in the component.

In addition, you might want to use some form of group verification in the COM server to prevent unauthorized use of the procedures contained in the object. This ultimately creates the most granular administrative model available, as each function can then require specific group membership before executing.

Note

A delegated COM server example is included on this book's Web site: http://www.newriders.com/adsi..

Using the technique presented in Exercise 2.6, you have allowed the functions of the COM server to run under a different identity without changing a single line of client code, thus allowing non-administrative users to create a new user account.

When instantiating the object from an ASP, the referenced class module will run under MTS context ”improving the stability and increasing the variety of options available to the systems developer.

Top

Developing a COM Server Using Visual Basic and ADSI

Exercise 2.3 Creating an ActiveX DLL for Account Creation

Testing the COM Server Using Visual Basic

Exercise 2.4 Using a Custom COM Server in a Visual Basic Project

Instantiating the COM Object from a VBScript Active Server Page

Exercise 2.5 Instantiating the ADSI_COM.DLL Object from an Active Server Page Script

Creating a Delegation Model Using DCOM

Running COM Components in MTS

Exercise 2.6 Establishing a Delegation Model Using Microsoft Transaction Server and the Distributed Component Object Model

Figure 2.4. Create a new MTS package.

Figure 2.5. Creating an MTS Package Using the Package Wizard.

Figure 2.6. Creating an empty package.

Figure 2.7. Setting the Package Identity.