Since this doesn't seem to be documented anywhere online (particularly in the API documentation), it is worth noting that CErrors.NewError will throw an exception if the ThrowExceptionOnError property of the associated IiMISUser object is set to true (assuming you are creating an Error and not a Warning). In this case, it will always throw and never return. At least that's what I gather from digging around in reflector:
public CError NewError(ErrorNumber errorNumber, string errorLocation, ErrorCategory errorCategory, params object[] errorValues)
{
// setup:
CError item = new CError(errorNumber);
// ...
// Decide whether to return a CError or throw an exception.
if ((!this.mBOUser.ThrowExceptionOnError || (errorCategory == ErrorCategory.Warning)) && (!this.mBOUser.ThrowExceptionOnWarning || (errorCategory != ErrorCategory.Warning)))
{
// ...
return item;
}
// ...
switch (errorNumber)
{
case ErrorNumber.InvalidReferenceValue:
throw new InvalidReferenceValueException(message);
// more case-throw's
case ErrorNumber.InvalidContact:
throw new InvalidContactException(message);
}
throw new BusinessRulesViolationException(message);
}
I find it a little weird that the IiMISUser has this effect on CErrors collections associated with objects other than user objects because whether to throw or not has to do with iBO's in general, not user objects specifically:
[Test]
public void Demo_NewError_ThrowsIfUserObjectIsSetToThrowOnError()
{
var defaultStaffUser = CStaffUser.GetDefaultStaffUser();
defaultStaffUser.ThrowExceptionOnError = true; // This is the default.
var payment = new CPayment(defaultStaffUser);
Assert.Throws<InvalidFieldLengthException>(delegate
{
payment.Errors.NewError(ErrorNumber.InvalidFieldLength, "the location", ErrorCategory.FieldValidation);
});
}
[Test]
public void Demo_NewError_DoesNotThrowIfUserObjectIsSetToNotThrowOnError()
{
var defaultStaffUser = CStaffUser.GetDefaultStaffUser();
defaultStaffUser.ThrowExceptionOnError = false;
var payment = new CPayment(defaultStaffUser);
payment.Errors.NewError(ErrorNumber.InvalidFieldLength, "the location", ErrorCategory.FieldValidation);
}
Anyway, that should make for a handy feature when enforcing validation. I assume similar behavior for Warnings, i.e., whenever NewError is used to create a Warning, it will decide whether to return or throw based on the associated IiMISUser's ThrowExceptionOnWarning property.