MessagePack serialization

Lagoon uses MessagePack to reduce the size of the data exchanged between the Blazor WebAssembly client and the ASP.NET Core server, while keeping the process transparent for the developer.

Actual framework wiring

Side	Verified wiring
Server	LgApplication adds a LagoonMessagePackOutputFormatter to the MVC OutputFormatters.
Format	The MessagePack MIME type is application/x-msgpack.
Options	The framework uses TypelessContractlessStandardResolver with Lz4BlockArray compression, allows assembly version differences, and omits the assembly version.
Client	The Lagoon HTTP extensions deserialize application/x-msgpack with the same options.
Default Accept	ApplicationBehavior.DefaultAcceptHeader is set to DefaultAcceptHeader.MessagePack.

The server formatter does not serialize BadRequest errors as MessagePack: errors remain serialized as JSON.

Transparent usage

In Lagoon HTTP calls, the client requests MessagePack by default and automatically deserializes the response if the server returns application/x-msgpack.

OrdersApiService.cs

public class OrdersApiService
{
    private readonly HttpClient _http;

    public OrdersApiService(HttpClient http)
    {
        _http = http;
    }

    public Task<List<VmOrder>> GetOrdersAsync(CancellationToken cancellationToken)
    {
        // L'extension Lagoon gère la désérialisation JSON ou MessagePack selon la réponse.
        return _http.TryGetAsync<List<VmOrder>>("api/orders", cancellationToken);
    }
}

Optimizing a ViewModel

For large lists or ViewModels with many properties, you can decorate the ViewModel with [MessagePackObject] and each property with [Key(n)]. This avoids repeating the property names in the serialized stream.

VmOrder.cs

using MessagePack;

namespace Demo.Shared.Orders;

[MessagePackObject]
public class VmOrder
{
    [Key(0)]
    public int Id { get; set; }

    [Key(1)]
    public string Reference { get; set; }

    [Key(2)]
    public bool Active { get; set; } = true;

    [Key(3)]
    public List<VmOrderLine> Lines { get; set; }
}

Maintaining keys

The Key indexes must be unique within the class. The technical order does not matter, but keeping the properties in order makes maintenance easier.

Reverting to JSON for debugging

The client behavior exposes DefaultAcceptHeader. To simplify network inspection in the browser, an application can request JSON instead of MessagePack.

Main.cs

protected override void OnConfigureBehavior(ApplicationBehavior behavior)
{
    base.OnConfigureBehavior(behavior);

    // Demande des réponses JSON pour faciliter le debug réseau côté navigateur.
    behavior.DefaultAcceptHeader = DefaultAcceptHeader.Json;
}

Points to note

• MessagePack is the default exchange format in Lagoon.
• Server actions don't need to explicitly choose MessagePack: the MVC formatter handles it based on the Accept header.
• The Lagoon HTTP extensions can read both JSON and MessagePack.
• For exports handled by [Queryable], the framework avoids re-encoding binary content as JSON or MessagePack when the response must be a file.