ECMJobRunner/ECMJobRunner.Application/Common/Exceptions/JobException.cs

using System;
using System.Collections.Generic;

namespace ECMJobRunner.Application.Common.Exceptions
{
    /// <summary>
    /// Base exception class for job execution failures
    /// Provides a flexible structure for capturing job context and detailed error information
    /// </summary>
    public class JobException : Exception
    {
        /// <summary>
        /// Initializes a new instance of JobException with detailed context information
        /// </summary>
        /// <param name="jobName">Name of the job that failed (e.g., "SQL Main Query", "ReC Request")</param>
        /// <param name="processName">Name of the process/stage being executed (e.g., "MainQueryExecution", "CheckQueryValidation")</param>
        /// <param name="batchId">Unique batch identifier for tracking the execution</param>
        /// <param name="reason">Human-readable reason for the failure (nullable)</param>
        /// <param name="innerException">The underlying exception that caused the failure (nullable)</param>
        /// <param name="details">Additional contextual details as name-value pairs with optional null-handling</param>
        /// <remarks>
        /// The details parameter accepts tuples with:
        /// - Name: Display name of the detail
        /// - Value: String value of the detail (nullable)
        /// - IgnoreIfNull: If true, the detail is omitted from the message when value is null
        /// </remarks>
        public JobException(string jobName, string processName, string batchId, string? reason, Exception? innerException, params (string Name, string? Value, bool IgnoreIfNull)[] details) 
            : base(
                  Message(jobName,
                  [
                      ("Process Name", processName, false),
                      ("Batch Id", batchId, false),
                      ("Reason", reason, true),
                      ..details
                  ]),
                  innerException)
        {
            JobName = jobName;
            ProcessName = processName;
            BatchId = batchId;
        }

        /// <summary>
        /// Gets the name of the job that failed
        /// </summary>
        public string JobName { get; }

        /// <summary>
        /// Gets the name of the process/stage that was being executed when the failure occurred
        /// </summary>
        public string ProcessName { get; }

        /// <summary>
        /// Gets the unique batch identifier for tracking the execution
        /// </summary>
        public string BatchId { get; }

        /// <summary>
        /// Generates a formatted error message with job context and details
        /// </summary>
        /// <param name="jobName">Name of the job that failed</param>
        /// <param name="details">Collection of name-value pairs with optional null-handling</param>
        /// <returns>Formatted multi-line error message with visual separators</returns>
        /// <remarks>
        /// Message format:
        /// <code>
        /// {jobName} could not be completed.
        /// ─────────────────────────────────────────
        ///   Process Name: {processName}
        ///   Batch Id: {batchId}
        ///   {additional details...}
        /// ─────────────────────────────────────────
        /// </code>
        /// Details with IgnoreIfNull=true are omitted when their value is null.
        /// </remarks>
        internal static string Message(string jobName, IEnumerable<(string Name, string? Value, bool IgnoreIfNull)> details)
        {
            var message = new System.Text.StringBuilder();
            message.AppendLine($"{jobName} could not be completed.");
            message.AppendLine("─────────────────────────────────────────");
            foreach (var (name, value, ignoreNullValue) in details)
            {
                if (ignoreNullValue && value is null)
                    continue;
                message.AppendLine($"  {name}: {value}");
            }
            message.AppendLine("─────────────────────────────────────────");
            return message.ToString();
        }
    }
}