init

Common/DTS.Common.Utilities/Exceptional.cs

@@ -0,0 +1,262 @@
+/*
+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);
+        }
+    }
+}