Creating Automation Servers

Article
11/14/2006

An Automation server is a COM component application that exposes functionality that can be used and reused by other applications through Automation. For example, using Visual FoxPro you can create an Automation server that displays reusable forms (in an out-of-process .exe file), or packages a complex routine into a simple component that other programmers can use. In addition, you can create one or more classes to handle enterprise-wide business rules. A client application that uses the business rule object would pass input parameters in a method call, and the Automation server might then do a great deal of work, retrieving or storing data from various sources and performing complex calculations, before returning the answer.

Examples of Automation servers are installed in the Visual FoxPro...\Samples\Servers directory.

Creating the Automation Server

All you need to create an Automation server in Visual FoxPro is a project that contains classes defined as OLEPUBLIC. You can have as many OLEPUBLIC classes as you want in the project and they can be defined in program files (.prg) or class libraries (.vcx).

For example, the following class definition in a program file creates a custom OLE public class:

DEFINE CLASS person AS CUSTOM OLEPUBLIC
   FirstName = SPACE(30)
   LastName = SPACE(45)

   PROCEDURE GetName
      RETURN THIS.FirstName + " " + THIS.LastName
   ENDPROC
ENDDEFINE

When you're designing a class in the Class Designer, select OLE Public in the Class Info dialog box to designate the class as OLEPUBLIC.

Compiling the Automation Server

In Visual FoxPro, you can create either an out-of-process or an in-process Automation server. An out-of-process component is an executable (.exe file) that runs in its own process. Communication between a client application and an out-of-process server is therefore called cross-process communication. An in-process component is a dynamic-link library (DLL) that runs in the same process address space as the client that calls it.

There are benefits to each. An in-process server is faster because there is no inter-process communication overhead. On the other hand, an out-of-process server can be deployed remotely and an in-process server cannot. Additionally, because the in-process server and the client share a process address space, any serious error in the .dll will terminate the client whereas an error in an out-of-process .exe would only terminate the server.

**Note **Because in-process .dll and out-of-process .exe Automation servers are invoked through class instantiation, your project need not specify a main file. In Visual FoxPro you can now build an in-process .dll or an out-of-process .exe Automation server without first specifying a main file in the Project Manager.

When you create an executable with OLE Public classes, you don't lose any of your normal .exe capabilities. You can still run the executable, provide a user interface, and all the normal functionality you would include in an application. You increase the extensibility of your application, though, by allowing other applications to tap into the specific functionality you want to expose.

To compile an Automation server

From the Project Manager, choose Build.
In the Build Options dialog box, choose Build Win32 executable / COM server (exe), Build Single-threaded COM server (dll), or Build Multi-threaded COM server (dll).
Choose OK.

-or-

When you type BUILD<space> in the command window and there is an active project, an Intellisense script will help to complete the BUILD command by showing the full paths to the target and the project

Once you build the project, you can see the server classes displayed in the Project Information dialog box. Here you can also specify a help file and a Help context ID for each class. This help file can be opened from most generic object browsers.

You can choose class-specific instancing values in the Project Information dialog box. The instancing options are:

Not Creatable Even though the class is marked OLE public, it will not be available to other applications. For example, you could have a standard library of OLE public classes used in multiple applications and disable automation of one or more classes for a single application.
Single Use Each client application that uses your server creates a separate instance of the server class. Each instance has a single thread of execution. Although separate instances require more memory, choosing Single Use allows the operating system to apply preemptive multitasking.
Multi Use Once the server has been created, other applications can use the same instance.

Note If you make changes in the Servers tab of the Project Information dialog box, you need to rebuild the .dll or .exe for the new settings to take effect.

When you build a project with OLE public classes, three files are created:

The .dll or .exe file
A type library (.tlb) file
A registry (.vbr) file

The type library file is a binary file that lists all the published classes in your Automation server, along with their properties, methods, and events. OLE object browsers read this information and present it in a readable interface. For more information, see Binding Type Libraries.

The registry file lists the global unique IDs (GUID) for the classes in your server.

Note A .vbr registry file is the same as a .reg registry file except that the .vbr file doesn't include hard-coded paths.

Registering an Automation Server

Your Automation servers are available to other applications once the servers have been added to the Windows Registry. When you build an Automation server, it's automatically registered on the build machine. You can also register your servers on other machines.

When you use the Visual FoxPro Setup to create setup disks, the setup program registers your servers on your customers' machines. You can also manually register servers.

To register an .exe component

Run the .exe file with the /regserver switch.

For example, to register Myserver.exe, run the following command:
```
myserver /regserver
```

To remove an .exe component registry entry

Run the .exe file with the /unregserver switch.

For example, to unregister Myserver.exe, run the following command:
```
myserver /unregserver
```

To register a .dll component

Run REGSVR32 with the name of the server.

For example, to register Myserver.dll run the following command:
```
REGSVR32 myserver.dll
```

To remove a .dll component registry entry

Run REGSVR32 with the name of the server and the /u switch.

For example, to register Myserver.dll run the following command:
```
REGSVR32 /u myserver.dll
```
Note The registry contains the full path name to the file, so if you move the file, you'll need to register it again.

Using the Automation Server

Any application that can create Automation objects can create objects based on your Automation server, set properties that are not HIDDEN or PROTECTED, and call methods. For example, assuming that your server is named foxole and contains a class named person with a GetName method, the following code could be run in Visual FoxPro:

oTest = CREATEOBJECT("foxole.person")
cName = oTest.GetName()

Similar code could be run in Microsoft Excel or Visual Basic:

Set oTest = CreateObject("foxole.person")
cName$ = oTest.GetName()

Handling Exceptions

When a Visual FoxPro Automation server generates an exception, the Automation server sets the COM ErrorInfo object (via IErrorInfo) and cancels out of the current method. The Automation client can either release the Visual FoxPro Automation server or, if the client has access to the COM ErrorInfo object, handle the exception based on that information.

For an example using ErrorInfo, see _ErrorInfo( ) API Library Routine.

The new Visual FoxPro function, COMRETURNERROR( ), handles errors that occur on an Automation server. You can use COMRETURNERROR( ) in the Error method, to populate the COM exception structure with information that Automation clients can use to determine the source of Automation server errors. For more information, see COMRETURNERROR( ) Function.

Raising or Returning Errors from Automation Servers

The only interaction with the objects provided by an Automation server (COM component) is through the methods and properties of the exposed classes. When a client application calls a method of an object, and an error occurs in the Automation server, the method either returns an error value or raises an error in the client application.

The client application decides whether to alert the user or proceed with another execution path. The Automation server itself never interacts with the user. This allows the location of the Automation server to be transparent to the client application. The Automation server can be local, running on the user's computer, or you can use the Remote Automation feature of Visual FoxPro to run it on a network server.