Creating the Root Forefront TMG Object

You can access almost all Forefront TMG administration COM objects through a single root object. You must first create this root object and then use its properties to access subordinate objects in the object model. All configuration settings are accessed through the root object. For information about accessing the configuration settings for an array object after creating the root object, see Retrieving an Array Object.

To create the root object (an instance of the FPC object) in a scripting language such as Microsoft Visual Basic Scripting Edition (VBScript) or Microsoft JScript®, use the CreateObject function. Use the class name "FPC.Root", as in these examples:

VBScript
```
Set root = CreateObject("FPC.Root")
```
JScript
```
root = new ActiveXObject("FPC.Root");
```

When creating the root object in Visual Basic, you can use the following:

Dim root As New FPCLib.FPC

The CreateObject function is also available to Visual Basic programmers and so, alternatively, the following can be used:

Dim root As FPCLib.FPC
root = CreateObject("FPC.Root")

Creation of the root object is the first step in all Forefront TMG scripts. If you are using Visual Basic, you must have Microsoft Forefront Threat Management Gateway Administration Library selected as a project reference to create this object. For more information about creating a project reference in Visual Basic, see Getting Started with the Administration COM Objects.

When using the administration COM objects in C++, you can use the following code to create the root object and a smart pointer to the IFPC interface:

HRESULT hr;
// Initialize the COM library.
hr = CoInitialize(NULL); 
// Create the Forefront TMG root object.
FPCLib::IFPCPtr sipRoot;
hr = sipRoot.CreateInstance("FPC.Root");

If you are using C++, you must first import the Msfpccom.dll file so that the Forefront TMG administration COM objects can be used. For more information about importing the Msfpccom.dll file, see Getting Started with the Administration COM Objects.

If you are using C#, you must add a reference to the primary interop assembly msfpccom.interop.dll. For more information about retrieving the root object in C# code, see Getting Started with the Administration COM Objects.

Although almost all Forefront TMG administration COM objects can be accessed through a single root object, the FPCFilterExpressions collection is not part of the object hierarchy based on the FPC root object and must be created separately. The following VBScript example creates an instance of the FPCFilterExpressions collection:

Set filter = CreateObject("FPC.FPCFilterExpressions")

When creating the filter expressions collection in Visual Basic, use the following:

Dim root As New FPCLib.FPCFilterExpressions

Dim root As FPCLib.FPCFilterExpressions
root = CreateObject("FPC.FPCFilterExpressions")

When creating the filter expressions collection in C++, you can use the following code to create the collection and a smart pointer to the IFPCFilterExpressions interface:

HRESULT hr;
FPCLib::IFPCFilterExpressionsPtr sipFilterExpressionsCol;
hr = sipFilterExpressionsCol.CreateInstance("FPC.FPCFilterExpressions");

After creating the root object and making changes to the properties of any object accessed through it, your code should not impersonate a different user. For example, changes made to the Forefront TMG configuration in one security context cannot be written to persistent storage in a different security context.

Using the Root Object for Remote Administration

A user may choose to install only the administration components of Forefront TMG on a particular computer, thereby creating a remote management computer for Forefront TMG. That computer will provide the administrator with Forefront TMG Management for performing administration tasks manually and with the Microsoft Forefront Threat Management Gateway Administration Library (Msfpccom.dll) for performing administration tasks programmatically, but will not include Forefront TMG engine components.

Administration code that will be run from a remote management computer must first create the root object. Then, an administrator can call the ConnectToConfigurationStorageServer method on the root object to access a Configuration Storage server. After this call succeeds, the application or script can access any property or method in the administration COM hierarchy of objects.

Note By default, every Forefront TMG computer with the Microsoft Firewall service installed is also a Configuration Storage server.

Send comments about this topic to Microsoft

Build date: 11/30/2009