Gestion des exceptions

Lagoon fournit un pattern homogène pour afficher les erreurs côté Blazor WebAssembly et pour renvoyer les erreurs côté serveur.

Côté UI : ShowException

Les pages et composants Lagoon héritent de LgComponentBase ou LgPage. Ils disposent de ShowException(ex), qui délègue à l'application Lagoon.

Utilisez ce pattern dans les handlers déclenchés par l'utilisateur :

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) applique les règles du framework :

Cas	Comportement
LgValidationException	Ignorée par ShowException, car gérée par LgEditForm.
TaskCanceledException	Ignorée pour ne pas afficher les annulations normales.
AggregateException	Chaque exception interne est traitée individuellement.
Erreur d'authentification HTTP	Le framework peut déclencher la logique de reconnexion.
Autre exception	L'erreur est tracée, puis un message utilisateur est affiché.

Côté serveur : Problem(ex)

Les contrôleurs applicatifs doivent hériter de LgControllerBase. Pour les actions qui capturent explicitement les exceptions, renvoyez 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) est le point d'entrée standard côté serveur pour laisser Lagoon tracer et transformer l'exception en réponse HTTP cohérente.

Erreurs utilisateur

Les erreurs utilisateur sont destinées à être affichées dans l'interface de l'utilisateur final.

Journalisation

L'ancienne documentation précise que les erreurs utilisateur ne sont pas envoyées vers les journaux applicatifs comme des erreurs techniques classiques.

Exception	Usage
UserException	Erreur métier avec message personnalisable, idéalement localisé.
UnauthorizedException	Erreur d'autorisation prédéfinie.

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;
}

Recommandations

• Côté UI, encapsuler les handlers dans try / catch (Exception ex) et appeler ShowException(ex).
• Côté serveur, hériter de LgControllerBase et utiliser Problem(ex) dans les actions qui capturent les exceptions.
• Utiliser des clés Dico.xml (#...) pour les messages affichés à l'utilisateur.
• Ne pas afficher manuellement les exceptions filtrées par Lagoon, notamment LgValidationException et TaskCanceledException.