How to: Create Management Agent Rules Extensions in C#

Article
06/15/2010

You can use C# to create a management agent rules extension for Forefront Identity Manager Synchronization Service (FIM Synchronization Service). There are two ways to create the project files for rules extensions:

Use Synchronization Service Manager to create a Microsoft Visual Studio 2008 project.
Use Visual Studio 2008 to create the project.

Using Synchronization Service Manager is the easiest way to create the project. The Synchronization Service Manager creates the necessary files and automatically makes the reference to the Microsoft.MetadirectoryServices assembly. However, using Synchronization Service Manager to create your project files limits you to creating your rules extension on the same system where FIM Synchronization Service is installed. For more information about using Synchronization Service Manager to create the project files, see Forefront Identity Manager Technical Reference.

If you want to create your rules extension on a different system, you can use Visual Studio 2008 to create the project files. You must copy the Microsoft.MetadirectoryServices.dll assembly to your development system and manually create a reference to the assembly. You can find the assembly in the bin\assemblies folder of the FIM Synchronization Service program folder. The default folder for FIM Synchronization Service is %ProgramFiles%\Microsoft Forefront Identity Management\2010\Synchronization Service\bin\assemblies\.

To create a rules extension using Visual Studio 2008, you must follow these steps in the order in which they appear:

Create a new C# class library project.
Add a reference to the Microsoft.MetadirectoryServices assembly.
Copy the code to the code pane and make changes to the code.
Build the class library.
Install the rules extension in the rules extensions folder.

To create a new C# class library project using Visual Studio 2008

Click Start, point to All Programs, and then click Microsoft replace:Visual Studio 2008.

The Visual Studio 2008 development environment appears.
On the File menu, point to New, and then click Project.
In the New Project dialog box, under Project Types, click Visual C#.
On the Templates menu, click Class Library.
In the Name box, type the name of the rules extension that you are creating, and then click Browse.
Browse to the location where you want to store the project files, click Open, and then click OK. The name of the new project now appears in Solution Explorer.

Note

We recommend that you store the project on your local computer instead of a network location.

To add a reference to the Microsoft.MetadirectoryServices assembly

In Visual Studio 2008, on the Project menu, click Add Reference.
In the Add Reference dialog box, on the .NET tab, click Microsoft.MetadirectoryServices, and then click OK. If the file does not appear in the Component Name list, click the Browse tab. Browse to the folder with the assembly file, click Microsoft.MetadirectoryServices, and then click Open.
Click OK to close the Add Reference dialog box.

In Solution Explorer, Microsoft.MetadirectoryServices now appears as one of the references.

To copy the code to the code pane and make changes to the code

Delete the existing code in the code pane, and then copy and paste the following code example in the code pane.

using System;
using Microsoft.MetadirectoryServices;

// Replace <sample namespace name>  with the name of your rules extension.
// If you do not replace <sample namespace name> with the name of your
// rules extension, you will not be able to compile this file.
namespace <sample namespace name>
{
    // Replace <extension object name> with the name of your rules 
    // extension class. If you do not replace <extension object name>
    // with the name of your rules extension class, you will not be 
    // able to compile this file.

    /// <summary>
    /// Summary description for <extension object name>.
    /// </summary>
    public class <extension object name> : IMASynchronization
    {
        public <extension object name>()

        {
            //
            // TODO: Add constructor logic here
            //
        }
        void IMASynchronization.Initialize ()
        {
            //
            // TODO: write initialization code.
            //
        }

        void IMASynchronization.Terminate ()
        {
            //
            // TODO: write termination code.
            //
        }

        bool IMASynchronization.ShouldProjectToMV (CSEntry csentry, out string MVObjectType)
        {
            //
            // TODO: Remove this throw statement if you implement this method.
            //
            throw new EntryPointNotImplementedException();
        }

        DeprovisionAction IMASynchronization.Deprovision (CSEntry csentry)
        {
            //
            // TODO: Remove this throw statement if you implement this method.
            //
            throw new EntryPointNotImplementedException();
        }

        bool IMASynchronization.FilterForDisconnection (CSEntry csentry)
        {
            //
            // TODO: write disconnection filter code.
            //
            throw new EntryPointNotImplementedException();
        }

        void IMASynchronization.MapAttributesForJoin (string FlowRuleName, CSEntry csentry, ref ValueCollection values)
        {
            //
            // TODO: write join mapping code.
            //
            throw new EntryPointNotImplementedException();
        }

        bool IMASynchronization.ResolveJoinSearch (string joinCriteriaName, CSEntry csentry, MVEntry[] rgmventry, out int imventry, ref string MVObjectType)
        {
            //
            // TODO: write join resolution code.
            //
            throw new EntryPointNotImplementedException();
        }

        void IMASynchronization.MapAttributesForImport( string FlowRuleName, CSEntry csentry, MVEntry mventry)
        {
            //
            // TODO: write your import attribute flow code.
            //
            throw new EntryPointNotImplementedException();
        }

        void IMASynchronization.MapAttributesForExport (string FlowRuleName, MVEntry mventry, CSEntry csentry)
        {
            //
            // TODO: write your export attribute flow code.
            //
            throw new EntryPointNotImplementedException();
        }
    }
}

In the code, replace <sample namespace name> with the name of your project. Be sure to remove the angle brackets (< >).
In the code, replace all instances of <sample extension object name> with the name of your rules extension class. Be sure to remove the angle brackets.

To build the class library

On the Build menu, click Build Solution.

If the following message appears, the rules extension was successfully built:
```
------ Build started: Project: Management Agent Rules Extension, Configuration: Debug .NET ------

Preparing resources...
Updating references...
Performing main compilation...
Building satellite assemblies...



---------------------- Done ----------------------

    Build: 1 succeeded, 0 failed, 0 skipped
```
The rules extension file, which has a .dll extension, is in the bin\Debug folder of your project folder. Before you use the rules extension, install it in the FIM Synchronization Service rules extensions folder. The default folder for rules extensions is %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions.

The following procedure is optional. Alternatively, you can set Visual Studio 2008 to install the rules extension automatically in the rules extensions folder as part of the build process.

To install the rules extension in the rules extensions folder

In Solution Explorer, click your class library project.
On the View menu, click Property Pages.
Select the Compile tab.
In the Configuration drop-down list box, click All Configurations.
In the Build Output Path text box, type the name of the rules extensions folder or browse to the location of the rules extensions folder. The default folder for rules extensions is %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions.
Close the Property Pages dialog box.

Keep the following issues in mind when you use the Extensions folder:

Avoid using the Extensions folder to store files that must be kept open or frequently modified, such as log files. The Extensions folder is automatically backed up to the Microsoft SQL Server 2008 database. If any file in this folder is locked, the backup to the SQL Server 2008 database fails.
Avoid making changes to any files in the Extensions folder while you are running a management agent run profile. If you change a file in the Extensions folder while you are running a management agent run profile, the action returns the "stopped-extension-dll-updated-version" value.
Store configuration information that the rules extension requires in an initialization file in the Extensions folder, because the Extensions folder is backed up by the SQL Server database. For more information, see How to: Read Settings for Rules Extensions.

Share via

How to: Create Management Agent Rules Extensions in C#

To create a new C# class library project using Visual Studio 2008

To add a reference to the Microsoft.MetadirectoryServices assembly

To copy the code to the code pane and make changes to the code

To build the class library

To install the rules extension in the rules extensions folder

See Also

Concepts

Additional resources