Creating a Management Agent Rules Extension in Visual Basic .NET

You can use Visual Studio 2005 to create a management agent rules extension. There are two ways to create the project files for rules extensions:

• Use Identity Manager to create a Visual Studio 2005 project.
• Use Visual Studio 2005 to create the project.

Using Identity Manager is the easiest way to create the project. The Identity Manager creates the necessary files and automatically makes the reference to the Microsoft.MetadirectoryServices assembly. However, using the Identity Manager to create your project files limits you to creating your rules extension on the same system where Microsoft Identity Integration Server (MIIS) is installed. For more information about using Identity Manager to create the project files, see "Create a rules extension for a management agent" in MIIS Help.

If you want to create your rules extension on a different system, you can use Visual Studio 2005 to create the project files. You will need to copy the Microsoft.MetadirectoryServices 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 Microsoft Identity Integration Server program folder. The default folder for MIIS is C:\Program Files\Microsoft Identity Integration Server\bin\assemblies\.

To create a rules extension using Visual Studio 2005, you must complete the following steps:

1. Create a new Visual Basic .NET class library project
2. Add a reference to the Microsoft.MetadirectoryServices assembly
3. Copy the code to the code pane and make changes to the code
4. Build the class library
5. Install the rules extension in the rules extensions folder (Optional)

To create a new Visual Basic .NET class library project using Visual Studio 2005

1. Click Start, point to All Programs, and then click Microsoft Visual Studio 2005.

   The Visual Studio 2005 development environment appears.

2. On the File menu, point to New, and then click Project.

3. In the New Project dialog box, in Project Types, click Visual Basic.

4. On the Template menu, click Class Library.

5. In the Name box, type the name of your rules extension, and then click Browse.

6. Browse to the location where you want to store the project files, click Open, and then click OK.

   Your project name now appears in Solution Explorer.

Note  We recommend that you store the project on your local computer rather than at a network location.

To add a reference to the Microsoft.MetadirectoryServices assembly

1. On the Project menu in Visual Studio 2005, click Add Reference.

2. In the .NET tab of the Add Reference dialog box, 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.dll, and then click Open.

3. 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

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

   
   Imports Microsoft.MetadirectoryServices
   
   ' Replace <sample extension object name> with the name of your rules 
   ' extension class. If you do not replace <sample extension object name> 
   ' with the name of your rules extension class, you will not be able to
   ' compile this file.
   
   Public Class <sample extension object name>
       Implements IMASynchronization
   
       Public Sub Initialize() Implements IMASynchronization.Initialize
           ' TODO: Add initialization code here
       End Sub
   
       Public Sub Terminate() Implements IMASynchronization.Terminate
           ' TODO: Add termination code here
       End Sub
   
       Public Function ShouldProjectToMV(ByVal csentry As CSEntry, ByRef MVObjectType As String) As Boolean Implements IMASynchronization.ShouldProjectToMV
           ' TODO: Remove this throw statement if you implement this method
           Throw New EntryPointNotImplementedException()
       End Function
   
       Public Function FilterForDisconnection(ByVal csentry As CSEntry) As Boolean Implements IMASynchronization.FilterForDisconnection
           ' TODO: Add stay-disconnector code here
           Throw New EntryPointNotImplementedException()
       End Function
   
       Public Sub MapAttributesForJoin(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByRef values As ValueCollection) Implements IMASynchronization.MapAttributesForJoin
           ' TODO: Add join mapping code here
           Throw New EntryPointNotImplementedException()
       End Sub
   
       Public Function ResolveJoinSearch(ByVal joinCriteriaName As String, ByVal csentry As CSEntry, ByVal rgmventry() As MVEntry, ByRef imventry As Integer, ByRef MVObjectType As String) As Boolean Implements IMASynchronization.ResolveJoinSearch
           ' TODO: Add join resolution code here
           Throw New EntryPointNotImplementedException()
       End Function
   
       Public Sub MapAttributesForImport(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByVal mventry As MVEntry) Implements IMASynchronization.MapAttributesForImport
           ' TODO: write your import attribute flow code
           Throw New EntryPointNotImplementedException()
       End Sub
   
       Public Sub MapAttributesForExport(ByVal FlowRuleName As String, ByVal mventry As MVEntry, ByVal csentry As CSEntry) Implements IMASynchronization.MapAttributesForExport
           ' TODO: Add export attribute flow code here
           Throw New EntryPointNotImplementedException()
       End Sub
   
       Public Function Deprovision(ByVal csentry As CSEntry) As DeprovisionAction Implements IMASynchronization.Deprovision
           ' TODO: Remove this throw statement if you implement this method
           Throw New EntryPointNotImplementedException()
       End Function
   End Class
   

2. 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 you see the following message, 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 using the rules extension, install it in the Microsoft Identity Integration Server rules extensions folder. The default folder for rules extensions is C:\Program Files\Microsoft Identity Integration Server\Extensions.

This procedure is optional. Alternatively, you can set Visual Studio 2005 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

1. In Solution Explorer, click your class library project.

2. On the View menu, click Property Pages.

3. Select the Compile tab.

4. In the Configuration drop-down list box, click All Configurations.

5. In Build Output Path textbox, 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 C:\Program Files\Microsoft Identity Integration Server\Extensions.

6. 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 SQL Server 2000 database. If any file in this folder is locked, the backup to the SQL Server 2000 database fails.
• Avoid making changes to any files in the Extensions folder while running a management agent run profile. If you change a file in the Extensions folder while running a management agent run profile, the action will return the "stopped-extension-dll-updated-version" value.
• Store configuration information required by your rules extension in an initialization file in the Extensions folder, since the Extensions folder is backed up by the SQL Server database. For more information, see Example:_Reading_Settings_for_Rules_Extensions.

Send comments about this topic to Microsoft

Build date: 2/16/2009