There are two types of exceptions in the C# LDAP SDK:
Most errors that occur throw an LdapException. An LdapException is a general exception including an error message and an LDAP result code. An LdapException can result from physical problems (such as network errors) as well as problems with LDAP operations (for example, if the LDAP add operation fails because of a duplicate entry).
An LdapException can also contain a nested exception or a Throwable class with more information about the cause of the error. To retrieve the nested exception or Throwable class, use LdapException.getCause, which returns the lower-level exception which caused the failure. For example, an IOException with additional information may be returned on a CONNECT_ERROR failure. The various result codes returned from an LDAP request are defined as constants in the LdapException class.
Depending whether you are using asynchronous or synchronous functions, exceptions are handled differently. These differences are outlined in the following sections.
Synchronous methods throw an LdapException on result codes other than SUCCESS. This eliminates the need to check for errors, therefore a standard try/catch statement can be used to handle exceptions.
The following is an example using the LdapException.toString method to print error information:
try {
[Attempt an LDAP operation]
}
catch( LdapException e ) {
Console.WriteLine( "Error: " + e.ToString() );
}
To facilitate user feedback during synchronous searches, intermediate search results can be obtained before the entire search operation is completed by specifying the number of entries to return at a time. By calling the LdapSearchConstraints.BatchSize property, you can set the number of results to obtain before returning information back to the application. The default setting is 1, allowing results to be obtained as they are received by the server. By setting the batch size to 0, you ensure all the results have been received from the server and stored in local memory before returning to the application. This will allow you to enumerate through the results without ever blocking
For the asynchronous methods, exceptions are thrown only for local or non-server errors, such as connection errors or parameter errors. For server errors, LDAP result messages are returned as LdapResponse objects which must be checked by the client for errors.
The following is an example of error handling with a failed asynchronous search.
NOTE:Before you check the response for an error message you need to determine which type of LDAP message has been returned.
//previously determined that the message is an LdapResponse
if (message is LdapResponse)
{
LdapResponse response = (LdapResponse) message;
int status = response.getResultCode();
if (status != LdapException.SUCCESS )
{
Console.WriteLine("Asynchronous search failed.");
throw new LdapException( response.getErrorMessage(),
status,
response.getMatchedDN());
}
}
LdapReferralExceptions are encountered when performing synchronous LDAP operations. They are derived from LdapException and contain a list of URL strings corresponding to referrals received on an LDAP operation.
LdapReferralExceptions are thrown when referral handling is turned off in your application, or if the API attempted to follow a referral and the referral could not be followed. For example, if you have enabled automatic referral handling and the API throws an LdapReferralException, it means the referral could not be followed and you most likely have incomplete results. The LdapReferral exception will contain a list of LDAP URL strings the API attempted to follow.