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>
    /// <remarks>
    /// Initializes a new instance of JobException with detailed context information
    /// </remarks>
    /// <param name="profileId">Identifier of the profile associated with the job</param>
    /// <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 class JobException(long profileId, string jobName, string processName, string batchId, string? reason, Exception? innerException, params (string Name, string? Value, bool IgnoreIfNull)[] details)
        : Exception(
              CreateMessage(jobName,
                  [
                      ("Profile Id", profileId.ToString(), false),
                      ("Job Name", jobName, false),
                      ("Process Name", processName, false),
                      ("Batch Id", batchId, false),
                      ("Reason", reason, true),
                      ..details
                  ]),
              innerException)
    {
        /// <summary>
        /// Gets the profile identifier associated with the job execution
        /// </summary>
        public long ProfileId { get; } = profileId;

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

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

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

        /// <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 CreateMessage(string jobName, IEnumerable<(string Name, string? Value, bool IgnoreIfNull)> details)
        {
            var message = new System.Text.StringBuilder();
            message.AppendLine($"{jobName} could not be completed.");
            foreach (var (name, value, ignoreNullValue) in details)
            {
                if (ignoreNullValue && value is null)
                    continue;
                message.AppendLine($"  {name}: {value}");
            }
            return message.ToString();
        }
    }
}