Hints and Tips for Building Rules Extensions

Article
10/05/2010

Applies To: Windows Server 2003 with SP1

Previous Sections in This Guide

If you projects become very complex or there are code modules that you can share with other projects, then you should consider breaking the project into separate modules. By breaking your projects into smaller modules, you can record these modules in a shared code library and reuse them in other deployments.

Using the Utils Class

The Utils class provides a useful set of methods and properties that you can use in your projects. Below are a few examples that you might find useful. For a comprehensive list of methods and functions provided by the Utils class, see the MIIS 2003 Developer Help.

The following properties are static; you do not have to create an instance of the class to use them.

ExtensionDirectory

This returns the path of the MIIS 2003 Extensions directory. For example, “C:\Program Files\Microsoft Identity Integration Server\Extensions.”

WorkingDirectory

This returns the path of the management agents’ MIIS 2003 working directory. For example, “C:\Program Files\Microsoft Identity Integration Server\MaData.”

InPreviewMode

This determines if the current operation is running in preview mode. You can use this property to modify the behavior of your code. For example, you might wish to use a different logging level for preview mode.

TransactionProperties

This returns a collection of transaction properties. For a more complete description of the use of this collection and its use, see the Transaction property Bag, below.

Using the Transaction Property Bag

Variables in one rules extension are generally inaccessible from other rules extensions. There are occasions where it is necessary to share information between different rules extensions within the same transaction. For example, when synchronizing a particular csentry, you might wish to transfer information from an attribute flow rule to the provisioning rule to affect the behavior of the provisioning rule. MIIS 2003 provides a way for you to share data through a collection of values that is managed by the Utils class. Items added to this collection exist for the lifetime of the current transaction. Below is a code sample of this collection’s use.

In this example, some complex tests are performed in a rules extension for the Active Directory Application Mode (ADAM) management agent to determine if a particular object should be provisioned into another management agent’s connector space. If the code determines that it should be provisioned, then an entry is added to the collection with a value of True. The provisioning code inspects this entry and only provisions the object if the entry is set to True.

Management agent Rules Extension

   If SomeComplexTest() = True then
      Utils.TransactionProperties.Add("provision-to-adam", True)
   End If

Metaverse Rules Extension

Public Sub Provision(ByVal mventry As Microsoft.MetadirectoryServices.MVEntry) _
Implements Microsoft.MetadirectoryServices.IMVSynchronization.Provision

' … other code here

   If Utils.TransactionProperties.Contains("provision-to-adam") Then
      Dim bADAM As Boolean = Utils.TransactionProperties("provision-to-adam")
      If bADAM Then
         ProvisionADAM(mventry)
      End If
   End If
End Sub

Using the Debugger

Debugging a rules extension is the process of running a rule and identifying and fixing problems within the rules extension logic.

Assuming that you can’t spot a problem simply by examining code, you can arrange to set a break point that interrupts the running of your code and enables you to step line-by-line through your rules extension code within the Visual Studio .NET 2003 debugger, checking which lines are processed and looking at the values of variables and objects as you do.

Another debugging option is to use logging. By using logging, you can include output statements in your code that are typically written to a file. The output in the file can then be used to troubleshoot and fix problems within the rules extension. MIIS 2003 provides a logging capability to do just this. It can also be used for auditing purposes.

Debug By Using Visual Studio .NET 2003 Debugger

When developing a rules extension, the extension must be loaded and run by the MIIS 2003 service.

To debug the rules extension, attach the Visual Studio .NET 2003 debugger to the running miiserver.exe service process.

To enable debugging in your Rules Extension

On the Debug menu, select Processes…
In the Processes dialog box, select the miiservice.exe, and then click Attach….
In the Attach to process dialog box, select the Common Language Runtime check box, and then click OK.
Click Close

Next, set break points within the rules extension code, and then cause the extension to be called.

Triggering your Code

A rules extension is called by running any management agent that triggers the rules extension code. Debugging typically requires running one or a few representatives of csentry through the synchronization process. MIIS 2003 enables you to preview a single csentry or limit the number of objects processed.

Using Preview to Debug a Single CSObject

The Search Connector Space feature enables you to identify a particular csentry and preview the effect of synchronizing it, whether you run a delta of full synchronization. Your rules extension is called exactly as it is during a run, except no metadirectory data actually changes. You can preview again and again without the risk of damaging data, and without changing your start point, which means consistent testing of the process you are debugging.

Limiting the Number of Objects

When you have gotten a rules extension to run for one csentry under Preview, you can run a synchronization run profile. Modify it to specify a limited threshold of objects to be processed. By using a conditional break point you can still stop at points of interest and examine your code and data.

