Creating Rules Extensions

Microsoft Identity Integration Server 2003 allows you to programmatically modify the behavior that occurs when data that is managed by Microsoft Identity Integration Server 2003 is changed or removed. This behavior modification is allowed by means of an installable component known as a rules extension, which you create.

The following types of rules extensions are supported by Microsoft Identity Integration Server 2003.

Rules extension	Description
Management agent	A management agent rules extension is used on data that flows between the connector space and the metaverse, such as data transformations, join rules, and deprovisioning. Each management agent can have only one rules extension.
Metaverse	A metaverse rules extension is used on data that flows between the metaverse and connector space in response to a change in the metaverse, such as when an attribute value changes or a link is added or removed from a metaverse object.. The metaverse can have only one rules extension.

A rules extension is a Microsoft .NET  Framework class library, which is a dynamic link library (DLL) that implements one or more classes.

A rules extension class must implement a particular interface, which is determined by the type of rules extension being implemented. An interface is a contract that requires the class to implement all the methods of the interface. A management agent rules extension must implement the IMASynchronization interface. A metaverse rules extension must implement the IMVSynchronization interface.

Microsoft Identity Integration Server 2003 performs the following steps when running a rules extension:

1. Opens the class library DLL specified by the management agent or metaverse
2. Loads the extension object by finding a class that implements the proper interface for the type of extension, either IMASynchronization for a management agent extension or IMVSynchronization for a metaverse extension
3. Initializes the extension
4. Calls the appropriate class methods
5. Terminates the extension after a period of inactivity, unloads the extension object, and closes the class library DLL

Exceptions

In the past, methods and functions either returned a failure code or set a particular value on an output parameter to indicate that an error had occurred. The .NET Framework relies more heavily on exceptions than other programming models do. Though structured exception handling is not new, the .NET Framework has expanded the use of exceptions so that they are commonplace. When an exception is passed back to a caller, the exception is thrown. When the caller handles an exception, a caller catches the exception.

The Microsoft.MetadirectoryServices Namespace defines the following exceptions that are specific to Microsoft Identity Integration Server 2003. For information about when the exception should be thrown or caught, see Exceptions.

• AttributeNotDefinedAsSourceException
• AttributeNotInInclusionListException
• AttributeNotPresentException
• DeclineMappingException
• EntryPointNotImplementedException
• ExtensionException
• InvalidDNException
• MissingParentObjectException
• MetadirectoryServicesException
• NoCompatiblePartitionFoundException
• NoSuchAttributeException
• NoSuchAttributeInObjectTypeException
• NoSuchClassException
• NoSuchManagementAgentException
• NoSuchObjectException
• NoSuchObjectTypeException
• ObjectAlreadyExistsException
• TerminateRunException
• TooManyValuesException
• UnexpectedDataException

One instance in which an exception can be used is when a rules extension does not implement a method. If a method is not implemented, the extension should throw the EntryPointNotImplementedException exception. Microsoft Identity Integration Server 2003 will catch this exception and act appropriately.

The following example shows how to to throw the EntryPointNotImplementedException when a management agent rules extension does not implement the IMASynchronization.Deprovision method.

    Public Function Deprovision( _
        ByVal csdepro As CSEntry) _
    As DeprovisionAction _
    Implements IMASynchronization.Deprovision
        Throw New EntryPointNotImplementedException()
    End Function

    DeprovisionAction IMASynchronization.Deprovision (CSEntry csentry)
    {
        throw new EntryPointNotImplementedException();
    }

For more information about implementing specific types of rules extensions, see the following topics:

• Creating a Management Agent Rules Extension
• Creating a Metaverse Rules Extension
• Testing and Debugging Rules Extensions

Send comments about this topic to Microsoft

Build date: 2/16/2009