Collection Methods and Properties

All the collections that are defined in the Forefront TMG administration object model have a similar set of methods and properties, which are all or a combination of the following.

Method	Description
Save	Writes the current values of all the properties of the collection and its elements to persistent storage. Modifications made to the collection will not be saved until after this method is called. The Save method is recursive, so calling the Save method of a collection will save the data for every subobject within the collection.
Refresh	Reads the values of all the properties of the collection and its elements from persistent storage. The Refresh method does not check whether there are any unsaved changes made to the elements, so all changes made after the last Save method call will be lost. The Refresh method is useful when you want to cancel changes that have been made but not yet saved with the Save method. The Refresh method is recursive, so calling the Refresh method of a collection will read the data for every subobject within the collection.
Add	Adds an element to the collection, and returns a reference to the newly created element. This method takes a string parameter that identifies the new element. The string parameter can be used later to retrieve the element by using the Item method. To save this new element to persistent storage, call the Save method.
Remove	Removes a specified element from the collection. This method takes a string parameter or index of the element to be removed from the collection.
Item	Returns the requested element from the collection. This method retrieves an element by an index that is an integer value. Forefront TMG collection indices are one-based, meaning that the items are numbered from 1 upward. There is no element with an index of 0. In some collections, the Item method can retrieve an element by using the name of the element, which is a string value.

Property	Description
_NewEnum	Retrieves an enumerator object for the collection. An enumerator object provides serial access to the elements of the collection.
Count	Returns an integer value of the number of elements in the collection.
VendorParametersSets	Retrieves an FPCVendorParametersSets collection for the storing and loading of custom data into the collection. The VendorParametersSets property is designed to integrate third-party extensions into Forefront TMG.

Most of the Forefront TMG collections work in the same way. For specific descriptions, see the individual collection reference pages.

With Microsoft® Visual C++®, you can browse a collection to find a particular item by using the _NewEnum property or the Item method. Forefront TMG collections include both the _NewEnum property and the Item method. The _NewEnum property retrieves a pointer to the IUnknown interface of an enumerator object that implements an IEnumVARIANT interface for the collection. An interface pointer to the IEnumVARIANT interface of the enumerator object can be retrieved by calling QueryInterface on the IUnknown interface returned.

In Visual Basic® and Visual Basic Scripting Edition (VBScript), you do not need to explicitly use the _NewEnum property, because it is used implicitly in For Each...In...Next constructs.

Forefront TMG administration COM object collections do not support nested For Each loops on the same collection. For example, the following nested loops will not work because both loops operate on the same collection:

For Each rule1 in isaArray.ArrayPolicy.PolicyRules
	For Each rule2 In isaArray.ArrayPolicy.PolicyRules
		WScript.Echo rule1.Name & " - " & rule2.Name
	Next
Next

The following pair of nested For Each loops will work because each loop applies to a different collection:

For Each isaArray in isaArrays
	For Each rule In isaArray.ArrayPolicy.PolicyRules
		WScript.Echo Rule.Name
	Next
Next

Send comments about this topic to Microsoft

Build date: 11/30/2009