[API Proposal] Allow Dispatching to Blazor Renderer Sync Context

[Nick-Stanton]

Background and Motivation

Currently, there is not an easy or clean way to marshal exceptions occurring off the Blazor sync context back onto it. The following API would allow developers to directly dispatch exceptions to the renderer.

Fix for #44920

Related community requests: #44871, #27716

Proposed API

namespace Microsoft.AspNetCore.Components;

public abstract class ComponentBase : IComponent, IHandleEvent, IHandleAfterRender
{
+    protected Task DispatchExceptionAsync(Exception exception);
}

public readonly struct RenderHandle
{
+    public Task DispatchExceptionAsync(Exception exception);
}

Usage Examples

// Some code in a component
try
{
    await InvokeAsync(async () => { /* some code that may throw, possibly asynchronously */ });
}
catch (Exception e)
{
    await DispatchExceptionAsync(e);
}

Alternative Designs

An alternative would be to have a method Dispatch() that is used like InvokeAsync() but returns void instead of a task. This would require fewer lines of code to use it, but also would not allow the developer to get a result back from their work item or know when the async operation is completed.

Risks

None that I can think of. Does not cause a breaking change, nor should cause a performance regression.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[SteveSandersonMS]

Looks good to me!

[halter73]

API Review Notes:

• Why doesn't InvokeAsync call DispatchExceptionAsync internally? Will this ever be used for exceptions thrown from something other than InvokeAsync?
  • InvokeAsync is the primary scenario, but this makes this a non-breaking opt-in change.
• How are people going to know to call try/catch? Documentation.
• Is this behavior we even want on every call to InvokeAsync? No. Oftentimes, the error can be handled outside of the renderer.
• Can RenderHandle.DispatchExceptionAsync be internal? Maybe. Edit: No.
• Can this be worked around? Maybe using ExceptionDispatchInfo and SynchronizatinContext.Post? Maybe not that workaround, but there are ugly workarounds that we do not want to suggest to users.
• What does the Task returned by DispatchExceptionAsync represent? When the exception has completed dispatching. So any handlers should have completed handling the error on the UI thread. This should never really throw except maybe an ObjectDisposeException or something.

API Approved!

namespace Microsoft.AspNetCore.Components;

public abstract class ComponentBase : IComponent, IHandleEvent, IHandleAfterRender
{
+    protected Task DispatchExceptionAsync(Exception exception);
}

public readonly struct RenderHandle
{
+    public Task DispatchExceptionAsync(Exception exception);
}

[SteveSandersonMS]

Why doesn't InvokeAsync call DispatchExceptionAsync internally? Will this ever be used for exceptions thrown from something other than InvokeAsync?

InvokeAsync returns a task. So if the invoked call throws, the returned task will be in a failed state with this exception. If we didn't do that, there would be no way for the caller to handle the exceptions.

How are people going to know to call try/catch? Documentation.

The question probably indicates that we were not clear about the use case. The point of DispatchExceptionAsync is when you have exceptions that come from some external system (not the Blazor lifecycle methods) and want to treat them the same as lifecycle method exceptions. So, the premise that you have an exception already implies you caught it. If you don't catch an external exception, then you have an unhandled exception which has nothing to do with Blazor.

Can RenderHandle.DispatchExceptionAsync be internal? Maybe.

No, it needs to be usable by components that don't inherit from ComponentBase.

Can this be worked around? Maybe using ExceptionDispatchInfo and SynchronizatinContext.Post? Maybe not that workaround, but there are ugly workarounds that we do not want to suggest to users.

The only existing workaround, which we use internally in a couple of places, is to write some code that causes a component to re-render itself and to rethrow the exception during rendering. That is a nasty hack, so adding DispatchExceptionAsync is intended to give a clean and obvious way to achieve this.

[halter73]

InvokeAsync returns a task. So if the invoked call throws, the returned task will be in a failed state with this exception. If we didn't do that, there would be no way for the caller to handle the exceptions.

I was thinking it could rethrow, but I did not realize how fatal these dispatched exceptions are. After reading your explanation about this treating the exceptions as equivalent to exceptions in lifecycle methods and then reading https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/handle-errors?view=aspnetcore-7.0#lifecycle-methods, this API makes more sense to me. This is not something you'd want to do by default when the caller to InvokeAsync may be able to handle the exception gracefully.

No, it needs to be usable by components that don't inherit from ComponentBase.

Okay. This API is approved as proposed then. This is somethings we said would be easy to go and add back after API review. I've updated the approval comment, and I'll mention this in the email with the meeting notes.