How to return custom error messages in ECMA2 SP1

While updating my Management Agents (or connectors) and building a new one for a customer, I wanted to take advantage of the new possibility in the Service Pack 1 version of the ECMA2 framework where you can return a custom errorname and error detail to the Synchronization Service Manager. It took me sometime to get my head around this, but I finally got it working.

Before Service Pack 1, you could also use the CSEntryChangeResult to return a error on your imports and export actions. In your PutExportEntries interface code, you would put something like this to return a export error -

CSEntryChangeResult cschangeresult = CSEntryChangeResult.Create(csentryChange.Identifier, null, MAExportError.ExportErrorSyntaxViolation);

This line above would show up as a export error with the error code 'syntax-violation' in the Synchronization Service Manager. You can find the additional MAExportError options here (http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.maexporterror(v=vs.100).aspx).

With Service Pack 1, however, you are now able to return a custom error name and detail, which is awesome because you can give more information to the administrator. The caveat is that you do need to set MAExportError to either ExportErrorCustomContinueRun or ExportErrorCustomStopRun for your custom error information to be returned. These two enumeration options are new for Service Pack 1 and I was struggling for a few hours before I noticed these.

So after changing my MAExportError enumeration value to ExportErrorCustomContinueRun, my custom error message was returned to the Synchronization Service Manager. My line now looks like this -

CSEntryChangeResult cschangeresult = CSEntryChangeResult.Create(csentryChange.Identifier, null, MAExportError.ExportErrorCustomContinueRun, "script-error", scriptResult);

Notice that I keep my error name to the general, well-known syntax of <warning/error>-<message> (second last parameter). I just like this as a best practise but it is not a requirement; you can write any text, you like.

Happy coding.