DP44/Common/DTS.Common.Utilities/Exceptional.cs

/*
Exceptional.cs

Copyright © 2008
Diversified Technical Systems, Inc.
All Rights Reserved
*/

using System;
using System.Runtime.Serialization;
using DTS.Common.Utilities.DotNetProgrammingConstructs;
using DTS.Common.Utilities.Properties;

namespace DTS.Common.Utilities
{
    /// <summary>
    /// "Ultimate" base class for all DTS classes that expect to throw exceptions.
    /// Deriving classes from this class allows exceptions to be trapped based on
    /// the class type that threw them.
    /// </summary>
    ///
    /// <remarks>
    /// Sample usage:
    ///   public class A : Exceptional
    ///   {
    ///      public void ScrewItUp( )
    ///      {
    ///         private bool error = true;
    ///         if ( error ) throw new A.Exception( "Class A-specific screwup." );
    ///      }
    ///   }
    /// 
    ///   ...
    /// 
    ///   try
    ///   {
    ///     A.ScrewItUp( );
    ///     B.ScrewItUp( );
    ///     C.ScrewItUp( );
    ///   }
    ///   catch ( A.Exception ex )
    ///   {
    ///      // Can pick A's exceptions out of a crowd, or not and just treat it
    ///      // polymorphically as a System.Exception.
    ///   }
    /// </remarks>
    /// 
    [Serializable]
    public abstract class Exceptional
    {
        /// <summary>
        /// Initialize an instance of the DerivedClass.Exception class.
        /// </summary>
        public class Exception : ApplicationException
        {
            /// <summary>
            /// create a <see cref="Exceptional.Exception" /> object
            /// </summary>
            public Exception() { }
            /// <summary>
            /// create a <see cref="Exceptional.Exception" /> object
            /// </summary>
            /// <param name="msg">a message that describes the error</param>
            public Exception(string msg) : base(msg) { }
            /// <summary>
            /// create a <see cref="Exceptional.Exception" /> object
            /// </summary>
            /// <param name="msg">a message that describes the error</param>
            /// <param name="innerEx">The exception that is the cause of the current exception.</param>
            public Exception(string msg, System.Exception innerEx) : base(msg, innerEx) { }
            protected Exception(
                SerializationInfo info,
                StreamingContext context) : base(info, context) { }
        }

        /// <summary>
        /// Initialize an instance of the DerivedClass.UserException class.
        /// </summary>
        public class UserException : Exception
        {
            /// <summary>
            /// create a user Exception with a description of the event
            /// </summary>
            /// <param name="msg">description of error</param>
            public UserException(string msg) : base(msg) { }
        }

        /// <summary>
        /// Walk the nested exception tree and generate a single string from their messages.
        /// </summary>
        /// 
        /// <param name="ex">
        /// The parent <see cref="System.Exception"/>.
        /// </param>
        /// 
        /// <returns>
        /// The <see cref="string"/> concatenation of the exception tree's messages.
        /// </returns>
        /// 
        public static string GenerateLogMessageFromExceptionTree(System.Exception ex)
        {
            return GenerateMessageFromExceptionTree(ex, true, true, true);
        }
        public static string GenerateUIMessageFromExceptionTree(System.Exception ex)
        {
            return GenerateMessageFromExceptionTree(ex, true, true, false);
        }
        /// <summary>
        /// Walk the nested exception tree and generate a single string from their messages.
        /// </summary>
        /// 
        /// <param name="ex">
        /// The parent <see cref="System.Exception"/>.
        /// </param>
        /// 
        /// <param name="addNewlines">
        /// <see cref="Boolean"/> true to insert a newline between each exception's message,
        /// false to insert a delimiter between each instead.
        /// </param>
        /// 
        /// <returns>
        /// The <see cref="string"/> concatenation of the exception tree's messages.
        /// </returns>
        /// 
        public static string GenerateLogMessageFromExceptionTree(System.Exception ex, bool addNewlines)
        {
            return GenerateMessageFromExceptionTree(ex, addNewlines, true, true);
        }
        public static string GenerateUIMessageFromExceptionTree(System.Exception ex, bool addNewLines)
        {
            return GenerateMessageFromExceptionTree(ex, addNewLines, true, false);
        }


