diff --git a/doc/Learn/Mvux/Advanced/Messaging.md b/doc/Learn/Mvux/Advanced/Messaging.md index 5b24fa7f01..ce47ae3e6c 100644 --- a/doc/Learn/Mvux/Advanced/Messaging.md +++ b/doc/Learn/Mvux/Advanced/Messaging.md @@ -295,6 +295,80 @@ The `SelectedPersonPhone` state will only be refreshed if it meets the predicate This overload is the same as the previous one, except it watches a single-item state rather than a `ListState`, as in the last example. +#### Fluent API Observe overloads + +These extension methods are available for both `IState` and `IListState` objects. + +- `IState Observe(this IState state, IMessenger messenger, Func keySelector)` + + This overload is a fluent API extension method that can be used to observe entity-change messages from the messenger for a specific entity type and apply them to the state. It returns the state itself, so it can be chained with other methods. + + ```csharp + public partial record MyModel + { + protected IUserService UserService { get; } + + public MyModel(IUserService userService, IMessenger messenger) + { + UserService = userService; + + CurrentUser + .Observe(messenger, user => user.Id) + .Observe(messenger, user => user.Name); + } + + public IState CurrentUser => State.Async(this, UserService.GetCurrentUser); + } + ``` + + or in a more Fluent API way: + + ```csharp + public partial record MyModel(IUserService UserService, IMessenger Messenger) + { + public IState CurrentUser => State.Async(this, UserService.GetCurrentUser) + .Observe(Messenger, user => user.Id) + .Observe(Messenger, user => user.Name); + } + ``` + + > [!NOTE] + > Please note that in this example we are using C# Primary Constructors, which is a feature available in C# 9.0. + +- `IState Observe(this IState state, IMessenger messenger, Func keySelector, out IDisposable disposable)` + + This overload is the same as the previous one, except it returns an `IDisposable`, which can be used to dispose of the subscription. When disposed, the state will stop observing further entity-change messages from the messenger. + + ```csharp + public partial record MyModel + { + protected IUserService UserService { get; } + private IDisposable subscriptions; + + public MyModel(IUserService userService, IMessenger messenger) + { + UserService = userService; + + CurrentUser + .Observe(messenger, user => user.Id, out subscriptions); + } + + public IState CurrentUser => State.Async(this, UserService.GetCurrentUser); + + // Call this method to cancel the subscription + private void CancelSubscriptions() + { + subscriptions.Dispose(); + } + } + ``` + +Two more overload extensions are available for `IListState`, and they behave the same as the `IState` overloads. + +- `IListState Observe(this IListState listState, IMessenger messenger, Func keySelector, out IDisposable disposable)` + +- `IListState Observe(this IListState listState, IMessenger messenger, Func keySelector)` + ### Update The MVUX messaging package also includes a pair of `Update` methods that enable updating an `IState` or an `IListState` from an `EntityMessage`.