Creating Connected Data Source Extensions

Note

With the release of ECMA 2.0, this feature has been deprecated and will be removed in future versions. You should use the Extensible Connectivity 2.0 Management Agent Reference for Connector development going forward.

A connected data source extension is a Microsoft .NET Framework class library that implements the following interfaces:

• IMAExtensibleCallExport

• IMAExtensibleFileExport

• IMAExtensibleFileImport

An import-only connected data source extension must implement the IMAExtensibleFileImport interface. The IMAExtensibleFileImport interface performs the following tasks:

• Connects to the connected data source

• Reads the data to be synchronized

• Generates an XML file that is based on this data

• Closes the connection to the connected data source

For a connected data source extension that is used for export only, implement the IMAExtensibleCallExport interface or the IMAExtensibleFileExport interface. The IMAExtensibleCallExport interface performs the following tasks:

• Connects to the connected data source

• Exports one CSEntry object at a time

• Disconnects from the connected data source

The IMAExtensibleFileExport interface performs the following tasks:

• Generates a file that contains all the synchronized data

• Processes this file

For example, you can use the IMAExtensibleFileExport interface to generate a Lightweight Directory Access Protocol (LDAP) Data Interchange Format (LDIF) file that contains the synchronized data, and then start a utility that uses this file to import the synchronized data to your connected data source.

The interfaces that you must implement when you create a connected data source extension also depend on the step type and export modes that are set on the Extensible Connectivity Management Agent (ECMA). The step type and export modes are configured when you create the management agent.

The following table lists the interfaces to implement according to the various configuration scenarios that you can use for the ECMA.

Step types	Export modes	Interfaces to implement
Import and export	Call-based	IMAExtensibleFileImport and IMAExtensibleCallExport
Import and export	File-based	IMAExtensibleFileImport and IMAExtensibleFileExport
Import-only	Call-based	IMAExtensibleFileImport* and IMAExtensibleCallExport
Import-only	File-based	IMAExtensibleFileImport* and IMAExtensibleFileExport
Export-only	Call-based	IMAExtensibleFileImport and IMAExtensibleCallExport*
Export-only	File-based	IMAExtensibleFileImport and IMAExtensibleFileExport*

* Although the Forefront Identity Manager Synchronization Service (FIM Synchronization Service) server requires the listed methods to be implemented, only the starred interfaces are currently used by the FIM Synchronization Service server in this type of connected data source extension. For interfaces that are required but not used by the FIM Synchronization Service server, you can throw the EntryPointNotImplementedException in the methods.

All connected data source extensions must implement the IMAExtensibleFileImport interface and the GenerateImportFile method. In addition to this interface, a connected data source extension must also implement one of the following interfaces, depending on the export mode of the extension:

Export mode	Interface to implement	Methods
Call-based	IMAExtensibleCallExport	BeginExport EndExport ExportEntry
File-based	IMAExtensibleFileExport	DeliverExportFile

Warning

Rules extensions are run in the FIM Synchronization Service Engine's process, which is a 64-bit process. 32-bit only Rules extensions are not supported in FIM.

Importing Custom Data

Applications have the option to create custom data when a file is imported with the GenerateImportFile method. You can use custom data as a watermark to indicate delta updates, or to store application-specific data. When the management agent is created or the server configuration is imported with a new management agent, the custom data, stored in the <custom-data> tag, is empty. Applications implement the GenerateImportFile method to import a file and write the custom data to the server using the following steps:

1. Implement the GenerateImportFile method.

2. Indicate that custom data is set in the GenerateImportFile method by setting the fFullImport parameter to true.

3. Specify the custom data in the customData parameter of the GenerateImportFile method.

Exporting Custom Data

The DeliverExportFile method exports the server configuration or the management agent to a file. A complete copy of the custom data from the FIM Synchronization Service server is exported together with all non-encrypted data.

The following Microsoft Visual Basic example shows how to create an entire class declaration for a call-based connected data source extension.

Imports Microsoft.MetadirectoryServices

Public Class Sample_CallBased_Extension
Implements IMAExtensibleFileImport
Implements IMAExtensibleCallExport

Public Sub GenerateImportFile(ByVal fileName As String, _
                              ByVal connectTo As String, _
                              ByVal user As String, _
                              ByVal password As String, _
                              ByVal configParameters As Microsoft.MetadirectoryServices.ConfigParameterCollection, _
                              ByVal fFullImport As Boolean, _
                              ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection, _
                              ByRef customData As String) _
  Implements Microsoft.MetadirectoryServices.IMAExtensibleFileImport.GenerateImportFile
  ' TODO: Remove this throw statement if you implement this method.
End Sub

Public Sub BeginExport(ByVal connectTo As String, _
                       ByVal user As String, _
                       ByVal password As String, _
                       ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection) _
  Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.BeginExport

  ' TODO: Remove this throw statement if you implement this method.
