Registering Web Filters in Enterprise Edition

In ISA Server Enterprise Edition, enterprise and array configuration settings are stored centrally on Configuration Storage servers. Each ISA Server computer in an enterprise obtains the enterprise configuration settings and the array configuration settings for its array from a Configuration Storage server and maintains a locally stored effective configuration that is derived from the enterprise configuration and the array configuration. Web filters can be registered in the Web filters collections in the enterprise configuration and in array configurations. The Web filters collection in the enterprise configuration is not ordered, while the Web filters collection in an array configuration is ordered and provides methods for changing the ordinal position of each Web filter in the collection.

In addition, ISA Server Management can be extended for a Web filter by adding property pages for configuring the Web filter on the enterprise and array levels.

A Web filter can work on a ISA Server computer only if all of the following conditions are met:

Registering the Web filter in the array configuration is required for enforcing its policy in the array. Registering a Web filter in the enterprise configuration is optional, but provides several benefits. When you register a Web filter in the enterprise configuration, you can do the following:

The Setup code for a Web filter may offer the following registration options:

Registering and Unregistering the Web Filter in the Enterprise Configuration

The process of registering and unregistering a Web filter as an object in the enterprise configuration stored on a Configuration Storage server includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified Configuration Storage server with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator. This step can be skipped when Setup is run on a Configuration Storage server.
  3. Using the FPC.Enterprise property to get a reference to the FPCEnterprise object.
  4. Using the FPCEnterprise.Extensions property to get a reference to the FPCExtensions object for the enterprise configuration.
  5. Using the FPCExtensions.WebFilters property to get a reference to the FPCWebFilters collection.
  6. Calling the FPCWebFilters.Add method with the Web filter's GUID, the filter's name, the path for storing the filter's DLL, including the file name of the DLL, relative to the ISA Server installation folder, the filter's priority, and the filter's direction, or calling FPCWebFilters.Remove to unregister the Web filter in the enterprise configuration and skipping the next step. Note that the path and priority supplied in the call to the Add method are ignored in the enterprise configuration.
  7. Setting the vendor parameters sets and additional properties of the Web filter.
  8. Calling the Save method on the FPCWebFilters collection to write the changes in the stored enterprise configuration.
  9. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the Configuration Storage server. This step can be skipped when Setup is run on a Configuration Storage server.

If an enterprise administrator wants to register a Web filter in the enterprise configuration from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the Configuration Storage server before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Registering and Unregistering the Web Filter in an Array

In ISA Server Enterprise Edition, an enterprise administrator can create an empty array and add a Web filter to the array configuration before adding any ISA Server computers to the array. This code is applicable to registering and unregistering the Web filter in an empty array or in an array that has array members.

Administrators should run this code only once to register the Web filter in an array. It can be run on a remote management computer, a Configuration Storage server, or an array member. If this code is run on an array member, it also registers or unregisters the Web filter as an installed Web filter on the array member.

The process of registering and unregistering a Web filter in an array includes the following steps:

  1. Creating an instance of the FPC root object and obtaining a reference to it.
  2. Calling FPC.ConnectToConfigurationStorageServer to connect to the specified Configuration Storage server with the credentials of the user who is logged on. Code can be added for supplying the credentials of an enterprise administrator. This step can be skipped when Setup is run on a Configuration Storage server.
  3. Using the FPC.Arrays property to get a reference to the FPCArrays collection of the arrays collection.
  4. Calling the FPCArrays.Item method to get a reference to the FPCArray object representing the array.
  5. Using the FPCArray.Extensions property to get a reference to the FPCExtensions object for the array.
  6. Using the FPCExtensions.WebFilters property to get a reference to the FPCWebFilters collection for the array.
  7. Calling the FPCWebFilters.Add method with the Web filter's GUID, the filter's name, the path for storing the filter's DLL, including the file name of the DLL, relative to the ISA Server installation folder, the filter's priority, and the filter's direction, or calling FPCWebFilters.Remove to unregister the Web filter in the array and skipping the next step. Note that a Web filter can be removed from an array configuration only after all the references to it in the FPCRefs collection stored in the InstalledWebFilters property of every member of the array have been removed.
  8. Setting the vendor parameters sets and additional properties of the Web filter, particularly its description, the name of the vendor who supplied it, and the version number.
  9. Registering events and alerts in the array configuration (optional). For more information about creating an event and alert in an array, see Signaling Events and Alerts.
  10. Calling the Save method on the FPCWebFilters collection to write the changes in the stored enterprise configuration.
  11. Calling FPC.DisconnectFromConfigurationStorageServer to close the connection with the Configuration Storage server. This step can be skipped when Setup is run on a Configuration Storage server.

Steps for changing the order of the filters in the collection using the FPCWebFilters.MoveDown and FPCWebFilters.MoveUp methods may be added.

After these steps are performed, the Web filter can be installed and registered on the array members.

If this code is run on an array member to register the Web filter in its array, the DLL should be copied to the computer and stored in the location that will be passed in the RelativePath parameter of the FPCWebFilters.Add method sometime before this method is called. When the FPCWebFilters.Add method is called to register the Web filter in the array, this method also registers the Web filter as being installed on the array member by creating a reference to the new FPCWebFilter object in the FPCRefs collection stored in the InstalledWebFilters property of the local ISA Server computer.

After a Web filter is registered in an array, a Web filter not registered alert may be issued on array members that have the filter in their array configuration, but do not have a reference to it in their InstalledWebFilters property. This alert indicates that the steps required to install and register the Web filter on those array members must still be performed. We recommend resetting this alert after the filter is registered on all the array members.

If an enterprise administrator wants to register a Web filter in an array from a workgroup computer, the Cmdkey command-line tool (Cmdkey.exe) or the Stored User Names and Passwords program must be used to create stored credentials for accessing the Configuration Storage server before launching the registration process. After completing the registration process, the user should run Cmdkey or open Shared User Names and Passwords again to delete the credentials.

Installing and Registering the Web Filter on an Array Member

The process of installing and uninstalling a Web filter on an array member after the Web filter has been registered in the array includes the following steps:

  1. Copying the Web filter's DLL to the array member and storing it in the location that was specified in the RelativePath parameter of the FPCWebFilters.Add method when the Web filter was registered in the array.
  2. Creating an instance of the FPC root object and obtaining a reference to it.
  3. Calling the FPC.GetContainingServer method to get a reference to the FPCServer object representing the ISA Server computer.
  4. Using the FPCServer.InstalledWebFilters property to get a reference to the FPCRefs collection of references to the Web filters installed on the server.
  5. Calling the FPCRefs.Add method and specifying the Web filter's GUID in the Name parameter to create a reference to the FPCWebFilter object in the FPCRefs collection stored in the InstalledWebFilters property of the local ISA Server computer, or calling FPCRefs.RemoveSpecified and specifying the Web filter's GUID in the Name parameter to unregister the Web filter as being installed on the array member. Note that the FPCRefs.Add method will fail with HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS) if the Web filter was installed by running the option to register the Web filter in the array on the array member. This error should be ignored.
  6. Calling the Save method on the FPCServer object to write the changes in the stored array configuration.

Registering the ISA Server Management Extension for the Web Filter

For information about creating an extension to ISA Server Management for a Web filter and registering the extension, see Extending Forefront TMG Management.


Send comments about this topic to Microsoft

Build date: 11/30/2009

© 2008 Microsoft Corporation. All rights reserved.