Creating Connected Data Source Extensions

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

• IMAExtensibleCallExport
• IMAExtensibleFileExport
• IMAExtensibleFileImport

Note  If you plan to use System.DirectoryServices to create a connected data source extension, you must use the .NET Framework version 1.1 or later.

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 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 or IMAExtensibleFileExport interface. The IMAExtensibleCallExport interface is 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 is performs the following tasks:

• Generates a file that contains all the synchronized data
• Processes this file

For example, you can use IMAExtensibleFileExport to generate an 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 need to implement when creating a connected data source extension also depend upon 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 shows you the interfaces to implement according to the various configuration scenarios that can be used for the ECMA.

* Although the ILM 2007 FP1 server requires the listed methods to be implemented, only the starred interfaces are currently used by the ILM 2007 FP1 server in this type of connected data source extension. For interfaces that are required but not used by the ILM 2007 FP1 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 upon the export mode of the extension:

Importing Custom Data

Applications have the option to create custom data when a file is imported with the IMAExtensibleFileImport.GenerateImportFile method. Custom data can be used 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:

• Implement the GenerateImportFile method
• Indicate that custom data is set in the GenerateImportFile method by setting the fFullImport parameter to true
• Specify the custom data in the customData parameter of GenerateImportFile

Exporting Custom Data

The IMAExtensibleFileExport.DeliverExportFile exports the server configuration or the management agent to a file. A complete copy of the custom data from the ILM 2007 FP1 server is exported along with all non-encrypted data.

The following Visual Basic .NET 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 ILM 2007 FP1. For information about when the exception should be thrown or caught, see Exceptions.

• BadServerCredentialsException
• EntryExportException
• EntryPointNotImplementedException
• ExtensibleExtensionException
• FatalEntryExportException
• ServerDownException
• UnexpectedDataException

See Also

Creating a Connected Data Source Extension in Visual Basic .NET
Creating a Connected Data Source Extension in C#

Send comments about this topic to Microsoft

Build date: 2/16/2009