Add api to handle unhandled async rules exceptions (#4727)

* Fixes #4725
Add a new interface IUnhandledAsyncRuleExceptionHandler so a user can inspect and do somethign with exceptions raised by async rules.

* Add docs

* Add missing assignment line.

* Update Source/tests/Csla.test/ValidationRules/AsyncRuleTests.cs

Fix typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update Source/Csla/Rules/BusinessRules.cs

Add missing doc

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix typo in class name

* Prevent test hos crash during test

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: StefanOssendorf

Source/Csla/Configuration/ConfigurationExtensions.cs

@@ -6,6 +6,7 @@
 // <summary>Implement extension methods for base .NET configuration</summary>
 //-----------------------------------------------------------------------
 using Csla.DataPortalClient;
+using Csla.Rules;
 using Csla.Runtime;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
@@ -58,6 +59,8 @@ public static IServiceCollection AddCsla(this IServiceCollection services, Actio
       services.AddScoped(typeof(IDataPortalCache), cslaOptions.DataPortalOptions.DataPortalClientOptions.DataPortalCacheType);
       cslaOptions.AddRequiredDataPortalServices(services);
 
+      services.AddScoped(typeof(IUnhandledAsyncRuleExceptionHandler), cslaOptions.UnhandledAsyncRuleExceptionHandlerType);
+
       // Default to using LocalProxy and local data portal
       var proxyInit = services.Any(i => i.ServiceType == typeof(IDataPortalProxy));
       if (!proxyInit)

Source/Csla/Configuration/Fluent/CslaOptions.cs

@@ -8,6 +8,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 using Csla.Core;
+using Csla.Rules;
 using Microsoft.Extensions.DependencyInjection;
 
 namespace Csla.Configuration
@@ -50,6 +51,22 @@ public CslaOptions UseContextManager<T>() where T : IContextManager
     /// </summary>
     public Type? ContextManagerType { get; private set; }
 
+    /// <summary>
+    /// Sets the type for the <see cref="IUnhandledAsyncRuleExceptionHandler"/> to be used.
+    /// </summary>
+    /// <typeparam name="T">The type to register for <see cref="IUnhandledAsyncRuleExceptionHandler"/>.</typeparam>
+    /// <returns>This instance.</returns>
+    public CslaOptions UseUnhandledAsyncRuleExceptionHandler<T>() where T : IUnhandledAsyncRuleExceptionHandler
+    {
+      UnhandledAsyncRuleExceptionHandlerType = typeof(T);
+      return this;
+    }
+
+    /// <summary>
+    /// Gets the type used for the <see cref="IUnhandledAsyncRuleExceptionHandler"/>.
+    /// </summary>
+    public Type UnhandledAsyncRuleExceptionHandlerType { get; private set; } = typeof(DontObserveUnhandledAsyncRuleExceptionHandler);
+
     /// <summary>
     /// Sets a value indicating whether CSLA
     /// should fallback to using reflection instead of

Source/Csla/Core/BusinessBase.cs

@@ -1086,7 +1086,7 @@ protected BusinessRules BusinessRules
       get
       {
         if (_businessRules == null)
-          _businessRules = new BusinessRules(ApplicationContext, this);
+          _businessRules = new BusinessRules(ApplicationContext, this, ApplicationContext.GetRequiredService<IUnhandledAsyncRuleExceptionHandler>());
         else if (_businessRules.Target == null)
           _businessRules.SetTarget(this);
         return _businessRules;

Source/Csla/Rules/BusinessRules.cs

@@ -35,11 +35,13 @@ public BusinessRules()
     /// </summary>
     /// <param name="applicationContext"></param>
     /// <param name="target">Target business object.</param>
+    /// <param name="unhandledAsyncRuleExceptionHandler">Handler for unhandled exceptions that occur during asynchronous rule execution.</param>
     /// <exception cref="ArgumentNullException"><paramref name="applicationContext"/> or <paramref name="target"/> is <see langword="null"/>.</exception>
-    public BusinessRules(ApplicationContext applicationContext, IHostRules target)
+    public BusinessRules(ApplicationContext applicationContext, IHostRules target, IUnhandledAsyncRuleExceptionHandler unhandledAsyncRuleExceptionHandler)
     {
       _applicationContext = applicationContext ?? throw new ArgumentNullException(nameof(applicationContext));
       _target = target ?? throw new ArgumentNullException(nameof(target));
+      _unhandledAsyncRuleExceptionHandler = unhandledAsyncRuleExceptionHandler ?? throw new ArgumentNullException(nameof(unhandledAsyncRuleExceptionHandler));
     }
 
 #if NET9_0_OR_GREATER
@@ -49,6 +51,8 @@ public BusinessRules(ApplicationContext applicationContext, IHostRules target)
     [NonSerialized]
     private object _syncRoot = new();
 #endif
+    [NonSerialized]
+    private readonly IUnhandledAsyncRuleExceptionHandler _unhandledAsyncRuleExceptionHandler;
 
     private ApplicationContext _applicationContext;
 
@@ -1120,7 +1124,7 @@ private RunRulesResult RunRules(IEnumerable<IBusinessRuleBase> rules, bool casca
           if (rule is IBusinessRule syncRule)
             syncRule.Execute(context);
           else if (rule is IBusinessRuleAsync asyncRule)
-            RunAsyncRule(asyncRule, context);
+            RunAsyncRule(asyncRule, context, _unhandledAsyncRuleExceptionHandler);
           else
             throw new ArgumentOutOfRangeException(rule.GetType().FullName);
         }
@@ -1151,12 +1155,16 @@ private RunRulesResult RunRules(IEnumerable<IBusinessRuleBase> rules, bool casca
       return new RunRulesResult(affectedProperties, dirtyProperties);
     }
 
-    private static async void RunAsyncRule(IBusinessRuleAsync asyncRule, IRuleContext context)
+    private static async void RunAsyncRule(IBusinessRuleAsync asyncRule, IRuleContext context, IUnhandledAsyncRuleExceptionHandler unhandledAsyncRuleExceptionHandler)
     {
       try
       {
         await asyncRule.ExecuteAsync(context);
       }
+      catch (Exception exc) when (unhandledAsyncRuleExceptionHandler.CanHandle(exc, asyncRule))
+      {
+        await unhandledAsyncRuleExceptionHandler.Handle(exc, asyncRule, context);
+      }
       finally
       {
         context.Complete();

Source/Csla/Rules/DontObserveUnhandledAsyncRuleExceptionHandler.cs

@@ -0,0 +1,7 @@
+namespace Csla.Rules;
+
+internal class DontObserveUnhandledAsyncRuleExceptionHandler : IUnhandledAsyncRuleExceptionHandler
+{
+  public bool CanHandle(Exception exception, IBusinessRuleBase executingRule) => false;
+  public ValueTask Handle(Exception exception, IBusinessRuleBase executingRule, IRuleContext ruleContext) => throw new NotSupportedException();
+}

Source/Csla/Rules/IUnhandledAsyncRuleExceptionHandler.cs

@@ -0,0 +1,24 @@
+namespace Csla.Rules;
+
+/// <summary>
+/// Represents an interface for handling exceptions raised by <see cref="IBusinessRuleAsync"/>.
+/// </summary>
+public interface IUnhandledAsyncRuleExceptionHandler
+{
+  /// <summary>
+  /// Checks whether the given <paramref name="exception"/> and <paramref name="executingRule"/> can be handled.
+  /// </summary>
+  /// <param name="exception">The unhandled <see cref="Exception"/>.</param>
+  /// <param name="executingRule">The rule causing <paramref name="exception"/>.</param>
+  /// <returns><see langword="true"/> if the exception can be handled. Otherwise <see langword="false"/>.</returns>
+  bool CanHandle(Exception exception, IBusinessRuleBase executingRule);
+
+  /// <summary>
+  /// Handles the raised <paramref name="exception"/>.
+  /// </summary>
+  /// <param name="exception">The unhandled <see cref="Exception"/>.</param>
+  /// <param name="executingRule">The rule causing <paramref name="exception"/>.</param>
+  /// <param name="ruleContext">The associated <see cref="IRuleContext"/> to this rule run.</param>
+  /// <returns><see cref="ValueTask"/></returns>
+  ValueTask Handle(Exception exception, IBusinessRuleBase executingRule, IRuleContext ruleContext);
+}

Source/tests/Csla.test/Csla.Tests.csproj

@@ -66,6 +66,8 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\Csla.Generators\cs\AutoImplementProperties\Csla.Generator.AutoImplementProperties.Attributes.CSharp\Csla.Generator.AutoImplementProperties.Attributes.CSharp.csproj" ReferenceOutputAssembly="true" OutputItemType="Analyzer" PrivateAssets="all" />
+    <ProjectReference Include="..\..\Csla.Generators\cs\AutoImplementProperties\Csla.Generator.AutoImplementProperties.CSharp\Csla.Generator.AutoImplementProperties.CSharp.csproj" ReferenceOutputAssembly="false" OutputItemType="Analyzer" />
     <ProjectReference Include="..\Csla.TestHelpers\Csla.TestHelpers.csproj" />
     <ProjectReference Include="..\..\Csla\Csla.csproj" />
   </ItemGroup>

Source/tests/Csla.test/ValidationRules/AsyncRuleTests.cs

@@ -6,9 +6,11 @@
 // <summary>This only works on Silverlight because when run through NUnit it is not running</summary>
 //-----------------------------------------------------------------------
 
+using Csla.Rules;
 using Csla.TestHelpers;
-using FluentAssertions.Execution;
 using FluentAssertions;
+using FluentAssertions.Execution;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 namespace Csla.Test.ValidationRules
@@ -152,11 +154,88 @@ public async Task MyTestMethod()
       await har.WaitForIdle();
 
       var affectedProperties = await har.CheckRulesForPropertyAsyncAwait();
-      using (new AssertionScope()) 
+      using (new AssertionScope())
       {
         har.AsyncAwait.Should().Be("abc");
         affectedProperties.Should().ContainSingle().Which.Should().Be(nameof(AsyncRuleRoot.AsyncAwait));
       }
     }
+
+    [TestMethod($"When an async rule throws an exception the framework must invoke {nameof(IUnhandledAsyncRuleExceptionHandler)}.{nameof(IUnhandledAsyncRuleExceptionHandler.CanHandle)}.")]
+    public async Task AsyncRuleException_Testcase01()
+    {
+      var diContext = CreateDIContextForAsyncRuleExceptions();
+
+      var unhandledExceptionHandler = (TestUnhandledAsyncRuleExceptionHandler)diContext.ServiceProvider.GetRequiredService<IUnhandledAsyncRuleExceptionHandler>();
+      unhandledExceptionHandler.CanHandleResult = true; // Otherwise the test host process will be crashed
+
+      var cp = diContext.CreateDataPortal<DelayedAsyncRuleExceptionRoot>();
+      var bo = await cp.CreateAsync();
+
+      var tcs = new TaskCompletionSource();
+      unhandledExceptionHandler.CanHandleInspector = (_, _) => tcs.SetResult();
+
+      await ForceThreadSwitch(bo, TimeSpan.FromMilliseconds(25));
+
+      await tcs.Task.WaitAsync(TimeSpan.FromMilliseconds(150));
+    }
+
+    [TestMethod($"When an async rules exception can be handled by {nameof(IUnhandledAsyncRuleExceptionHandler)} it must invoke {nameof(IUnhandledAsyncRuleExceptionHandler)}.{nameof(IUnhandledAsyncRuleExceptionHandler.Handle)}.")]
+    public async Task AsyncRuleException_Testcase02()
+    {
+      var diContext = CreateDIContextForAsyncRuleExceptions();
+
+      var unhandledExceptionHandler = (TestUnhandledAsyncRuleExceptionHandler)diContext.ServiceProvider.GetRequiredService<IUnhandledAsyncRuleExceptionHandler>();
+      unhandledExceptionHandler.CanHandleResult = true; // Otherwise the test host process will be crashed
+
+      var cp = diContext.CreateDataPortal<DelayedAsyncRuleExceptionRoot>();
+      var bo = await cp.CreateAsync();
+
+      bool canHandleInvoked = false;
+      unhandledExceptionHandler.HandleInspector = (_, _, _) => canHandleInvoked = true;
+
+      await ForceThreadSwitch(bo, TimeSpan.FromMilliseconds(25));
+
+      await Task.Delay(TimeSpan.FromMilliseconds(150));
+
+      canHandleInvoked.Should().BeTrue();
+    }
+
+    [Ignore("This test can be run but will crash the test host, so this is failing any CI build. But for completness it's here and can be run if necessary.")]
+    [TestMethod($"When the default {nameof(IUnhandledAsyncRuleExceptionHandler)} is used the exception must be handled by a global unhandled exception handler (for this test it's the {nameof(AppDomain)}.{nameof(AppDomain.CurrentDomain)}.{nameof(AppDomain.CurrentDomain.UnhandledException)} event).")]
+    public async Task AsyncRuleException_Testcase03()
+    {
+      var diContext = CreateDIContextForAsyncRuleExceptions();
+
+      bool unobservedTaskExceptionFound = false;
+      AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;
+      try
+      {
+        var unhandledExceptionHandler = (TestUnhandledAsyncRuleExceptionHandler)diContext.ServiceProvider.GetRequiredService<IUnhandledAsyncRuleExceptionHandler>();
+        unhandledExceptionHandler.CanHandleResult = false;
+        var cp = diContext.CreateDataPortal<DelayedAsyncRuleExceptionRoot>();
+        var bo = await cp.CreateAsync();
+
+        await ForceThreadSwitch(bo, TimeSpan.FromMilliseconds(25));
+
+        await Task.Delay(TimeSpan.FromMilliseconds(150));
+
+        unobservedTaskExceptionFound.Should().BeTrue();
+      }
+      finally
+      {
+        AppDomain.CurrentDomain.UnhandledException -= CurrentDomain_UnhandledException;
+      }
+
+      void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e) => unobservedTaskExceptionFound = true;
+    }
+
+
+    private static TestDIContext CreateDIContextForAsyncRuleExceptions() => TestDIContextFactory.CreateDefaultContext(services => services.AddSingleton<IUnhandledAsyncRuleExceptionHandler, TestUnhandledAsyncRuleExceptionHandler>());
+    private static async Task ForceThreadSwitch(DelayedAsyncRuleExceptionRoot root, TimeSpan exceptionDelay)
+    {
+      await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
+      root.ExceptionDelay = exceptionDelay;
+    }
   }
 }

Source/tests/Csla.test/ValidationRules/DelayedAsynRuleExceptionRoot.cs

@@ -0,0 +1,49 @@
+//-----------------------------------------------------------------------
+// <copyright file="DelayedAsyncRuleExceptionRoot.cs" company="Marimer LLC">
+//     Copyright (c) Marimer LLC. All rights reserved.
+//     Website: https://cslanet.com
+// </copyright>
+// <summary>This only works on Silverlight because when run through NUnit it is not running</summary>
+//-----------------------------------------------------------------------
+
+using Csla.Core;
+using Csla.Rules;
+
+namespace Csla.Test.ValidationRules
+{
+  [CslaImplementProperties]
+  internal partial class DelayedAsyncRuleExceptionRoot : BusinessBase<DelayedAsyncRuleExceptionRoot>
+  {
+    public partial TimeSpan ExceptionDelay { get; set; }
+
+    [Create, RunLocal]
+    private void Create()
+    {
+      _ = this;
+    }
+
+    protected override void AddBusinessRules()
+    {
+      base.AddBusinessRules();
+      BusinessRules.AddRule(new RaiseExceptionRuleAsync(ExceptionDelayProperty));
+    }
+
+
+    private class RaiseExceptionRuleAsync : BusinessRuleAsync
+    {
+      public RaiseExceptionRuleAsync(IPropertyInfo primaryProperty) : base(primaryProperty)
+      {
+        InputProperties.Add(primaryProperty);
+      }
+
+      protected override async Task ExecuteAsync(IRuleContext context)
+      {
+        var delay = context.GetInputValue<TimeSpan>(PrimaryProperty);
+
+        await Task.Delay(delay);
+
+        throw new InvalidOperationException("This is a test exception");
+      }
+    }
+  }
+}

Source/tests/Csla.test/ValidationRules/TestUnhandledAsyncRuleExceptionHandler.cs

@@ -0,0 +1,33 @@
+//-----------------------------------------------------------------------
+// <copyright file="TestUnhandledAsyncRuleExceptionHandler.cs" company="Marimer LLC">
+//     Copyright (c) Marimer LLC. All rights reserved.
+//     Website: https://cslanet.com
+// </copyright>
+// <summary>This only works on Silverlight because when run through NUnit it is not running</summary>
+//-----------------------------------------------------------------------
+
+using Csla.Rules;
+
+namespace Csla.Test.ValidationRules
+{
+  internal class TestUnhandledAsyncRuleExceptionHandler : IUnhandledAsyncRuleExceptionHandler
+  {
+    public bool CanHandleResult { get; set; } = true;
+
+    public Action<Exception, IBusinessRuleBase> CanHandleInspector { get; set; }
+
+    public bool CanHandle(Exception exception, IBusinessRuleBase executingRule)
+    {
+      CanHandleInspector?.Invoke(exception, executingRule);
+      return CanHandleResult;
+    }
+
+
+    public Action<Exception, IBusinessRuleBase, IRuleContext> HandleInspector { get; set; }
+    public ValueTask Handle(Exception exception, IBusinessRuleBase executingRule, IRuleContext ruleContext)
+    {
+      HandleInspector?.Invoke(exception, executingRule, ruleContext);
+      return ValueTask.CompletedTask;
+    }
+  }
+}