chore: Improve error reporting in ResolveSqlProjAndInputs for MSBuild Full Framework failures (#35)

Author: Copilot

src/JD.Efcpt.Build.Tasks/ResolveSqlProjAndInputs.cs

@@ -300,6 +300,12 @@ private bool ExecuteCore(TaskExecutionContext ctx)
     {
         var log = new BuildLog(ctx.Logger, "");
 
+        // Log runtime context for troubleshooting
+        var runtime = System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription;
+        log.Detail($"MSBuild Runtime: {runtime}");
+        log.Detail($"ProjectReferences Count: {ProjectReferences?.Length ?? 0}");
+        log.Detail($"SolutionPath: {SolutionPath}");
+
         Directory.CreateDirectory(OutputDir);
 
         var resolutionState = BuildResolutionState(log);
@@ -356,8 +362,13 @@ private TargetContext DetermineMode(BuildLog log)
             WarnIfAutoDiscoveredConnectionStringExists(log);
             return new(false, "", sqlProjPath);
         }
-        catch
+        catch (Exception ex)
         {
+            // Log detailed exception information to help users diagnose SQL project resolution issues.
+            // This is intentionally more verbose than other catch blocks in this file because this
+            // specific failure point is commonly reported by users and requires diagnostic context.
+            log.Warn($"SQL project detection failed: {ex.Message}");
+            log.Detail($"Exception details: {ex}");
             return null;
         }
     }
@@ -427,10 +438,12 @@ private ResolutionState BuildResolutionState(BuildLog log)
             .Require(state
                 => state.UseConnectionStringMode
                     ? string.IsNullOrWhiteSpace(state.ConnectionString)
-                        ? "Connection string resolution failed"
+                        ? "Connection string resolution failed. No connection string could be resolved from configuration."
                         : null
                     : string.IsNullOrWhiteSpace(state.SqlProjPath)
-                        ? "SqlProj resolution failed"
+                        ? "SqlProj resolution failed. No SQL project reference found. " +
+                          "Add a .sqlproj ProjectReference, set EfcptSqlProj property, or provide a connection string via " +
+                          "EfcptConnectionString/appsettings.json/app.config. Check build output for detailed error messages."
                         : null)
             .Build(state => state);
     }

tests/JD.Efcpt.Build.Tests/ResolveSqlProjAndInputsTests.cs

@@ -698,4 +698,91 @@ private static TaskResult ExecuteTaskSqlProjWithAutoDiscovery(SetupState setup)
         var success = task.Execute();
         return new TaskResult(setup, task, success);
     }
+
+    // ========== Error Reporting Tests ==========
+
+    [Scenario("Provides detailed error message when no SQL project is found")]
+    [Fact]
+    public async Task Provides_detailed_error_message_when_no_sqlproj()
+    {
+        await Given("project with no sqlproj reference", SetupNoSqlProjReference)
+            .When("execute task", ExecuteTaskNoSqlProjReference)
+            .Then("task fails", r => !r.Success)
+            .And("errors are logged", r => r.Setup.Engine.Errors.Count > 0)
+            .And("error contains helpful guidance", r =>
+                r.Setup.Engine.Errors.Any(e => e.Message?.Contains("No SQL project reference found") == true) &&
+                r.Setup.Engine.Errors.Any(e => e.Message?.Contains("Add a .sqlproj ProjectReference") == true ||
+                                              e.Message?.Contains("EfcptConnectionString") == true))
+            .Finally(r => r.Setup.Folder.Dispose())
+            .AssertPassed();
+    }
+
+    [Scenario("Logs warning with exception details when SQL project detection fails")]
+    [Fact]
+    public async Task Logs_warning_with_exception_details_on_detection_failure()
+    {
+        await Given("project with invalid solution path", SetupInvalidSolutionPath)
+            .When("execute task with solution scan", ExecuteTaskInvalidSolutionPath)
+            .Then("task fails", r => !r.Success)
+            .And("warnings logged about detection failure", r =>
+                r.Setup.Engine.Warnings.Any(w => w.Message?.Contains("SQL project detection failed") == true))
+            .Finally(r => r.Setup.Folder.Dispose())
+            .AssertPassed();
+    }
+
+    private static SetupState SetupNoSqlProjReference()
+    {
+        var folder = new TestFolder();
+        var projectDir = folder.CreateDir("src");
+        var csproj = folder.WriteFile("src/App.csproj", "<Project />");
+
+        var engine = new TestBuildEngine();
+        return new SetupState(folder, engine, projectDir, csproj, "", "", "", "", "");
+    }
+
+    private static TaskResult ExecuteTaskNoSqlProjReference(SetupState setup)
+    {
+        var task = new ResolveSqlProjAndInputs
+        {
+            BuildEngine = setup.Engine,
+            ProjectFullPath = Path.Combine(setup.ProjectDir, "App.csproj"),
+            ProjectDirectory = setup.ProjectDir,
+            Configuration = "Debug",
+            ProjectReferences = [], // No SQL project references
+            OutputDir = Path.Combine(setup.ProjectDir, "obj", "efcpt"),
+            DefaultsRoot = TestPaths.DefaultsRoot
+        };
+
+        var success = task.Execute();
+        return new TaskResult(setup, task, success);
+    }
+
+    private static SetupState SetupInvalidSolutionPath()
+    {
+        var folder = new TestFolder();
+        var projectDir = folder.CreateDir("src");
+        var csproj = folder.WriteFile("src/App.csproj", "<Project />");
+
+        var engine = new TestBuildEngine();
+        return new SetupState(folder, engine, projectDir, csproj, "", "", "", "", "");
+    }
+
+    private static TaskResult ExecuteTaskInvalidSolutionPath(SetupState setup)
+    {
+        var task = new ResolveSqlProjAndInputs
+        {
+            BuildEngine = setup.Engine,
+            ProjectFullPath = Path.Combine(setup.ProjectDir, "App.csproj"),
+            ProjectDirectory = setup.ProjectDir,
+            Configuration = "Debug",
+            ProjectReferences = [],
+            OutputDir = Path.Combine(setup.ProjectDir, "obj", "efcpt"),
+            SolutionPath = Path.Combine(setup.ProjectDir, "NonExistent.sln"), // Invalid path
+            ProbeSolutionDir = "true",
+            DefaultsRoot = TestPaths.DefaultsRoot
+        };
+
+        var success = task.Execute();
+        return new TaskResult(setup, task, success);
+    }
 }