Best Practices for Coding

  • Article

Applies To: Windows Server 2003 with SP1

Previous Sections in This Guide

Here are some best practices for coding rules extensions:

  • Always check to see if a metaverse or connector space attribute value you are about to use in an operation actually exists using .IsPresent.

  • Always check for conditions for which no logic has been written and ensure your code throws the appropriate MIIS 2003 exceptions.

  • Use whatever resources can help you to do the job, like the MIIS 2003 Help and the MIIS 2003 Resource Tool Kit.

  • Use Try and Catch code to catch errors, check the error codes, and throw an appropriate exception with a meaningful error message.

  • Always check your assumptions. If you expect a Boolean in a transaction property, check to see if it is True, False, or something else.

  • Do not trust connector space attribute values without checking them. Either determine that an attribute must contain a properly formatted value because the connected data source enforces this (you can assume a DN from Active Directory is properly formatted) or check its value before propagating it to the metaverse (a joining date might not be correctly formed if it was a free-format field in a database). Ensure that data in the metaverse is as valid as you can make it.

Reading an XML Parameter File

It is useful to use some kind of initialization or configuration file to control the behavior of a .dll file without having to recompile it. You can do this by providing an XML file of parameters that are read in the Initialize sub of a management agent or metaverse .dll assembly (any initialization file will be sufficient, but XMLworks best).

A typical configuration file might look like this:

<rules-extensions>
    <management-agents>
        <phone-ma>
            <enabled>yes</enabled>
        </phone-ma>

        <fabrikam-ad-ma>
            <enabled>yes</enabled>
            <employees>OU=employee,OU=Users,DC=fabrikam,DC=com</employees>
            <contractors>OU=contractor,OU=users,DC=fabrikam,DC=com</contractors>
       </fabrikam-ad-ma>

    </management-agents>
</rules-extensions>

Each management agent has a section, with parameters that (perhaps) enable and disable provisioning for individual management agents, or specify parent containers for creating DNs when provisioning. Specifying parent containers can be very useful as the MIIS 2003 UI only permits global control of provisioning.

The configuration file can be stored in a location that you use frequently, such as the MIIS 2003 Extensions folder, and that is automatically backed up by the MIIS 2003 service.

A typical assembly might look like this:

Dim Phone_MA_Enabled As Boolean

Public Sub Initialize() Implements IMvSynchronization.Initialize
    Const SCENARIO_XML_CONFIG = "\Fabrikam.xml"

    Dim config As XmlDocument = New XmlDocument()
    Dim dir As String = Utils.ExtensionsDirectory.ToString
    Dim rnode As XmlNode

    ' Load the XML file
    config.Load(dir + SCENARIO_XML_CONFIG)

    ' Find the root of the management agents section in the XML file
    rnode = config.SelectSingleNode("rules-extensions/management-agents")

    Phone_MA_Enabled = (rnode.SelectSingleNode _
("phone-ma/enabled").InnerText.ToLower = "yes")

    ' And so on for all the other parameters...

If the XML file is named fabrikam.xml, this assembly loads the file into memory, identifies the node of interest, and sets the boolean Phone_MA_Enabled according to whether the phone-ma node holds a yes or not.

Later the provisioning rule can used code like this:

    ' Only provision into Telephone if the flag is set to true
    If Telephone_MA_Enabled Then
        ProvisionTelephone(mventry)
    End If

Example of Manual Precedence

To use manual precedence, all the rules that can flow values into the metaverse attribute in question must be extension implemented. Also, in the metaverse designer, in the Configure attribute flow precedence dialog box for the metaverse attribute concerned, ensure that Use manual precedence is selected. Where manual precedence is used, each rule must decide whether to write a value or not. Here is an example:

Public Sub MapAttributesForImport(ByVal FlowRuleName As String, ByVal csentry _
As CSEntry, ByVal mventry As MVEntry) Implements _
IMASynchronization.MapAttributesForImport
    Select Case FlowRuleName
        Case "sn"
            If Not mventry("sn").IsPresent OrElse _ 
mventry("sn").LastContributingMA.Name.Equals("Test MA") Then
                mventry("sn").Value = csentry("Surname").Value
            Else
                Throw New DeclineMappingException
            End If

This code example above checks that the metaverse sn attribute is either not present (is null) or the Test MA management agent provided the value that is there. If either of the tests is true, the code flows the csentry surname attribute. The use of DeclineMappingException is important, because if it were not raised then the LastContributingMA for the attribute would be is updated with the name of this management agent even if the mapping does not actually take place, because the conditions for flowing a new value were not met.

Adding a New Management Agent

When adding a new management agent to the deployment, perform similar actions to those you used for the existing management agents, and stop and start any scheduled runs.

  • Prevent any scheduled runs from starting.

  • Turn off provisioning.

  • Import or create the new management agent.

  • Perform a staged full import.

  • Using Preview, check on a few, representative objects that the anticipated actions are performed.

  • Perform a full synchronization for the new management agent.

  • Perform an export run on any affected management agents (perhaps first dropping a file and stopping the run to check outgoing data).

  • Turn on provisioning.

  • Again, perform a full synchronization run for the new management agent; but also perform other full synchronizations from any other management agent with a projection rule as necessary, so that provisioning code has run for every metaverse object, if it is possible that this might result in objects being provisioned in the new management agent.

  • Again, perform an export run on any affected management agents (again, some checking should take place prior to this step).

  • Enable scheduled runs.

After each of these steps, you should check that you have no errors and that the results are as you anticipated.

Next

See Also

Concepts

Introduction to Building Rules Extensions for MIIS 2003
Rules Extension Environment
Identifying Rules Extension Requirements
Management Agent Rules Extensions
Hints and Tips for Building Rules Extensions