End Sub

Public Sub EndExport() Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.EndExport

  ' TODO: Remove this throw statement if you implement this method.
End Sub

Public Sub ExportEntry(ByVal modificationType As Microsoft.MetadirectoryServices.ModificationType, _
                       ByVal changedAttributes() As String, _
                       ByVal csentry As Microsoft.MetadirectoryServices.CSEntry) _
  Implements Microsoft.MetadirectoryServices.IMAExtensibleCallExport.ExportEntry
  ' TODO: Remove this throw statement if you implement this method.
End Sub

End Class

The following C# example shows how to create an entire class declaration for a call-based data source extension.

using System;
using Microsoft.MetadirectoryServices;

namespace SampleCDExtension
{
  public class Sample_CallBased_Extension : IMAExtensibleFileImport, IMAExtensibleCallExport
  {
    public Sample_CallBased_Extension()
    {
      //
      // TODO: Add constructor logic here
      //
    }
        
    public void GenerateImportFile(
      string fileName,
      string connectTo,
      string user,
      string password,
      ConfigParameterCollection configParameters,
      Boolean fFullImport,
      TypeDescriptionCollection types,
      ref string customData
      )
      {
        // TODO: Remove this throw statement if you implement this method.
      } 
        
      public void BeginExport(
        string connectTo,
        string user,
        string password,
        ConfigParameterCollection configParameters,
        TypeDescriptionCollection types
        )
        {
          // TODO: Remove this throw statement if you implement this method.
        }
        
      public void ExportEntry(
        ModificationType modificationType,
        string[] changedAttributes,
        CSEntry csentry
        )
        {
          // TODO: Remove this throw statement if you implement this method.
        }
        
     public void EndExport()
     {
       // TODO: Remove this throw statement if you implement this method.
     }
  }
    
}

The following example shows how to create an entire class declaration for a file-based connected data source extension.

Imports Microsoft.MetadirectoryServices

Public Class Sample_CallBased_Extension
Implements IMAExtensibleFileImport
Implements IMAExtensibleFileExport

Public Sub GenerateImportFile(ByVal fileName As String, _
                              ByVal connectTo As String, _
                              ByVal user As String, _
                              ByVal password As String, _
                              ByVal configParameters As Microsoft.MetadirectoryServices.ConfigParameterCollection, _
                              ByVal fFullImport As Boolean, _
                              ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection, _
                              ByRef customData As String) _
  Implements Microsoft.MetadirectoryServices.IMAExtensibleFileImport.GenerateImportFile

  ' TODO: Remove this throw statement if you implement this method.
End Sub

Public Sub DeliverExportFile(ByVal fileName As String, _
                             ByVal connectTo As String, _
                             ByVal user As String, _
                             ByVal password As String, _
                             ByVal configParameters As Microsoft.MetadirectoryServices.ConfigParameterCollection, _
                             ByVal types As Microsoft.MetadirectoryServices.TypeDescriptionCollection) _
  Implements Microsoft.MetadirectoryServices.IMAExtensibleFileExport.DeliverExportFile
  ' TODO: Remove this throw statement if you implement this method.
End Sub

End Class

The following example shows how to create an entire class declaration for a file-based connected data source extension.

using System;
using Microsoft.MetadirectoryServices;

namespace SampleCDExtension
{
  public class Sample_CallBased_Extension : IMAExtensibleFileImport, IMAExtensibleFileExport
    {
      public Sample_CallBased_Extension()
        {
           //
           // TODO: Add constructor logic here
           //
        }
      public void GenerateImportFile(
        string fileName,
        string connectTo,
        string user,
        string password,
        ConfigParameterCollection configParameters,
        Boolean fFullImport,
        TypeDescriptionCollection types,
        ref string customData
        )
        {
          // TODO: Remove this throw statement if you implement this method.
        } 
        
      public void DeliverExportFile(        
        string fileName,
        string connectTo,
        string user,
        string password,
        ConfigParameterCollection configParameters,
        TypeDescriptionCollection types
        )
        {
          // TODO: Remove this throw statement if you implement this method.
        }
    }
}

Exceptions

The Microsoft.MetadirectoryServices namespace has the following exceptions, which are specific to connected data source extensions in FIM Synchronization Service. For information about when the exception should be thrown or caught, see Exceptions.

• BadServerCredentialsException

• EntryExportException

• EntryPointNotImplementedException

• ExtensibleExtensionException

• FatalEntryExportException

• ServerDownException

• UnexpectedDataException

See Also

Concepts

Connected Data Source Extensions
Connected Data Source Extensions Code Examples
How to: Create Connected Data Source Extensions in Visual Basic
How to: Create Connected Data Source Extensions in C#
Compiling Rules and Data Source Extensions