What's the essential difference between the two HandleException() methods of Exception Handling Application Block (Ent Lib 4.1)

Question

In the most recent version (4.1, released October 2008) of The Microsoft Enterprise Library's Exception Handling Application Block, there are two HandleException() method signatures, and I am a bit lost on the intent for these, especially since neither the documentation, intellisense, nor the QuickStart apps intimate any meaningful difference.

Here are the two signatures:

bool HandleException(Exception exceptionToHandle, string policyName);

bool HandleException(Exception exceptionToHandle, string policyName, out Exception exceptionToThrow);

All of the examples I have found use the first, as in this example straight out of the XML documentation comments on the actual method:

try
{
   Foo();
}
catch (Exception e)
{
   if (ExceptionPolicy.HandleException(e, name)) throw;
}

And here, from the same source (the XML doc comments for the method), is an example of using the second:

try
{
   Foo();
}
catch (Exception e)
{
   Exception exceptionToThrow;
   if (ExceptionPolicy.HandleException(e, name, out exceptionToThrow))
   {
      if(exceptionToThrow == null)
         throw;
      else
         throw exceptionToThrow;
   }
}

So, my question is, what does using the second one give you that the first does not? This should probably be obvious to me, but my head is a mess today and I don't really want to keep banging my head against the proverbial wall any longer. :)

No speculations, please; I hope to hear from someone that actually knows what they are talking about from experience using this.

Answer 1

If you use a replace handler in the enterprise library config, your replacement exception is returned by means of the second signature .. , out Exception exceptionToThrow).

Answer 2

I believe you are not allowed to throw your original exceptions across WCF service boundaries, this is a security feature (really to make sure that sensitive error information is not propagated through the service chain). Therefore a new execption can be created and passed in via the second parameter out Exception exceptionToThrow) and given a specific exception message and type by means of your configuration (enterprise library replace exception). One example of which is:

            try
            {
                throw new InvalidCastException();
            }
            catch (InvalidCastException ex)
            {
                Exception ex1;
                bool rethrow = ExceptionPolicy.HandleException(ex, "ReplacePolicy1", out ex1);

                if (rethrow)
                {
                    throw new FaultException<ApplicationException>((ApplicationException)ex1, ex1.Message);
                }
            }

Throwing a FaultException (with a Fault contract set up on the WCF operation) prevents the WCF Service from reporting a faulted state error message in your calling application / Service.

Without the second signature i would struggle with error simplification / propagation across WCF service boundries.

Thanks, Paul. (mod to code 8/7/09 - correction comment from John, thanks)

Answer 3

The main difference between the two method overloads is that

bool HandleException(Exception exceptionToHandle, string policyName);

will throw an exception if the PostHandlingAction is set to ThrowNewException.

Whereas the second method overload:

bool HandleException(Exception exceptionToHandle, string policyName, out Exception exceptionToThrow);

does not throw an exception in that case but instead returns the exception to be rethrown as an out parameter.

Actually, both calls invoke the same core code but the second method overload catches the thrown Exception and returns it to the caller.

So the second overload gives you a bit more control since you could perform some additional logic before throwing. It also standardizes the API in the sense that if you use the second HandleException method with the out parameter Enterprise Library will never intentionally handle your exception and throw it for you. i.e. The first method sometimes throws and sometimes relies on you to rethrow (in the case of NotifyRethrow) but the second method always returns and lets the caller throw/rethrow.