From 8a1a57950129ad8bdd8c072dd4be11c6328e79d7 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Sat, 11 Jul 2026 12:38:31 +0200
Subject: [PATCH] feat: add DEX job exception handling and configuration

Exceptions:
- DEXJobException: custom exception with formatted error messages
  * Includes query name, batch ID, SQL query, and detailed error info
  * Two constructors: with inner exception or reason message
  * Comprehensive XML documentation

Options:
- DexJobOptions: hierarchical configuration for DEX job execution
  * Error handling per stage (MainQuery, CheckQuery, ReCRequest)
  * Granular error actions (OnExecution, IfNullOrWhiteSpace, OnUnexpectedResult)
  * Placeholder configuration with regex pattern support
  * Default BatchId placeholder: #INT#BATCH_ID (case-insensitive)
  * Fully documented with XML comments
---
 .../Common/Exceptions/DEXJobException.cs      |  68 ++++++++++++
 .../Common/Options/DexJobOptions.cs           | 105 ++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 ECMJobRunner.Application/Common/Exceptions/DEXJobException.cs
 create mode 100644 ECMJobRunner.Application/Common/Options/DexJobOptions.cs

diff --git a/ECMJobRunner.Application/Common/Exceptions/DEXJobException.cs b/ECMJobRunner.Application/Common/Exceptions/DEXJobException.cs
new file mode 100644
index 0000000..5cb974f
--- /dev/null
+++ b/ECMJobRunner.Application/Common/Exceptions/DEXJobException.cs
@@ -0,0 +1,68 @@
+using System;
+
+namespace ECMJobRunner.Application.Common.Exceptions
+{
+    /// <summary>
+    /// Exception thrown when a DEX job operation fails
+    /// </summary>
+    public class DEXJobException : Exception
+    {
+        /// <summary>
+        /// Initializes a new instance with an inner exception
+        /// </summary>
+        /// <param name="queryName">Name of the query that failed</param>
+        /// <param name="batchId">Batch ID associated with the operation</param>
+        /// <param name="sqlQuery">SQL query that was executed (nullable)</param>
+        /// <param name="innerException">The inner exception that caused the failure</param>
+        public DEXJobException(string queryName, string batchId, string? sqlQuery, Exception innerException)
+            : base(
+                $"[SQL Execution Failure] Query '{queryName}' could not be completed for Batch '{batchId}'." + Environment.NewLine +
+                "─────────────────────────────────────────" + Environment.NewLine +
+                "  Query:" + (sqlQuery is null ? string.Empty : Environment.NewLine + $"    {sqlQuery}") + Environment.NewLine + Environment.NewLine +
+                "  Root Cause:" + Environment.NewLine +
+                $"    {innerException?.Message}" + Environment.NewLine +
+                "─────────────────────────────────────────",
+                innerException)
+        {
+            SqlQuery = sqlQuery;
+            BatchId = batchId;
+            QueryName = queryName;
+        }
+
+        /// <summary>
+        /// Initializes a new instance with a reason message
+        /// </summary>
+        /// <param name="queryName">Name of the query that failed</param>
+        /// <param name="batchId">Batch ID associated with the operation</param>
+        /// <param name="sqlQuery">SQL query that was executed (nullable)</param>
+        /// <param name="reason">Reason for the failure</param>
+        public DEXJobException(string queryName, string batchId, string? sqlQuery, string reason)
+            : base(
+                $"[SQL Execution Failure] Query '{queryName}' could not be completed for Batch '{batchId}'." + Environment.NewLine +
+                "─────────────────────────────────────────" + Environment.NewLine +
+                "  Query:" + (sqlQuery is null ? string.Empty : Environment.NewLine + $"    {sqlQuery}") + Environment.NewLine + Environment.NewLine +
+                "  Reason:" + Environment.NewLine +
+                $"    {reason}" + Environment.NewLine +
+                "─────────────────────────────────────────")
+        {
+            SqlQuery = sqlQuery;
+            BatchId = batchId;
+            QueryName = queryName;
+        }
+
+        /// <summary>
+        /// Gets the SQL query that failed (if available)
+        /// </summary>
+        public string? SqlQuery { get; }
+
+        /// <summary>
+        /// Gets the batch ID associated with the operation
+        /// </summary>
+        public string BatchId { get; }
+
+        /// <summary>
+        /// Gets the name of the query that failed
+        /// </summary>
+        public string QueryName { get; }
+    }
+}
diff --git a/ECMJobRunner.Application/Common/Options/DexJobOptions.cs b/ECMJobRunner.Application/Common/Options/DexJobOptions.cs
new file mode 100644
index 0000000..988fc65
--- /dev/null
+++ b/ECMJobRunner.Application/Common/Options/DexJobOptions.cs
@@ -0,0 +1,105 @@
+using ECMJobRunner.Application.Common.Constants;
+using System.Text.RegularExpressions;
+
+namespace ECMJobRunner.Application.Common.Options
+{
+    /// <summary>
+    /// Configuration options for DEX job execution
+    /// </summary>
+    public class DexJobOptions
+    {
+        /// <summary>
+        /// Error handling options for DEX job operations
+        /// </summary>
+        public record DexJobErrorHandlingOptions
+        {
+            /// <summary>
+            /// Error handling options for SQL query execution
+            /// </summary>
+            public record SqlQueryErrorHandlingOptions
+            {
+                /// <summary>
+                /// Action to take when query execution fails
+                /// </summary>
+                public ErrorAction OnExecution { get; set; } = ErrorAction.Stop;
+
+                /// <summary>
+                /// Action to take when query is null or whitespace
+                /// </summary>
+                public ErrorAction IfNullOrWhiteSpace { get; set; } = ErrorAction.Ignore;
+
+                /// <summary>
+                /// Action to take when query returns unexpected result
+                /// </summary>
+                public ErrorAction OnUnexpectedResult { get; set; } = ErrorAction.Stop;
+            }
+
+            /// <summary>
+            /// Error handling options for HTTP requests
+            /// </summary>
+            public record HttpRequestErrorHandlingOptions
+            {
+                /// <summary>
+                /// Action to take when HTTP request fails
+                /// </summary>
+                public ErrorAction OnSending { get; set; } = ErrorAction.Stop;
+            }
+
+            /// <summary>
+            /// Error handling for main SQL query
+            /// </summary>
+            public SqlQueryErrorHandlingOptions MainQuery { get; set; } = new();
+
+            /// <summary>
+            /// Error handling for check SQL query
+            /// </summary>
+            public SqlQueryErrorHandlingOptions CheckQuery { get; set; } = new();
+
+            /// <summary>
+            /// Error handling for ReC HTTP request
+            /// </summary>
+            public HttpRequestErrorHandlingOptions ReCRequest { get; set; } = new();
+        }
+
+        /// <summary>
+        /// Error handling configuration
+        /// </summary>
+        public DexJobErrorHandlingOptions Error { get; set; } = new();
+
+        /// <summary>
+        /// Placeholder configuration for dynamic value replacement
+        /// </summary>
+        public record PlaceHolderOptions
+        {
+            /// <summary>
+            /// Configuration for a single placeholder
+            /// </summary>
+            public record PlaceHolder
+            {
+                /// <summary>
+                /// Regex pattern to match the placeholder
+                /// </summary>
+                public string Pattern { get; set; } = null!;
+
+                /// <summary>
+                /// Regex options for pattern matching
+                /// </summary>
+                public RegexOptions RegexOptions { get; set; } = RegexOptions.IgnoreCase;
+            }
+
+            /// <summary>
+            /// BatchId placeholder configuration
+            /// </summary>
+            public PlaceHolder BatchId { get; set; } = new()
+            {
+                Pattern = "#INT#BATCH_ID",
+                RegexOptions = RegexOptions.IgnoreCase
+            };
+        }
+
+        /// <summary>
+        /// Placeholder configuration
+        /// </summary>
+        public PlaceHolderOptions Placeholders { get; set; } = new();
+    }
+}