Retrieving an Array Object

After the root object is obtained by creating an instance of the FPC object, all the array-level configuration settings defined in the hierarchy of administration COM objects for the single Forefront TMG server or multiple Forefront TMG servers associated with an array can be accessed through the applicable FPCArray object, which is an element of the FPCArrays collection. The way in which an FPCArray object is retrieved depends on the components of Forefront TMG that are installed and running on the computer on which the root object is created.

Retrieving the Array Object for the Local Computer

If the Microsoft Firewall service is installed on the computer on which the root object is created, the GetContainingArray method can be called on the root object to retrieve the FPCArray object that represents the array associated with the local Forefront TMG server, as in the following Visual Basic Scripting Edition (VBScript) code.

' Create the root object.
Dim root  ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
Dim tmgArray  ' An FPCArray object
Set tmgArray = root.GetContainingArray()

In Forefront TMG Standard Edition, this FPCArray object provides access to the stored configuration settings of only a single Forefront TMG server.

Retrieving the Array Object from a Remote Management Computer

The root object can also be created for remote management on a computer on which Forefront TMG Management is installed without the Microsoft Firewall service. Such a computer is called a remote management computer.

A remote management computer can create a root object, but it cannot access the properties of the root object or any other object in the administration COM object hierarchy until it connects to a Configuration Storage server in a call to the ConnectToConfigurationStorageServer method on the root object. After this call succeeds, your application or script can access any property or method in the administration COM hierarchy of objects that is supported in the specific deployment.

A Configuration Storage server is a Forefront TMG computer on which Active Directory Lightweight Directory Services (AD LDS), the ISASTGCTRL service, and the Microsoft Forefront TMG Storage (ISASTG) service are running. The following types of Forefront TMG servers are Configuration Storage servers.

• A standalone Forefront TMG server.
• An array manager.
• An Enterprise Management Server (EMS).

The ConnectToConfigurationStorageServer method can be used to connect only to Forefront TMG servers of these types from a remote management computer.

Note  Only computers whose IP addresses are included in the Remote Management Computers computer set of the specified Configuration Storage server can access it for remote management, and the user must have permissions to access the specified server. If user credentials are not supplied in the call to ConnectToConfigurationStorageServer, the credentials of the logged-on user are used.

If the logged-on user does not have the permissions needed to access information stored on the Configuration Storage server, the ConnectToConfigurationStorageServer method must be called with the credentials of an enterprise administrator or an enterprise auditor to connect to a Configuration Storage server before any array object can be retrieved.

Multiple Forefront TMG servers can be administered in a single script or application from the same remote management computer by successively connecting to and disconnecting from each applicable Configuration Storage server.

When run on a Forefront TMG computer, this VBScript subprocedure receives the name of a Configuration Storage server and the credentials of an enterprise administrator in the parameters passed to it, connects to the specified Configuration Storage server using the credentials of the enterprise administrator supplied, retrieves the FPCArray object for the specified computer, and disconnects from the Configuration Storage server.

Sub ConnectToCSS(CSSName, userName, domainName, password)
    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")
    ' Declare the other object needed.
    Dim tmgArray      ' An FPCArray object
    ' Connect to the Configuration Storage server.
    root.ConnectToConfigurationStorageServer CSSName, userName, domainName, password
    ' Retrieve a reference to the array object
    ' for the specified Forefront TMG server.
    Set tmgArray = root.GetContainingArray()
    ' Add steps to retrieve or set properties.
   ' Disconnect from the Configuration Storage server.
   root.DisconnectFromConfigurationStorageServer
End Sub

Send comments about this topic to Microsoft

Build date: 6/30/2010