Exception handling

Lagoon provides a consistent pattern for displaying errors on the Blazor WebAssembly side and for returning errors on the server side.

UI side: ShowException

Lagoon pages and components inherit from LgComponentBase or LgPage. They have ShowException(ex), which delegates to the Lagoon application.

Use this pattern in handlers triggered by the user:

OrderActions.razor

@inherits LgComponentBase

<LgButton Text="#Save" OnClick="SaveAsync" />

OrderActions.razor.cs

namespace Demo.Client.Components;

public partial class OrderActions
{
    private async Task SaveAsync(ActionEventArgs args)
    {
        try
        {
            // Exécute l'action métier appelée depuis l'interface.
            await SaveOrderAsync(args.CancellationToken);
            ShowSuccess("#OrderSaved");
        }
        catch (Exception ex)
        {
            ShowException(ex);
        }
    }

    private Task SaveOrderAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

ShowException(ex) applies the framework rules:

Case	Behavior
LgValidationException	Ignored by ShowException, since it is handled by LgEditForm.
TaskCanceledException	Ignored so as not to display normal cancellations.
AggregateException	Each inner exception is processed individually.
HTTP authentication error	The framework may trigger the reconnection logic.
Other exception	The error is logged, then a user-facing message is displayed.

Server side: Problem(ex)

Application controllers must inherit from LgControllerBase. For actions that explicitly catch exceptions, return Problem(ex).

OrdersController.cs

[ApiController]
[Route("api/[controller]")]
public class OrdersController : LgControllerBase
{
    private readonly OrderService _orderService;

    public OrdersController(OrderService orderService)
    {
        _orderService = orderService;
    }

    [HttpPost]
    public async Task<IActionResult> CreateAsync(VmOrder order, CancellationToken cancellationToken)
    {
        try
        {
            // Valide le ModelState avec le mécanisme standard de Lagoon.
            EnsureModelStateIsValid();
            int orderId = await _orderService.CreateAsync(order, cancellationToken);
            return Ok(orderId);
        }
        catch (Exception ex)
        {
            return Problem(ex);
        }
    }
}

LgControllerBase.Problem(Exception ex) is the standard server-side entry point for letting Lagoon log the exception and turn it into a consistent HTTP response.

User errors

User errors are intended to be displayed in the end user's interface.

Logging

The legacy documentation states that user errors are not sent to the application logs as classic technical errors are.

Exception	Usage
UserException	Business error with a customizable message, ideally localized.
UnauthorizedException	Predefined authorization error.

OrderService.cs

public Task ValidateAsync(VmOrder order, CancellationToken cancellationToken)
{
    if (string.IsNullOrWhiteSpace(order.Reference))
    {
        // Message utilisateur localisé via Dico.xml.
        throw new UserException("#OrderReferenceRequired");
    }

    return Task.CompletedTask;
}

Recommendations

• On the UI side, wrap handlers in try / catch (Exception ex) and call ShowException(ex).
• On the server side, inherit from LgControllerBase and use Problem(ex) in actions that catch exceptions.
• Use Dico.xml keys (#...) for messages displayed to the user.
• Do not manually display exceptions filtered by Lagoon, in particular LgValidationException and TaskCanceledException.