        /// <summary>
        /// Legacy wrapper for walking the nested exception tree and generating a single string from their messages
        /// </summary>
        /// 
        /// <param name="ex">
        /// The parent <see cref="System.Exception"/>.
        /// </param>
        /// 
        /// <returns>
        /// The <see cref="string"/> concatenation of the exception tree's messages.
        /// </returns>

        public static string GenerateMessageFromExceptionTree(System.Exception ex)
        {
            return GenerateMessageFromExceptionTree(ex, true, true, true);
        }

        /// <summary>
        /// Walk the nested exception tree and generate a single string from their messages.
        /// </summary>
        /// 
        /// <param name="ex">
        /// The parent <see cref="System.Exception"/>.
        /// </param>
        /// 
        /// <param name="addNewlines">
        /// <see cref="Boolean"/> true to insert a newline between each exception's message,
        /// false to insert a delimiter between each instead.
        /// </param>
        /// 
        /// <param name="makeSentence">
        /// <see cref="Boolean"/> true to append "because" after each exception message in
        /// string and end deepest message with a period, false to leave messages raw.
        /// </param>
        /// 
        /// <param name="bLogMessage"></param>
        /// <returns>
        /// The <see cref="string"/> concatenation of the exception tree's messages.
        /// </returns>
        /// 
        public static string GenerateMessageFromExceptionTree(System.Exception ex, bool addNewlines, bool makeSentence, bool bLogMessage)
        {
            var message = "";
            var stackTrace = "";
            var currentEx = ex;
            while (null != currentEx)
            {
                if (bLogMessage)
                {
                    message += string.Format(Resources.Exceptional_GenerateMessageFromExceptionTree_MessageFormatString,
                                              currentEx.Message,
                                              makeSentence && null != currentEx.InnerException
                                                                        ? Resources.Exceptional_GenerateMessageFromExceptionTree_BecauseString
                                                                        : Resources.Exceptional_GenerateMessageFromExceptionTree_ErrorTextTerminatorString,
                                              null != currentEx.InnerException ? (addNewlines ? "\n" : " : ") : "");
                }
                else { message = currentEx.Message; }

                stackTrace += currentEx.StackTrace;
                currentEx = currentEx.InnerException;
            }

#if ( DEBUG )
            if (bLogMessage) { message += "\n\n*** Debug Mode Stack Trace ***\n" + stackTrace; }
#endif

            return message.EndsWith(
                string.Format(Resources.Exceptional_GenerateMessageFromExceptionTree_EndsWithFormatString,
                               Resources.Exceptional_GenerateMessageFromExceptionTree_ErrorTextTerminatorString,
                               Resources.Exceptional_GenerateMessageFromExceptionTree_ErrorTextTerminatorString))
                   ? message.Remove(message.LastIndexOf(Resources.Exceptional_GenerateMessageFromExceptionTree_ErrorTextTerminatorString, StringComparison.Ordinal))
                   : message;

        }

        /// <summary>
        /// Extract the first exception of the specified class type from the specified
        /// exception's exception tree.
        /// </summary>
        /// 
        /// <typeparam name="TExceptionType">
        /// The type of System.Exception-derived class to be extracted.
        /// </typeparam>
        /// 
        /// <param name="ex">
        /// The <see cref="System.Exception"/>-derived class to have its exception tree
        /// searched.
        /// </param>
        /// 
        /// <returns>
        /// The first nested innner exception of type ExceptionType; null otherwise.
        /// </returns>
        /// 
        public static TExceptionType
            ExtractFirstExceptionOfTypeFromExceptionTree<TExceptionType>(System.Exception ex)
            where TExceptionType : System.Exception
        {
            var currentEx = ex;
            while (null != currentEx)
            {
                if (currentEx is TExceptionType exceptionType)
                    return exceptionType;
                currentEx = currentEx.InnerException;
            }
            return null;
        }

        /// <summary>
        /// Determine whether or not the specified exception's exception tree contains
        /// a UserException-derived exception.
        /// </summary>
        /// 
        /// <param name="ex">
        /// The <see cref="System.Exception"/>-derived class to have its exception tree
        /// searched.
        /// </param>
        /// 
        /// <returns>
        /// <see cref="bool"/> true if the specified exception tree contains a
        /// UserException-type exception; false otherwise.
        /// </returns>
        /// 
        public static bool ExceptionTreeContainsUserException(System.Exception ex)
        {
            return null != ExtractFirstExceptionOfTypeFromExceptionTree<UserException>(ex);
        }
    }
}