Delta or Full Synchronization

In a Preview or Run Profile, you make a choice of whether to run a delta or full synchronization. That decision has nothing to do with debugging your code; your code is run or not run for various objects according to the rules discussed in “Management Agent Rules Extension Environment” earlier in this subject. For example, only pending csentry parameters are processed in a delta run, explicit disconnectors are never processed, and so on. However, choosing one or the other might help you to debug your data and understand which objects are processed by various rules and which ones are not.

Note

To debug a rules extension in the Visual Studio .NET 2003 debugger, you must create the rules extension within Visual Studio .NET 2003 in a debug build configuration. This not only creates the rules extension assembly, but also creates a program debug data file. This file has the same file name as the rules extension .dll, but has the extension .pdb. To perform debugging successfully, it is important to ensure that both the assembly and the .pdb files are in the Extensions folder on the server running MIIS 2003. When the problem is fixed, switch to the release build configuration, and create the rules extension .dll in this mode.

Handling Exceptions

It can be useful to break into debug mode when an exception is thrown.

The following procedures show you how to configure the Visual Studio .NET 2003 debugger to start on any exception or on a specified exception. Before you perform the following procedures, enable debugging as described in the “To enable debugging in your rules extension” earlier in this subject.

To start the Visual Studio .NET 2003 debugger on any exception

On the Debug menu of Visual Studio .NET 2003, click Exceptions.
In the Exceptions dialog box, click Common Language Runtime Exceptions.
In the When the exception is thrown dialog box, click Break into the debugger.
Click OK.

You can also start the debugger, when a specified exception is thrown, by adding the fully qualified exception name to the appropriate category of exceptions in Visual Studio .NET 2003.

To start the debugger on a specified exception

On the Debug menu of Visual Studio .NET 2003, click Exceptions.
In the Exceptions dialog box, click Common Language Runtime Exceptions, and then click Add.
In New Exceptions dialog box, type the fully qualified exception name, and then click OK. The MIIS 2003 exception names are prefixed with “Microsoft.MetadirectoryServices.” For example, “Microsoft.MetadirectoryServices.EntryPointNotImplementedException” would cause the debugger to be invoked for any exceptions of this type.
In the Exceptions dialog box, under the category that you selected earlier, click your new exception name.
In the When the exception is thrown dialog box, click Break into the debugger.
Click OK.

Debug By Using Tracing and Logging

Tracing is useful if you prefer to see specific logic or error conditions encountered within a rules extension and not using a debugger. This can be accomplished by writing output to a file. Although the .NET Framework provides out-of-the box classes for file output, MIIS 2003 provides a .NET Framework logging assembly that you can use to enable debug tracing. Use the MIIS 2003 logging assembly to implement tracing in your own rules extensions.

The MIIS 2003 logging assembly provides:

The ability to turn tracing on or off without recreating the rules extension.
The configuration of the output file name without recreating the rules extension.
Parallel writes of multiple rules extensions to the same output file.

Configuration of the MIIS 2003 logging assembly is performed by editing the logging.xml file with a text editor.

This logging XML file is located in the Extensions folder of the server running MIIS 2003.

<rules-extension-properties>
<logging>
        <use-single-log>false</use-single-log>
        <file-name>galsync.log</file-name>
        <logging-level>0</logging-level>
</logging>
</rules-extension-properties>

It contains the following three parameters:

use-single-log

If True, all output should be written to the same file that is located in the root of the management agent working folder (madata) on the MIIS 2003 server. If False, the output should be written individually for every management agent to the working folder of each management agent (in madata).

file-name

The name of the file or files to which the output is written.

logging-level

A value of 0 indicates no logging. Any value greater than 0 indicates that when a call is made to write log information to file, the information is written to the file only if the logging level of the call is less than or equal to this value.

To enable logging

In the Solution Explorer, right-click References for your project, and then click Add Reference….
Click Browse…, navigate to the MIIS 2003 Extensions directory, and then select LOGGING.dll. In the code module, just after the Imports Microsoft.MetadirectoryServices command, add:
```
Imports Microsoft.MetadirectoryServices.Logging
```

Adding this code prevents you from having to use a fully qualified name for each command, so you can substitute “Microsoft.MetadirectoryServices.logging.log” with “log,” as in:

Log("Created displayname " & mventry("displayname").Value, True, 2)

Where the True or False determines whether there is a date stamp and the logging level corresponds to a setting in LOGGING.XML as above.

Best Practices for Coding

Share via