DEV Community: Eric King

Fun with C# and Bingo

Eric King — Sat, 03 Dec 2022 00:16:11 +0000

This post is part of the C# Advent 2022 event. Please visit https://www.csadvent.christmas/ for more C# fun!

I was recently considering what it would take to make a Bingo game engine in C#. Bingo is a relatively simple game with relatively simple rules, but as is usually the case, the perceived simplicity can be deceiving once you delve into the details.

When I looked online for inspiration, I wasn't satisfied with what I found. Very few examples used much more than the most basic C# language features, and so were missing out on some possibilities for making the code a bit more readable and expressive.

I decided I would use this as a learning opportunity for myself, to see if I could do better. This post is for me to share some of what I learned.

If you would like to follow along with the source code, it can be found on GitHub at https://github.com/eric-king/BingoEngine

So firstly, let's review: What is Bingo exactly? As wikipedia puts it, (American) Bingo is

a game of chance in which each player matches the numbers printed in different arrangements on cards.

A Bingo card is defined as:

A typical Bingo game utilizes the numbers 1 through 75. The five columns of the card are labeled 'B', 'I', 'N', 'G', and 'O' from left to right. The center space is usually marked "Free" or "Free Space", and is considered automatically filled. The range of printed numbers that can appear on the card is normally restricted by column, with the 'B' column only containing numbers between 1 and 15 inclusive, the 'I' column containing only 16 through 30, 'N' containing 31 through 45, 'G' containing 46 through 60, and 'O' containing 61 through 75.

Interestingly, I've not seen any Bingo code where those parameters are explicitly laid out in an easily readable format. Most of what I found had all the pieces embedded in various loops, and to recreate the rules as laid out above, a programmer would basically have to mentally debug the program.

I want to have that basic set of parameters in an easily glanceable block of code. Here's what I came up with:


 csharp
var columnParams = new Dictionary<string, (int MinCellValue, int MaxCellValue)>
{
    { "B", (01,15) },
    { "I", (16,30) },
    { "N", (31,45) },
    { "G", (46,60) },
    { "O", (61,75) }
};

The string represents the label of the column that the rule applies to, and the (int, int) tuple (a C# 7.0 feature) represents the min and max values for that column. Anybody should be able to glance at that set of parameters and verify that it matches the paragraph above.

Generating a Bingo Board

We can use that set of parameters to build a standard Bingo layout, which is basically a two-dimensional string array string[,]. We can start by using the column rules above to generate the random column values.

Defined elsewhere are the column labels


 csharp
public string[] ColumnLabels { get; } = new [] { "B", "I", "N", "G", "O" };

and the standard row and column counts for a Bingo board.


 csharp
public const int STANDARD_COL_COUNT = 5;
public const int STANDARD_ROW_COUNT = 5;

Numbers can't be repeated in the Bingo board, so the algorithm should ensure that it only adds random numbers to the column if the column doesn't already contain that number. Here's the entire column-generating algorithm:


 csharp
private string[,] GenerateStandardBingoColumns()
{
    var columns = new string[Constants.STANDARD_COL_COUNT, Constants.STANDARD_ROW_COUNT];

    // The valid cell values are numbers between 1-75,
    // based on these column parameters
    var columnParams = new Dictionary<string, (int MinCellValue, int MaxCellValue)>
    {
        { "B", (01,15) },
        { "I", (16,30) },
        { "N", (31,45) },
        { "G", (46,60) },
        { "O", (61,75) }
    };

    var random = new Random();
    foreach (var columnParam in columnParams)
    {
        // make sure we're working with the correct column,
        // based on the column label
        var colIndex = Array.IndexOf(ColumnLabels, columnParam.Key);

        // cell values can't repeat, so we need to keep track
        // of the previously generated values in this column
        var previouslyGeneratedValues = new List<int>();

        // calculate each cells distinct value based on the column's
        // designated value bucket as described above
        for (int rowIndex = 0; rowIndex < Constants.STANDARD_ROW_COUNT; rowIndex++)
        {
            int cellValue = GenerateDistinctRandomInRange(random, columnParam.Value, previouslyGeneratedValues);
            columns[colIndex, rowIndex] = cellValue.ToString();
            previouslyGeneratedValues.Add(cellValue);
        }
    }

    return columns;
}

Nice and understandable, at a glance.

The distinct random number function looks like this:


 csharp
private static int GenerateDistinctRandomInRange(Random random, (int minValue, int maxValue) range, List<int> previouslyGeneratedValues)
{
    int newValue;
    do
    {
        newValue = random.Next(range.minValue, range.maxValue + 1);
    }
    // try again if we've already got that value
    while (previouslyGeneratedValues.Any(previousValue => newValue == previousValue));

    return newValue;
}

By using the same (int, int) tuple for the value range as before, it makes it very easy to use the columnParam.Value directly. Also, something tells me we may be able to re-use this function later, when drawing random Bingo numbers. 🙂

So far, so good, we can generate a grid of numbers following the standard Bingo column rules. But how do we handle win conditions?

Win Conditions

For a standard Bingo game,

A player wins by completing a row, column, or diagonal. The center space is usually marked "Free" or "Free Space", and is considered automatically filled.

This means that there are 12 distinct "patterns" that a grid can form that result in a standard win condition. Each of the 5 columns, each of the 5 rows, and the 2 diagonals from corner to corner. Some examples of how we can visualize them are:

The entire "B" column
■□□□□
■□□□□
■□□□□
■□□□□
■□□□□

The entire 4th row
□□□□□
□□□□□
□□□□□
■■■■■
□□□□□

Diagonal top-left to bottom-right (the center square is not needed as it is "Free")
■□□□□
□■□□□
□□□□□
□□□■□
□□□□■

But beyond the "standard" game, there are other possibilities:

In addition to a straight line, other patterns may be considered a valid bingo in special games. For example, a 2×2 square of marked squares in the upper-right-hand corner could be considered a "postage stamp". Another common special game requires players to cover the four corners. There are several other patterns, such as a Roving 'L', which requires players to cover all B's and top or bottom row or all O's and top or bottom row. Another common pattern is a blackout, covering all 24 numbers and the free space.

We may visualize those patterns like so:

Postage Stamp
□□□■■
□□□■■
□□□□□
□□□□□
□□□□□

Four Corners
■□□□■
□□□□□
□□□□□
□□□□□
■□□□■

For our code, it makes sense to create a BingoPattern class that contains a list of WinConditions. Some patterns may only have one win condition, but others (like the "standard" pattern) may have many. A WinCondition will consist of a list of Cells, each of which define a location (column, row) in the grid that's required so satisfy the win condition. We should also define a Name for the Pattern, and also for each Wincondition.

The approach I took is to create an interface to define the basic structure of a BingoPattern.


 csharp
public interface IBingoPattern
{
    string PatternName { get; }
    List<WinCondition> WinConditions { get; init; }
}

Note the use of an init only setter, a feature added with C# 9.0, for WinConditions.

I want each Pattern implementation to contain a default empty constructor which initializes the WinCondition list, so I'm enforcing that by providing an abstract base class that looks like this:


 csharp
public abstract class BasePattern : IBingoPattern
{
    public abstract string PatternName { get; }
    public List<WinCondition> WinConditions { get; init; }

    public BasePattern()
    {
        WinConditions = BuildWinConditions();
    }

    protected abstract List<WinCondition> BuildWinConditions();
}

Which means that I can create a class for each type of Pattern that I want to implement, and all each class needs to do is provide a name and a list of win conditions:


 csharp
public class StandardPattern : BasePattern
{
    public override string PatternName => "Standard Bingo";

    protected override List<WinCondition> BuildWinConditions()
    {
        return new List<WinCondition>
        {
           // but what goes here?
        };
    }
}

Now we have to define the win conditions. The challenge, however, is how can we do it in as human-readable yet programmatically correct way as we can? Here's a challenge for you:

Which of the following coordinates (column, row) represent the "Four Corners" pattern? Which the "Postage Stamp" pattern?

(0,0), (0,4), (4,0), (4,4)
(0,3), (0,4), (1,3), (1,4)
(0,0), (1,1), (3,3), (4,4)

Admittedly that's not that hard to figure out, but I bet you still had to "step through" the coordinates and map them to a mental model of the Bingo board's grid before you were sure.

On the other hand, what if we could use those "pictograms" I provided as examples above? How fast can you recognize the patterns then?

1.
□□□■■
□□□■■
□□□□□
□□□□□
□□□□□

2.
■□□□■
□□□□□
□□□□□
□□□□□
■□□□■

3.
■□□□□
□■□□□
□□□□□
□□□■□
□□□□■

My guess is that your recognition of the patterns was near instant, and that any deviation from the expected is also nearly instantly recognizable. I want my code to have those characteristics where possible. So, let's do it.

C# 11.0 introduces a feature called raw string literals which we can make use of here.

With a raw string literal, I can imagine WinCondition constructor that looks like this:


 csharp
new WinCondition("Entire B column",
"""
■□□□□
■□□□□
■□□□□
■□□□□
■□□□□
""");

How good does that look? To implement that, we just have to do some basic string parsing. First, I define a PatternCell to hold the Column and Row of each spot on the grid that represents a part of the win condition. I do so using a record type, introduced as a feature of C# 9.0.


 csharp
public record PatternCell(int ColIndex, int RowIndex);

I've also defined as constants the values of the "dark square" and "light square" characters I'm using to create the pictograms.


 csharp
public const char DARK_SQUARE = '\u25a0';
public const char LIGHT_SQUARE = '\u25a1';

And so now our WinCondition class can be defined as follows, where it receives the pictogram as a constructor parameter, splits it into individual lines, and then parses though the lines to find any character in the row that is a dark square. When it finds one, it registers that row/col as a PatternCell in the WinCondition.


 csharp
public class WinCondition 
{
    public PatternCell[] Cells { get; init; }
    public string Description { get; init; }

    public WinCondition(string description, string pictogram)
    {
        Cells = BuildPatternCells(pictogram);
        Description = description;
    }


    private static PatternCell[] BuildPatternCells(string pictogram)
    {
        List<PatternCell> patternCells = new();
        var rows = pictogram.Split(Environment.NewLine);
        for (int rowIndex = 0; rowIndex < Constants.STANDARD_ROW_COUNT; rowIndex++)
        {
            for (int colIndex = 0; colIndex < Constants.STANDARD_COL_COUNT; colIndex++)
            {
                if (rows[rowIndex][colIndex] == Constants.DARK_SQUARE)
                {
                    patternCells.Add(new PatternCell(colIndex, rowIndex));
                }
            }
        }
        return patternCells.ToArray();
    }
}

This allows us to create a new Pattern with a class as simple as


 csharp
public class PostageStampPattern : BasePattern
{
    public override string PatternName => "Postage Stamp";

    protected override List<WinCondition> BuildWinConditions()
    {
        return new List<WinCondition>
        {
            new WinCondition("4 cells at the top right corner",
            """
            □□□■■
            □□□■■
            □□□□□
            □□□□□
            □□□□□
            """),
        };
    }
}

or as complicated as


 csharp
public class StandardPattern : BasePattern
{
    public override string PatternName => "Standard Bingo";

    protected override List<WinCondition> BuildWinConditions()
    {
        return new List<WinCondition>
        {
            new WinCondition("Entire B column",
            """
            ■□□□□
            ■□□□□
            ■□□□□
            ■□□□□
            ■□□□□
            """),

            new WinCondition("Entire I column",
            """
            □■□□□
            □■□□□
            □■□□□
            □■□□□
            □■□□□
            """),

            new WinCondition("Entire N column",
            """
            □□■□□
            □□■□□
            □□□□□
            □□■□□
            □□■□□
            """),

            new WinCondition("Entire G column",
            """
            □□□■□
            □□□■□
            □□□■□
            □□□■□
            □□□■□
            """),

            new WinCondition("Entire O column",
            """
            □□□□■
            □□□□■
            □□□□■
            □□□□■
            □□□□■
            """),

            new WinCondition("Entire first row",
            """
            ■■■■■
            □□□□□
            □□□□□
            □□□□□
            □□□□□
            """),

            new WinCondition("Entire second row",
            """
            □□□□□
            ■■■■■
            □□□□□
            □□□□□
            □□□□□
            """),

            new WinCondition("Entire third row",
            """
            □□□□□
            □□□□□
            ■■□■■
            □□□□□
            □□□□□
            """),

            new WinCondition("Entire fourth row",
            """
            □□□□□
            □□□□□
            □□□□□
            ■■■■■
            □□□□□
            """),

            new WinCondition("Entire fifth row",
            """
            □□□□□
            □□□□□
            □□□□□
            □□□□□
            ■■■■■
            """),

            new WinCondition("Diagonal top left to bottom right",
            """
            ■□□□□
            □■□□□
            □□□□□
            □□□■□
            □□□□■
            """),

            new WinCondition("Diagonal top right to bottom left",
            """
            □□□□■
            □□□■□
            □□□□□
            □■□□□
            ■□□□□
            """)
        };
    }
}

To round things off, the WinCondition should be able to convert itself back into a pictogram, for places where we want to graphically display it.


 csharp
public string ToPictogram() 
{
    StringBuilder stringBuilder = new();
    for (int rowIndex = 0; rowIndex < Constants.STANDARD_ROW_COUNT; rowIndex++)
    {
        for (int colIndex = 0; colIndex < Constants.STANDARD_COL_COUNT; colIndex++)
        {
            PatternCell cellToCheck = new(colIndex, rowIndex);
            bool isPartOfWinCondition = Cells.Any(cell => cell == cellToCheck);
            stringBuilder.Append(isPartOfWinCondition ? Constants.DARK_SQUARE : Constants.LIGHT_SQUARE);
        }
        stringBuilder.AppendLine();
    }

    return stringBuilder.ToString().TrimEnd();
}

The check here


 csharp
PatternCell cellToCheck = new(colIndex, rowIndex);
bool isPartOfWinCondition = Cells.Any(cell => cell == cellToCheck);

works because PatternCell is a record type, which provides value equality for free! And also note the syntax of PatternCell cellToCheck = new(colIndex, rowIndex); and StringBuilder stringBuilder = new(); which both use the C# 9.0 feature target-typed new expression instead of var.

So now we have a way to generate random Bingo boards, and we have a library of Patterns we can apply as win conditions. But how to we know when a Bingo board is a winner?

Judging a Bingo Board

The challenge: A typical Bingo game will probably have the players with their Boards in a different place as the Number Caller for a particular game. This means I'd like to be able to represent a particular board's configuration by some serializable code that can be easily transferred from one system to another.

There are 552,446,474,061,128,648,601,600,000 possible "standard" Bingo card configurations based on the rules we are using, so indexing each of them with a unique pre-determined code is out of the question. 🙂 So I'm going to take advantage of a library called Hashids to generate a code that's a combination of a Standard Bingo board's 25 "cells" and a code that represents a particular game "session".

The idea here isn't cryptographic security, but instead just a controlled way to encode a bingo board configuration in the context of a game session so it can be easily shared with a "Judge", which can then reconstitute the game board from the code and check it against the current game's win conditions and the numbers that have been called so far.

Using the Hashids library, we can take the Board's Grid (what I'm calling the collection of all of the board's cells) values, combine them with a string that represents a game session (it could be anything, like "BobsGame20221211") and generate a single string representation that I'm calling the BoardCode.

The implementation is simple.


 csharp
private string BuildBoardCode(string sessionCode)
{
    int[] gridValues = Grid.SelectMany(row => row.Cells.Select(cell => int.Parse(cell.Value))).ToArray();
    Hashids hashids = new(sessionCode);
    string boardCode = hashids.Encode(gridValues);
    return boardCode;
}

Using this function, a board with a sessionCode of "Test" and a Grid that looks like



13      17      43      59      73
2       20      35      47      71
5       23      39      57      62
8       24      45      55      72
4       29      42      54      65

will generate a BoardCode of "l6TlfeUwXfr4fEsQibcZbHnrU4HGFxIebUNKiLCYtrrf89TXKsoujUzhjeSpE"

And the grid values can be decoded from a sessionCode and a boardCode similarly:


 csharp
Hashids hashids = new(sessionCode);
int[] gridValues = hashids.Decode(boardCode);

This will give us the 25 cell values in order, which we can loop through and use to recreate the rows and columns of the board.

That gives us all we need to create a StandardBoardJudge class which can determine whether a particular Board meets any of the win conditions of the given Bingo Pattern. As a matter of fact, the code is relatively simple.


 csharp
public static class StandardBoardJudge
{
    public static WinCondition? Evaluate(string sessionCode, string boardCode, IBingoPattern pattern, int[] numbersCalled)
    {
        // reconstitute the board with all of its values based on the board code 
        StandardBoard board = new(sessionCode, boardCode);

        // boards may match more than one win condition
        // but we only need the first one
        return pattern.WinConditions.FirstOrDefault(condition =>
        {
            // if ALL of the cells in the win condition had their
            // number called, then we have a winner
            return condition.Cells.All(cell =>
            {
                // get the value of the win condition cell in the board
                string boardCellValue = board.Grid[cell.RowIndex].Cells[cell.ColIndex].Value;

                // check to see if it was called
                return numbersCalled.Contains(int.Parse(boardCellValue));
            });
        });
    }
}

This code finds the first WinCondition where every cell in the win condition is found in numbers called and returns that win condition. If no win condition is fulfilled, the function returns null.

Putting it all together

So now we have all the pieces we need to build a game from our simple "Bingo Engine".

By defining a IBingoPattern interface, we've given ourselves a way to dynamically build a list of all of the patterns available for use. By using a BasePattern to ensure that each Pattern has a default empty constructor, we can easily instantiate one of each, complete with win conditions.

We can do so with a little bit of reflection:


 csharp
IBingoPattern[] GetPatterns()
{
    // dynamically parse all of the classes that implement 
    // the IBingoPattern interface
    var patternInterface = typeof(IBingoPattern);
    var assembly = Assembly.GetAssembly(patternInterface);

    // this shouldn't ever be null, but handled anyway
    if (assembly == null)
    {
        return Array.Empty<IBingoPattern>();
    }

    // exclude the BasePattern, which is an abstract class and cannot be instantiated
    Type[] types = assembly.GetTypes()
        .Where(x => x.GetInterfaces().Contains(patternInterface))
        .Where(x => !x.IsAbstract)
        .ToArray();

    var patterns = types.Select(x => Activator.CreateInstance(x) as IBingoPattern ?? new StandardPattern());

    return patterns.ToArray();
}

This means our system conforms (in a way) to the Open-Closed Principal, in that we can introduce new Patterns into the system merely by creating new classes that implement the IBingoPattern, and we don't have to touch any other part of the engine for it to work.

Included in the source code for this article is a simple Console application that begins to use the game engine to run a game of Bingo. It's not a full-blown Bingo game with multiple Players and multiple Boards per player, but it gives a starting point.

I hope you've learned a few things here, and perhaps turning this into full-blown game can be another series of posts, if you don't beat me to it!

Advanced Blazor State Management Using Fluxor, part 7 - Client-to-Client comms with SignalR

Eric King — Sat, 08 May 2021 23:14:36 +0000

This is the seventh in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

Client-to-Client Communication

Consider a scenario where you want the state of your application in one user's browser client to affect the state of your application in another user's browser client. Perhaps you have a component that updates in real-time based on the activities of other users. Or maybe you want to notify a user that the record they are edited was just saved by another user, and they should refresh their data before continuing.

So far in this series everything we've done has dealt with the state of individual components, or with components sharing state with other components in the same browser instance. Actions can affect the state of other components in the same browser instance, and Effects can interact with a server or external API, but still each browser instance is independent and unaware of any other browser instances running the same application.

In order to accommodate the client-to-client scenario, we'll have to incorporate some other tool that allows the server to push messages to all of the clients that have the application loaded.

Enter SignalR

As with most challenges, there are undoubtedly many ways to accomplish this. One of the simplest would be to incorporate ASP.NET Core SignalR into our Blazor Wasm client and server projects.

ASP.NET Core SignalR is a library for ASP.NET Core developers that makes it incredibly simple to add real-time web functionality to your applications. What is "real-time web" functionality? It's the ability to have your server-side code push content to the connected clients as it happens, in real-time.

There is a handy tutorial for incorporating SignalR into a Blazor WebAssembly application in the official documentation here. I encourage you to at least glance through it before continuing here, because the rest of this post is going to assume at least a basic familiarity with SignalR and configuration.

For this post, I want to take it a few steps further by incorporating it into the Fluxor Store setup we've been building.

Broadcasting the Counter state

I will be adding a button to the Counter screen that, when clicked, will broadcast the counter's current value to all of the other clients. I'm triggering this with an explicit button click just for demonstration convenience; it could just as easily be triggered automatically by subscribing to an Action as we did with the Weather Forecast updates in Part 4 of this series.

This "Broadcast" button will be disabled if the client loses connectivity to the server, and toast notifications will be used to indicate when broadcasted Counter values are received, similar to the previous few posts in the series.

The CounterHub

The SignalR component that manages the connections and messaging on the server is called a Hub. So our first step is creating a Hub in our BlazorWithFluxor.Server project, which I am calling CounterHub. I first create a folder at the root of the project called Hubs, and add file named CounterHub.cs that contains the following class:

using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

namespace BlazorWithFluxor.Server.Hubs
{
    public class CounterHub : Hub
    {
        public async Task SendCount(int count)
        {
            await Clients.Others.SendAsync("ReceiveCount", count);
        }
    }
}

This class derives from Microsoft.AspNetCore.SignalR.Hub and contains one method SendCount that clients will use to send a count value, and the method broadcasts the value to all of the other clients via Clients.Others.SendAsync("ReceiveCount", count). The first parameter of "ReceiveCount" represents the name of the message that clients will be listening for.

To activate the CounterHub, we need to call AddSignalR in the ConfigureServices method of Startup.cs, along with adding response compression like so:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR();
    services.AddControllersWithViews();
    services.AddRazorPages();

    services.AddResponseCompression(opts =>
    {
        opts.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(
            new[] { "application/octet-stream" });
    });
}

The final piece for Startup.cs is to add an endpoint for the CounterHub in the UseEndpoints block:

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapControllers();
    endpoints.MapHub<CounterHub>("/counterhub");
    endpoints.MapFallbackToFile("index.html");
});

And with that we have a working SignalR hub on the server.

The CounterHubStore

For the BlazorWithFluxor.Client project, we begin by referencing the Microsoft.AspNetCore.SignalR.Client NuGet package.

Install-Package Microsoft.AspNetCore.SignalR.Client

Next we'll create a Fluxor store for the CounterHub, which I will place in a \Features\Hubs folder.

The CounterHubState will only need to keep track of whether or not it's connected to the server, which we'll use to enable/disable the Broadcast button. Since the client's HubConnection must reach out and communicate with the server's Hub, we will hold the HubConnection in the CounterHubEffects class. We will use an EffectMethod to configure the HubConnection and to communicate with the server Hub. With a handful of Actions to handle all of the interaction, our CounterHubStore looks like this:

using Fluxor;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.SignalR.Client;
using System;
using System.Threading.Tasks;

namespace BlazorWithFluxor.Client.Features.Hubs.CounterHub
{
    public record CounterHubState
    {
        public bool Connected { get; init; }
    };

    public class CounterHubFeature : Feature<CounterHubState>
    {
        public override string GetName() => "CounterHub";

        protected override CounterHubState GetInitialState()
        {
            return new CounterHubState 
            {
                Connected = false
            };
        }
    }

    public static class CounterHubReducers 
    {
        [ReducerMethod]
        public static CounterHubState OnSetConnected(CounterHubState state, CounterHubSetConnectedAction action) 
        {
            return state with
            {
                Connected = action.Connected
            };
        }
    }

    public class CounterHubEffects
    {
        private readonly HubConnection _hubConnection;

        public CounterHubEffects(NavigationManager navigationManager)
        {
            _hubConnection = new HubConnectionBuilder()
                .WithUrl(navigationManager.ToAbsoluteUri("/counterhub"))
                .WithAutomaticReconnect()
                .Build();
        }

        [EffectMethod]
        public async Task SendCount(CounterHubSendCountAction action, IDispatcher dispatcher)
        {
            try
            {
                if (_hubConnection.State == HubConnectionState.Connected)
                {
                    await _hubConnection.SendAsync("SendCount", action.Count);
                }
                else 
                {
                    dispatcher.Dispatch(new CounterHubSendCountFailedAction("Not connected to hub."));
                }
            }
            catch (Exception ex)
            {
                dispatcher.Dispatch(new CounterHubSendCountFailedAction(ex.Message));
            }
        }

        [EffectMethod(typeof(CounterHubStartAction))]
        public async Task Start(IDispatcher dispatcher) 
        {
            await _hubConnection.StartAsync();

            _hubConnection.Reconnecting += (ex) => 
            {
                dispatcher.Dispatch(new CounterHubSetConnectedAction(false));
                return Task.CompletedTask;
            };

            _hubConnection.Reconnected += (connectionId) =>
            {
                dispatcher.Dispatch(new CounterHubSetConnectedAction(true));
                return Task.CompletedTask;
            };

            _hubConnection.On<int>("ReceiveCount", (count) => dispatcher.Dispatch(new CounterHubReceiveCountAction(count)));

            dispatcher.Dispatch(new CounterHubSetConnectedAction(true));
        }
    }

    public record CounterHubSetConnectedAction(bool Connected);
    public record CounterHubStartAction();
    public record CounterHubReceiveCountAction(int Count);
    public record CounterHubSendCountAction(int Count);
    public record CounterHubSendCountFailedAction(string Message);

}

Note that the server Hub is notified via an EffectMethod that handles the CounterHubSendCountAction Action, and the ReceiveCount server notification dispatches a CounterHubReceiveCountAction Action on the client. Fully incorporated into the flux pattern.

I dispatch the CounterHubStartAction in the MainLayout.razor file, to connect to the server once the client is ready:

@code { 
    protected override void OnInitialized()
    {
        base.OnInitialized();
        Dispatcher.Dispatch(new CounterHubStartAction());
    }
}

I subscribe to a few new Actions in the Toaster.razor component:

protected override void OnInitialized()
{
    ...

    SubscribeToAction<CounterHubReceiveCountAction>(ShowCountReceivedToast);
    SubscribeToAction<CounterHubSendCountFailedAction>(ShowCountReceivedFailedToast);
    SubscribeToAction<CounterHubSetConnectedAction>(ShowHubConnectedToast);

    base.OnInitialized();
}

and

private void ShowCountReceivedToast(CounterHubReceiveCountAction action)
{
    toastService.ShowInfo($"Count received: {action.Count}");
}

private void ShowCountReceivedFailedToast(CounterHubSendCountFailedAction action)
{
    toastService.ShowError($"Count could not be broadcast: {action.Message}");
}

private void ShowHubConnectedToast(CounterHubSetConnectedAction action)
{
    if (action.Connected)
    {
        toastService.ShowSuccess($"CounterHub connected!");
    }
    else 
    {
        toastService.ShowError($"CounterHub disconnected!");
    }
}

And finally I add the Broadcast button in the Counter.razor component:

<button class="btn btn-outline-warning" 
        @onclick="SendCount" 
        disabled="@(!CounterHubState.Value.Connected)">
    Broadcast
</button>

and dispatch the Current Count when the button is clicked:

private void SendCount()
{
    Dispatcher.Dispatch(new CounterHubSendCountAction(CounterState.Value.CurrentCount));
}

With that complete, we can run our client in multiple browser windows to see the cross-client magic happen. For this example I used Firefox as one client and Chrome as the other, both connected to the same instance of the Server application.

If the persistent connection to the server hub is lost (in this example, I stopped the server host application), the CounterHubStore will react appropriately, disabling the Broadcast button and notifying the user.

Using the default WithAutomaticReconnect configuration, the clients will attempt to reconnect, and will re-enable the Broadcast button if successful.

This is what it looks like with multiple clients running at once:

One additional thing to note about SignalR is that you don't have to host the server Hub yourself if you don't want to. You could easily create a client-only Blazor WebAssembly serverless application and use Microsoft's Azure-based SignalR service to host the Hub in a massively scalable environment.

Please leave a comment if you have a question or suggestion. I'd love to hear from you if you found this useful.

In the meantime, happy coding!

Advanced Blazor State Management Using Fluxor, part 6 - Persisting State

Eric King — Sun, 14 Mar 2021 20:58:39 +0000

This is the sixth in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

Persisting State

In a comment on the previous post in this series, a reader observes that when the application is reloaded, the application state is lost. They then ask how to go about saving the application state so that it remains even after the page is reloaded.

There are undoubtedly many ways to accomplish this; In this post I'll demonstrate one technique.

I'll be using the browser's localStorage API as the mechanism for storing the state of the Counter and the Weather features, but this could work just as well using the IndexedDB API or even calling off to some web API endpoint to save and retrieve state in a database.

To begin, let's note that the localStorage API is a JavaScript API, and isn't directly available to be called by our Blazor code. We need to either write our own JSInterop code to interact with localStorage, or we can take advantage of a library somebody else has already written. I'm going to use the excellent Blazored.LocalStorage.

To install it into our Client project, we start with the NuGet package:



Install-Package Blazored.LocalStorage

And configure it in the Program.cs file:



using Blazored.LocalStorage;

...

builder.Services.AddBlazoredLocalStorage(config => 
{
    config.JsonSerializerOptions.WriteIndented = true;
});

Let's start by saving the CounterState to localStorage.

To do so, I want to have an EffectMethod that subscribes to an Action instructing it to store the State, and which then Dispatches a Success or Failure Action that my application can then respond to.

For the EffectMethod to have access to the Blazored.LocalStorage service, we need to inject it into the CounterEffects class. We should also define a unique string to act as the localStorage key for the CounterState.



private readonly ILocalStorageService _localStorageService;
private const string CounterStatePersistenceName = "BlazorWithFluxor_CounterState";

public CounterEffects(ILocalStorageService localStorageService)
{
    _localStorageService = localStorageService;
}

Now I can add an EffectMethod that can be handed a CounterState for the localStorageService to persist. The service will handle serializing the State for us.



[EffectMethod]
public async Task PersistState(CounterPersistStateAction action, IDispatcher dispatcher) 
{
    try
    {
        await _localStorageService.SetItemAsync(CounterStatePersistenceName, action.CounterState);
        dispatcher.Dispatch(new CounterPersistStateSuccessAction());
    }
    catch (Exception ex) 
    {
        dispatcher.Dispatch(new CounterPersistStateFailureAction(ex.Message));
    }
}

This means we need 3 new actions:



public class CounterPersistStateAction
{
    public CounterState CounterState { get; }
    public CounterPersistStateAction(CounterState counterState)
    {
        CounterState = counterState;
    }
}
public class CounterPersistStateSuccessAction { }
public class CounterPersistStateFailureAction
{
    public string ErrorMessage { get; }
    public CounterPersistStateFailureAction(string errorMessage)
    {
        ErrorMessage = errorMessage;
    }
}

We can then repeat the process for Loading the state, and for completeness we may also want to Clear the State.



[EffectMethod(typeof(CounterLoadStateAction))]
public async Task LoadState(IDispatcher dispatcher)
{
    try
    {
        var counterState = await _localStorageService.GetItemAsync<CounterState>(CounterStatePersistenceName);
        if (counterState is not null) 
        {
            dispatcher.Dispatch(new CounterSetStateAction(counterState));
            dispatcher.Dispatch(new CounterLoadStateSuccessAction());
        }
    }
    catch (Exception ex)
    {
        dispatcher.Dispatch(new CounterLoadStateFailureAction(ex.Message));
    }
}

[EffectMethod(typeof(CounterClearStateAction))]
public async Task ClearState(IDispatcher dispatcher)
{
    try
    {
        await _localStorageService.RemoveItemAsync(CounterStatePersistenceName);
        dispatcher.Dispatch(new CounterSetStateAction(new CounterState { CurrentCount = 0 }));
        dispatcher.Dispatch(new CounterClearStateSuccessAction());
    }
    catch (Exception ex)
    {
        dispatcher.Dispatch(new CounterClearStateFailureAction(ex.Message));
    }
}

These EffectMethods need to affect the value of the CounterState, so we need a ReducerMethod to handle the CounterSetStateAction.



[ReducerMethod]
public static CounterState OnCounterSetState(CounterState state, CounterSetStateAction action) 
{
    return action.CounterState;
}

With these in place, we are able to persist and retrieve the CounterState whenever is appropriate for our application by Dispatching the corresponding Actions.

For this scenario, let's assume we want to read and apply the CounterState when the application loads. Let's accomplish this by creating a Razor Component that has the responsibility of retrieving persisted state. we create a component named StateLoader.razor and place in it the following code:



@inherits FluxorComponent

@using BlazorWithFluxor.Client.Features.Counter.Store

@inject IDispatcher Dispatcher

@code {
    protected override void OnAfterRender(bool firstRender)
    {
        base.OnAfterRender(firstRender);

        if (firstRender)
        {
            Dispatcher.Dispatch(new CounterLoadStateAction());
        }
    }
}

And we can now reference this component in the MainLayout.razor file so that it's loaded at application start.



@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <div class="main">
        <div class="top-row px-4">
            <a href="http://blazor.net" target="_blank" class="ml-md-auto">About</a>
        </div>

        <div class="content px-4">
            @Body
        </div>
    </div>
</div>

<BlazoredToasts Position="ToastPosition.TopRight" Timeout="15" />

<StateLoader />

This will load the CounterState from localStorage if it exists. Let's now give the Counter.razor component a way to Save, Load, and Clear the State by adding a few buttons beside the existing Increment button:



<button class="btn btn-primary" @onclick="IncrementCount">Increment</button>
<button class="btn btn-outline-primary" @onclick="SaveCount">Save</button>
<button class="btn btn-outline-info" @onclick="LoadCount">Load</button>
<button class="btn btn-outline-danger" @onclick="ClearCount">Clear</button>

and their click handlers:



private void SaveCount()
{
    Dispatcher.Dispatch(new CounterPersistStateAction(CounterState.Value));
}

private void LoadCount()
{
    Dispatcher.Dispatch(new CounterLoadStateAction());
}

private void ClearCount()
{
    Dispatcher.Dispatch(new CounterClearStateAction());
}

And with that, we're set.

Note: For demonstration purposes I have hooked in the Blazored.Toast component to pop up a Toast message whenever the CounterState is saved or retrieved, as demonstrated in the previous post in this series. For brevity's sake I'm not including that code in this post, but you can find it all in the project's repository on github.

When the Save button is clicked, we can see the CounterState is saved to the browser's Local Storage:

And if the page is reloaded after the state has been saved, the application will load the saved state:

When the Load button is clicked, state is retrieved from storage and the Store's state is replaced with it:

And the Clear button will remove the state from storage and reset the current count:

One thing to note about Local Storage is that it's not secure, and it can be easily and directly manipulated right in the browser's developer tools:

Which means it can be manipulated in a way that results in badly formatted data:

So if you need to persist the state in a secure manner, you'll need to use something other than Local Storage.

If we repeat the same set of actions for the WeatherStore, we can see that Blazored.LocalStorage can handle more complicated objects too, including collections of objects like the Forecasts array.

Please leave a comment if you're enjoying this series or if you have suggestions for more posts.

As always, happy coding!

Advanced Blazor State Management Using Fluxor, part 5 - ASP.NET EditForm Binding

Eric King — Wed, 10 Mar 2021 13:39:17 +0000

This is the fifth in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

EditForm Databinding

So far we've spent a lot of time taking advantage of the unidirectional data flow inherent in the Flux pattern.

But one of the major benefits of using Blazor is being able to take advantage of your C# classes and .NET functionality in the browser as well as on the server.

A specific example is using an AspNetCore EditForm, binding it a Model class, and validating it automatically, both in the browser and on the server.

EditForm, however, is based on two-way databinding to its Model. Binding the form fields directly to a read-only State object would not work.

To illustrate, let's create a UserFeedback feature in our application. Consider the following requirement:

A user can submit a feedback form, with three fields: Email Address, Rating (1 through 10), and a Comment. Upon successful submit, hide the form and display a success message.

It would be tempting to begin by creating a UserFeedbackState record with those properties:



public record UserFeedbackState 
{
    public string EmailAddress { get; init; }
    public int Rating { get; init; }
    public string Comment { get; init; }
}

But it wouldn't take long to realize that the read-only nature of the record with init methods in place of set makes two-way binding to the EditForm impossible.

Instead, we need a traditional model class, where we can take advantage of DataAnnotations. We'll create this model and place it in the Shared project so that it can be referenced by the Blazor front-end and also by the server ApiController:



using System.ComponentModel.DataAnnotations;

namespace BlazorWithFluxor.Shared
{
    public class UserFeedbackModel
    {
        [EmailAddress]
        [Required]
        [Display(Name = "Email Address")]
        public string EmailAddress { get; set; }

        [Required]
        public int Rating { get; set; }

        [MaxLength(100)]
        public string Comment { get; set; }

        public UserFeedbackModel()
        {
            EmailAddress = string.Empty;
            Rating = 1;
            Comment = string.Empty;
        }
    }
}

Back in the Client project, let's put in place the folder structure \Features\UserFeedback with subfolders for \Pages and \Store.

Create a UserFeedbackStore.cs file in the \Store folder, and begin with a UserFeedbackState and its Feature:



public record UserFeedbackState 
{
    public bool Submitting { get; init; }
    public bool Submitted { get; init; }
    public string ErrorMessage { get; init; }
    public UserFeedbackModel Model { get; init; }
}

public class UserFeedbackFeature : Feature<UserFeedbackState>
{
    public override string GetName() => "UserFeedback";

    protected override UserFeedbackState GetInitialState()
    {
        return new UserFeedbackState 
        {
            Submitting = false,
            Submitted = false,
            ErrorMessage = string.Empty,
            Model = new UserFeedbackModel()
        };
    }
}

I've added a few properties to the UserFeedbackState to represent the state of the component: Submitting, Submitted, ErrorMessage. These represent the state of the form, but not the values in the form.

The values in the form will be databound to the Model property, where I'm ~~cheating~~ compromising a bit by using an init-only object but with read/write properties.

Note: I'm certain that this technique isn't strictly adherent to the "immutable state" approach of Flux, since technically some state is being mutated without going through a reducer. But I think this specific and limited situation is an acceptable exception to the rule, given the benefits.

For Actions, we only need a couple:



public class UserFeedbackSubmitSuccessAction { }

public class UserFeedbackSubmitFailureAction 
{
    public string ErrorMessage { get; }
    public UserFeedbackSubmitFailureAction(string errorMessage)
    {
        ErrorMessage = errorMessage;
    }
}

public class UserFeedbackSubmitAction 
{
    public UserFeedbackModel UserFeedbackModel { get; }

    public UserFeedbackSubmitAction(UserFeedbackModel userFeedbackModel)
    {
        UserFeedbackModel = userFeedbackModel;
    }
}

We'll need one Effect for the form submit:



public class UserFeedbackEffects 
{
    private readonly HttpClient _httpClient;
    public UserFeedbackEffects(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    [EffectMethod]
    public async Task SubmitUserFeedback(UserFeedbackSubmitAction action, IDispatcher dispatcher) 
    {
        var response = await _httpClient.PostAsJsonAsync("Feedback", action.UserFeedbackModel);

        if (response.IsSuccessStatusCode)
        {
            dispatcher.Dispatch(new UserFeedbackSubmitSuccessAction());
        }
        else 
        {
            dispatcher.Dispatch(new UserFeedbackSubmitFailureAction(response.ReasonPhrase));
        }            
    }
}

The EffectMethod will accept the Model as part of the action, and use the injected HttpClient to post it to the ApiController we'll soon create. It will dispatch either a Success or Failure action when it's done.

And finally for the store, the ReducerMethods:



public static class UserFeedbackReducers
{
    [ReducerMethod(typeof(UserFeedbackSubmitAction))]
    public static UserFeedbackState OnSubmit(UserFeedbackState state) 
    {
        return state with 
        {
            Submitting = true
        };
    }

    [ReducerMethod(typeof(UserFeedbackSubmitSuccessAction))]
    public static UserFeedbackState OnSubmitSuccess(UserFeedbackState state)
    {
        return state with
        {
            Submitting = false,
            Submitted = true
        };
    }

    [ReducerMethod]
    public static UserFeedbackState OnSubmitFailure(UserFeedbackState state, UserFeedbackSubmitFailureAction action)
    {
        return state with
        {
            Submitting = false,
            ErrorMessage = action.ErrorMessage
        };
    }
}

The ReducerMethods are straight-forward, just keeping track of the few properties that we'll use to decide what to display on the screen.

In the UserFeedback\Pages folder we'll add a Feedback.razor file as the page to hold the form. The EditForm will look like:



<EditForm Model="@model" OnValidSubmit="@HandleValidSubmit">
    <DataAnnotationsValidator />

    <div class="form-group">
        <label for="emailAddress">Email Address</label>
        <InputText class="form-control" id="emailAddress" @bind-Value="model.EmailAddress" />
    </div>

    <div class="form-group">
        <label for="rating">Rating (1-10)</label>
        <InputSelect class="form-control" id="rating" @bind-Value="model.Rating">
            <option>1</option>
            <option>2</option>
            <option>3</option>
            <option>4</option>
            <option>5</option>
            <option>6</option>
            <option>7</option>
            <option>8</option>
            <option>9</option>
            <option>10</option>
        </InputSelect>
    </div>

    <div class="form-group">
        <label for="comment">Comment</label>
        <InputTextArea class="form-control" id="comment" @bind-Value="model.Comment" rows="3"></InputTextArea>
    </div>

    <button class="btn btn-primary" type="submit">Submit</button>
    <ValidationSummary />
</EditForm>

The form has all the AspNetCore goodness: two-way databinding, DataAnnotationsValidator, ValidationSummary, etc. The HandleValidSubmit method will only be invoked once all of the form fields pass all validation.

The entire razor page, including the @code block and all of the code deciding which portions of the screen to display is below:



@page "/feedback"
@inherits FluxorComponent

@using BlazorWithFluxor.Client.Features.UserFeedback.Store

@inject IState<UserFeedbackState> UserFeedbackState
@inject IDispatcher Dispatcher

<h3>User Feedback</h3>

@if (UserFeedbackState.Value.Submitting)
{
    <div>
        Submitting... Please wait.
    </div>
}
else if (UserFeedbackState.Value.Submitted && string.IsNullOrWhiteSpace(UserFeedbackState.Value.ErrorMessage))
{
    <div class="alert alert-success">
        Thank you for sharing!
    </div>
}
else
{
    <EditForm Model="@model" OnValidSubmit="@HandleValidSubmit">
        <DataAnnotationsValidator />

        <div class="form-group">
            <label for="emailAddress">Email Address</label>
            <InputText class="form-control" id="emailAddress" @bind-Value="model.EmailAddress" type="email" />
        </div>

        <div class="form-group">
            <label for="rating">Rating (1-10)</label>
            <InputSelect class="form-control" id="rating" @bind-Value="model.Rating">
                <option>1</option>
                <option>2</option>
                <option>3</option>
                <option>4</option>
                <option>5</option>
                <option>6</option>
                <option>7</option>
                <option>8</option>
                <option>9</option>
                <option>10</option>
            </InputSelect>
        </div>

        <div class="form-group">
            <label for="comment">Comment</label>
            <InputTextArea class="form-control" id="comment" @bind-Value="model.Comment" rows="3"></InputTextArea>
        </div>

        <button class="btn btn-primary" type="submit">Submit</button>
        <ValidationSummary />
    </EditForm>
}

@if (!string.IsNullOrWhiteSpace(UserFeedbackState.Value.ErrorMessage))
{
    <div class="alert alert-danger">
        Error: @UserFeedbackState.Value.ErrorMessage
    </div>
}

@code {
    private UserFeedbackModel model => UserFeedbackState.Value.Model;

    private void HandleValidSubmit()
    {
        Dispatcher.Dispatch(new UserFeedbackSubmitAction(UserFeedbackState.Value.Model));
    }
}

To get to the page we add an item to the NavMenu:



<li class="nav-item px-3">
    <NavLink class="nav-link" href="feedback">
        <span class="oi oi-list-rich" aria-hidden="true"></span> Feedback
    </NavLink>
</li>

And finally, we need a place to POST the form to. Let's create a FeedbackController in the Server project:



using BlazorWithFluxor.Shared;
using Microsoft.AspNetCore.Mvc;
using System;

namespace BlazorWithFluxor.Server.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class FeedbackController : ControllerBase
    {
        [HttpPost]
        public void Post(UserFeedbackModel model)
        {
            var email = model.EmailAddress;
            var rating = model.Rating;
            var comment = model.Comment;

            Console.WriteLine($"Received rating {rating} from {email} with comment '{comment}'");
        }
    }
}

The Post action receives the same UserFeedbackModel class that the EditForm was bound to. We can (and should) re-validate the model here before further processing, but for this example I'm just going to log the contents of the model to the console.

As you can see, all of the built-in features of the EditForm and DataAnnotationsValidator are available, plus the state of the form was maintained by Fluxor when I navigated away from and then back to the form. The best of both worlds.

Happy Coding!

Advanced Blazor State Management Using Fluxor, part 4 - Interactions between Features

Eric King — Sun, 07 Mar 2021 19:20:43 +0000

This is the fourth in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

So far in this series everything we've explored has been limited to stateful interaction within a single Feature and its Store.

But what about interaction between Features? That's possible too, and here's one way to do it.

Imagine a scenario where we want to trigger an action in one Feature based on the state of another Feature. For instance:

Refresh the Weather Forecasts on every 10th Increment of the Counter.

One approach might be to put code in the Counter.razor page that inspects the CounterState and dispatches a WeatherLoadForecastsAction at the appropriate time.



@code {
    private void IncrementCount()
    {
        Dispatcher.Dispatch(new CounterIncrementAction());

        // every tenth increment
        if (CounterState.Value.CurrentCount % 10 == 0)
        {
            Dispatcher.Dispatch(new WeatherLoadForecastsAction());
        }
    }
}

But I don't prefer that approach because it puts application logic for the Weather Feature in the Counter Feature's UI component.

We could change the CounterStore so that the CounterIncrementAction is handled by an Effect rather than a Reducer, so that the Effect can dispatch a WeatherLoadForecastsAction. I don't prefer this approach either, because it complicates the Counter Feature unnecessarily with Weather Feature concerns.

This functionality really belongs in the WeatherStore. The WeatherStore should be able to react to a dispatch of CounterIncrementAction and respond appropriately.

So how would we do that?

Since we can inject dependencies into Effects classes, we can adjust the WeatherEffects class to have the CounterState injected:



private readonly HttpClient Http;
private readonly IState<CounterState> CounterState;

public WeatherEffects(HttpClient http, IState<CounterState> counterState)
{
    Http = http;
    CounterState = counterState;
}

Then we can add an Effect method to handle the dispatched action:



[EffectMethod(typeof(CounterIncrementAction))]
public async Task LoadForecastsOnIncrement(IDispatcher dispatcher) 
{
    // every tenth increment
    if (CounterState.Value.CurrentCount % 10 == 0) 
    {
        dispatcher.Dispatch(new WeatherLoadForecastsAction());
    }
}

This Effect method in turn triggers the LoadForecasts Effect method we created previously (via the WeatherLoadForecastsAction), and the forecasts are updated even though we're not interacting directly with the Weather page in any way.

If we run the app now, it's not apparent when the forecasts are updated unless we're looking at the weather forecasts page. So, let's change the NavMenu so that the Fetch Data menu item is displayed in bold text when the forecasts are loading.

In the NavMenu.razor file add:



@using BlazorWithFluxor.Client.Features.Weather.Store
@inject IState<WeatherState> WeatherState

In the @code block, let's add a variable for the css class:



private string WeatherItemClass => WeatherState.Value.Loading ? "font-weight-bold" : null;

And change the NavMenu label for the weather page to wrap it in a <span> so the css class can be applied:



<span class="@WeatherItemClass">Weather</span>

Now, if we build and run the application, we can see that the Weather nav menu link displays bold while the forecasts are loading:

And that the forecast loading is triggered by every 10th increment of the Counter:

All this using just the functionality provided by Actions, Reducers, and Effects.

IActionSubscriber

Now that we're triggering the updates of the weather forecasts based on activity in other application features, our users have asked for us to provide better notification than just turning a menu link bold. They have handed us this requirement:

When weather forecasts are updated, show a temporary popup message in the top right of the screen informing that the forecasts have been updated.

In this scenario we don't need to update the state of the application, we just need to trigger a notification. In scenarios like this, we can use a Fluxor feature called an IActionSubscriber. This allows a razor component to react to a dispatched Action without having to go through the Store to do it.

We're going to use the IActionSubscriber and Blazored.Toast to accommodate this new feature request.

First, let's install the Blazored.Toast NuGet package:



Install-Package Blazored.Toast

In Program.cs we need to add using Blazored.Toast; and this line:



builder.Services.AddBlazoredToast();

For convenience, we'll add a few using statements to the _Imports.razor file:



@using Blazored.Toast
@using Blazored.Toast.Configuration
@using Blazored.Toast.Services

Add the css reference to the wwwroot\index.html file:



<link href="_content/Blazored.Toast/blazored-toast.min.css" rel="stylesheet" />

And finally we'll configure the Toasts component by adding this to the MainLayout.razor file:



<BlazoredToasts Position="ToastPosition.TopRight" Timeout="3"/>

And with that, we're ready to trigger the Toasts. Since the NavMenu component is always loaded (in this template), I'm going to put the IActionSubscriber and the IToastService in the NavMenu.razor component.

At the top of NavMenu.razor inject the services:



@inject IToastService toastService
@inject IActionSubscriber ActionSubscriber

Add a function in the @code block to show the Toast message:



private void ShowWeatherToast()
{
    toastService.ShowInfo("Weather Forecasts have been updated!");
}

And let's use the ActionSubscriber to subscribe to the WeatherSetForecastsAction and invoke the ShowWeatherToast method:



protected override void OnInitialized()
{
    ActionSubscriber.SubscribeToAction<WeatherSetForecastsAction>(this, (action) => ShowWeatherToast());
    base.OnInitialized();
}

This line of code will tell the Fluxor Dispatcher that any time the WeatherSetForecastsAction is dispatched, invoke the given Action. The first parameter this represents the instance of the NavMenu component, and the second parameter represents an Action ("Action" in the .NET sense, not in the Flux Action sense) to invoke upon dispatch.

We can actually simplify this a little bit if we change the void ShowWeatherToasts() method to void ShowWeatherToasts(WeatherSetForecastsAction action), since that effectively turns it into an Action<WeatherSetForecastsAction>. The simplified version would look like:



protected override void OnInitialized()
{
    ActionSubscriber.SubscribeToAction<WeatherSetForecastsAction>(this, ShowWeatherToast);
    base.OnInitialized();
}

private void ShowWeatherToast(WeatherSetForecastsAction action)
{
    toastService.ShowInfo("Weather Forecasts have been updated!");
}

Since the subscription is created for the instance of the component (the this parameter), it's important to remove the subscription when the instance is disposed. So any time you SubscribeToAction, remember to unsubscribe when it's appropriate. We'll do so in the component's Dispose method:



protected override void Dispose(bool disposing)
{
    ActionSubscriber.UnsubscribeFromAllActions(this);
    base.Dispose(disposing);
}

The NavMenu.razor's @code block should now look like:



@code {
    private bool collapseNavMenu = true;

    private string NavMenuCssClass => collapseNavMenu ? "collapse" : null;
    private string WeatherItemClass => WeatherState.Value.Loading ? "font-weight-bold" : null;

    protected override void OnInitialized()
    {
        ActionSubscriber.SubscribeToAction<WeatherSetForecastsAction>(this, ShowWeatherToast);
        base.OnInitialized();
    }

    protected override void Dispose(bool disposing)
    {
        ActionSubscriber.UnsubscribeFromAllActions(this);
        base.Dispose(disposing);
    }

    private void ShowWeatherToast(WeatherSetForecastsAction action)
    {
        toastService.ShowInfo("Weather Forecasts have been updated!");
    }

    private void ToggleNavMenu()
    {
        collapseNavMenu = !collapseNavMenu;
    }
}

Build, run, and we can see the IActionSubscriber doing its work:

In the next post in the series, we'll tackle the challenge of meshing the read-only nature of State in Flux with the two-way data binding of razor EditForms.

Until then, happy coding!

Edit: Today I learned (from Peter's comment below) that you don't actually have to inject the IActionSubscriber into a component such as this, which @inherits FluxorComponent - the ActionSubscriber is already available and (better yet!) unsubscribing will happen automatically. No need to write that code.
With that in mind, here is an updated NavMenu @code block after removing the @inject IActionSubscriber ActionSubscriber line at the top of the file:



@code {
    private bool collapseNavMenu = true;

    private string NavMenuCssClass => collapseNavMenu ? "collapse" : null;
    private string WeatherItemClass => WeatherState.Value.Loading ? "font-weight-bold" : null;

    protected override void OnInitialized()
    {
        SubscribeToAction<WeatherSetForecastsAction>(ShowWeatherToast);
        base.OnInitialized();
    }

    private void ShowWeatherToast(WeatherSetForecastsAction action)
    {
        toastService.ShowInfo("Weather Forecasts have been updated!");
    }

    private void ToggleNavMenu()
    {
        collapseNavMenu = !collapseNavMenu;
    }
}

Notice that SubscribeToAction is called directly, and with no need for the this parameter.

Advanced Blazor State Management Using Fluxor, part 3 - Effects

Eric King — Sun, 07 Mar 2021 02:01:20 +0000

This is the third in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

What about Effects?

You may have noticed that I've mentioned a few times that Fluxor Stores are composed of 5 pieces: State, Feature, Actions, Reducers, and Effects. But so far we've only used 4 of those pieces. We haven't touched Effects yet. Why not?

An Effect in Fluxor is used when a dispatched Action needs to access resources outside of the Store in a way that a "pure" Reducer method cannot. A common example is making an HTTP call to an API. A Reducer method only has access to the current State and the Action it's subscribing to.

An Effect method can access outside resources, and in turn dispatch Actions itself that will be processed by Reducers to emit new State.

A class that contains Effect methods is an instance class (non-static) that can, through its constructor, have resources injected into it on instantiation. Anything that can be injected into a component using the standard dependency injection mechanism in Blazor can be injected into an Effect class instance.

Weather Forecasts

The "Fetch Data" component in the Blazor WebAssembly Hosted template that we're using is a component that, since it makes an API call to retrieve Weather Forecast data, can make use of an Effect method, so that's what we're going to do.

Consider the following scenario:

The Weather Forecasts should only be automatically retrieved the first time the page is loaded. On subsequent views, the already-retrieved forecasts should be displayed, not new ones.

New Weather Forecasts should be retrieved only when clicking a "Refresh Forecasts" button on the page.

Currently, the page will load new forecasts every time the page is viewed:

This is because the WeatherForecast[] is populated whenever the component is initialized, which is every time it's rendered.



@code {
    private WeatherForecast[] forecasts;

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
    }
}

What we really want is some state to hold on to the Forecasts and redisplay when the page is loaded, and a way to track whether the State has been initialized. Perhaps something like this:



public record WeatherState 
{
    public bool Initialized { get; init; }
    public bool Loading { get; init; }
    public WeatherForecast[] Forecasts { get; init; }
}

So lets turn this component into a Fluxor feature.

Step one, make a place for the Weather feature. Create a \Features\Weather folder, and inside that create a Pages folder and a Store folder. Move the FetchData.razor to the newly created Pages folder. In the Store folder create a WeatherStore.cs file.

In the WeatherStore goes the 5 pieces of a Fluxor Store: State, Feature, Actions, Reducers, Effects.

We have a WeatherState, as shown above.

The Feature:



public class WeatherFeature : Feature<WeatherState>
{
    public override string GetName() => "Weather";

    protected override WeatherState GetInitialState()
    {
        return new WeatherState
        {
            Initialized = false,
            Loading = false,
            Forecasts = Array.Empty<WeatherForecast>()
        };
    }
}

The Actions:



public class WeatherSetInitializedAction { }

public class WeatherSetForecastsAction
{
    public WeatherForecast[] Forecasts { get; }

    public WeatherSetForecastsAction(WeatherForecast[] forecasts)
    {
        Forecasts = forecasts;
    }
}

public class WeatherSetLoadingAction
{
    public bool Loading { get; }

    public WeatherSetLoadingAction(bool loading)
    {
        Loading = loading;
    }
}

The Reducers:



public static class WeatherReducers 
{
    [ReducerMethod]
    public static WeatherState OnSetForecasts(WeatherState state, WeatherSetForecastsAction action) 
    {
        return state with 
        {
            Forecasts = action.Forecasts
        };
    }

    [ReducerMethod]
    public static WeatherState OnSetLoading(WeatherState state, WeatherSetLoadingAction action)
    {
        return state with
        {
            Loading = action.Loading
        };
    }

    [ReducerMethod(typeof(WeatherSetInitializedAction))]
    public static WeatherState OnSetInitialized(WeatherState state)
    {
        return state with
        {
            Initialized = true
        };
    }
}

Which will allow us to change the FetchData.razor file like by adding the Fluxor requirements up top:



@inherits FluxorComponent

@using BlazorWithFluxor.Shared
@using BlazorWithFluxor.Client.Features.Weather.Store

@inject IDispatcher Dispatcher
@inject IState<WeatherState> WeatherState
@inject HttpClient Http

Change the @code block to something like:



@code {

    private WeatherForecast[] forecasts => WeatherState.Value.Forecasts;
    private bool loading => WeatherState.Value.Loading;

    protected override async Task OnInitializedAsync()
    {
        if (WeatherState.Value.Initialized == false)
        {
            await LoadForecasts();
            Dispatcher.Dispatch(new WeatherSetInitializedAction());
        }
        await base.OnInitializedAsync();
    }

    private async Task LoadForecasts()
    {
        Dispatcher.Dispatch(new WeatherSetLoadingAction(true));
        var forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
        Dispatcher.Dispatch(new WeatherSetForecastsAction(forecasts));
        Dispatcher.Dispatch(new WeatherSetLoadingAction(false));
    }

}

Exchange this awkward null check in the markup



@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}

with something more meaningful:



@if (_loading)
{
    <p><em>Loading...</em></p>
}

And add a button to trigger a reload of the forecasts:



</table>
<br />
<button class="btn btn-outline-info" @onclick="LoadForecasts">Refresh Forecasts</button>

Build, run, and it works:

However, this part is still a bit awkward:



private async Task LoadForecasts()
{
    Dispatcher.Dispatch(new WeatherSetLoadingAction(true));
    var forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
    Dispatcher.Dispatch(new WeatherSetForecastsAction(forecasts));
    Dispatcher.Dispatch(new WeatherSetLoadingAction(false));
}

There is a lot of state-manipulation going on here, which seems like it would be more appropriately placed in the WeatherStore. What we really want is something more like this:



private void LoadForecasts()
{
    Dispatcher.Dispatch(new WeatherLoadForecastsAction());
}

The handler of that Action, in the WeatherStore, would take care care of all of the State manipulation and leave the page to react to the changing State (see what I did there 😉) rather than drive it.

This is where Effect methods come into play. Since a Reducer cannot call out to the API, we need an Effect method to do it.

So, back to the WeatherStore we go, to add a new Action:



public class WeatherLoadForecastsAction { }

And a WeatherEffects class with one EffectMethod:



public class WeatherEffects 
{
    private readonly HttpClient Http;

    public WeatherEffects(HttpClient http)
    {
        Http = http;
    }

   [EffectMethod(typeof(WeatherLoadForecastsAction))]
    public async Task LoadForecasts(IDispatcher dispatcher) 
    {
        dispatcher.Dispatch(new WeatherSetLoadingAction(true));
        var forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
        dispatcher.Dispatch(new WeatherSetForecastsAction(forecasts));
        dispatcher.Dispatch(new WeatherSetLoadingAction(false));
    }
}

It is similar to the WeatherReducers class, but with one big and obvious difference: this one has a constructor into which we can inject dependencies, and which we can use in each EffectMethod.

Like a [ReducerMethod], an [EffectMethod] can be declared with the Action Type in the attribute (in the case of Actions with no payload), or as a method parameter:



[EffectMethod]
public async Task LoadForecasts(WeatherLoadForecastsAction action, IDispatcher dispatcher) 
{
    // code
}

In this case there is no payload so we declare the Action in the attribute.

Now we can go back to the FetchData.razor file, remove the @inject HttpClient Http since we no longer need it, and the page's @code block now looks like:



@code {

    private WeatherForecast[] forecasts => WeatherState.Value.Forecasts;
    private bool loading => WeatherState.Value.Loading;

    protected override void OnInitialized()
    {
        if (WeatherState.Value.Initialized == false)
        {
            LoadForecasts();
            Dispatcher.Dispatch(new WeatherSetInitializedAction());
        }
        base.OnInitialized();
    }

    private void LoadForecasts()
    {
        Dispatcher.Dispatch(new WeatherLoadForecastsAction());
    }

}

Build, run, and we still should see the same behavior as above. The forecasts load once on component initialize, the component maintains its state between views, and reloads the forecasts when the 'Refresh Forecasts' button is clicked.

As for the WeatherEffects class... What did we gain besides moving some code around? In the next part of this series, we'll explore how having the "Load Forecasts" functionality in the WeatherLoadForecastsAction opens up some opportunities for more complex interactions between application components.

After all of these steps, the solution should look like this branch of the demo repository.

Please leave a comment if you find this helpful, have a suggestion, or want to ask a question.

Happy coding!

Edit: Peter, in his comment below, suggests an adjustment to the Store that simplifies a few things. Here is what the Actions/Reducers/Effects would look like after the changes:



public static class WeatherReducers 
{
    [ReducerMethod]
    public static WeatherState OnSetForecasts(WeatherState state, WeatherSetForecastsAction action) 
    {
        return state with 
        {
            Forecasts = action.Forecasts,
            Loading = false
        };
    }

    [ReducerMethod(typeof(WeatherSetInitializedAction))]
    public static WeatherState OnSetInitialized(WeatherState state)
    {
        return state with
        {
            Initialized = true
        };
    }

    [ReducerMethod(typeof(WeatherLoadForecastsAction))]
    public static WeatherState OnLoadForecasts(WeatherState state)
    {
        return state with
        {
            Loading = true
        };
    }
}

public class WeatherEffects 
{
    private readonly HttpClient Http;
    private readonly IState<CounterState> CounterState;

    public WeatherEffects(HttpClient http, IState<CounterState> counterState)
    {
        Http = http;
        CounterState = counterState;
    }

    [EffectMethod(typeof(WeatherLoadForecastsAction))]
    public async Task LoadForecasts(IDispatcher dispatcher) 
    {
        var forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForecast");
        dispatcher.Dispatch(new WeatherSetForecastsAction(forecasts));
    }
}

#region WeatherActions
public class WeatherSetInitializedAction { }
public class WeatherLoadForecastsAction { }
public class WeatherSetForecastsAction
{
    public WeatherForecast[] Forecasts { get; }

    public WeatherSetForecastsAction(WeatherForecast[] forecasts)
    {
        Forecasts = forecasts;
    }
}
#endregion

This has the effect of simplifying the LoadForecasts EffectMethod, and moving the update of the Loading state to reducers that subscribe directly to WeatherLoadForecastsAction and WeatherSetForecastsAction, removing the need for the Effect to dispatch extra Actions.

Advanced Blazor State Management Using Fluxor, part 2 - Starting with Fluxor

Eric King — Sat, 06 Mar 2021 23:32:47 +0000

This is the second in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project. If you haven't read the previous posts, please start there.

Let's get to some code, shall we?

I'll be illustrating these examples using the Blazor WebAssembly, ASP.NET hosted template in Visual Studio 2019 Community. I'm a big Visual Studio, so that's my preferred IDE, but you can use Visual Studio Code instead if you prefer. Just execute dotnet new blazorwasm -ho in the command shell. The -ho indicates the "ASP.NET Core hosted" option. In Visual Studio 2019, this is what I'm using:

If you build and run at this point, you'll see an application with a Counter page that exhibits the state-losing behavior I noted in the previous blog post:

Installing Fluxor

Before we begin: The code for this blog series can be found on github as shown below. To check your progress for this step of the series, view the 002_Add_Fluxor_Libraries branch.

eric-king / BlazorWithFluxor

A demo of Blazor Wasm using Fluxor as application state management

To add Fluxor to the project and begin our state-management journey, first install the Fluxor.Blazor.Web Nuget package to the .Client project in the solution:



Install-Package Fluxor.Blazor.Web

Alter the Program.cs file to include this line, just above the line that begins "await builder.Build()"



builder.Services.AddFluxor(o => o.ScanAssemblies(typeof(Program).Assembly));

and the accompanying using statement at the top:



using Fluxor;

For convenience, add a couple of Fluxor using statements to the _Imports.razor file:



@using Fluxor
@using Fluxor.Blazor.Web.Components

To initialize Fluxor when the application is started, we add this to the very top of the App.razor file:



<Fluxor.Blazor.Web.StoreInitializer />

And finally, update the wwwroot/index.html to include just above the </body> tag:



<script src="_content/Fluxor.Blazor.Web/scripts/index.js"></script>

And with that, Fluxor is ready to be used. Let's update the Counter page to take advantage.

Note: This is the first point at which I diverge from the introductory videos I referred to in part 1 of this series. They both proceed by creating a "Store" folder at the root of the project, with a "Counter" subfolder, and placing the Counter Store files there. I prefer the feature-oriented folder structure that follows.

Creating the Counter Store

Create a folder at the root of the solution named Features, and another folder inside of it named Counter. This will be the place where we keep all of the files related to the Counter.

In the Counter folder create two more folders named Pages and Store. Move the Counter.razor file from the \Pages folder into the \Features\Counter\Pages folder. Your Client project should look like:

Next let's create the Store.

A Fluxor Store consists of 5 pieces:

The State record
The Feature class
One or more Action classes
The Reducers class
The Effects class

Note: This is the second place where I significantly diverge from the introductory videos. They follow the common C# convention of 'one class per file', which I usually also follow, but I think this situation, where none of these classes should really exist without all of the others, is a good example of when it's fine to group multiple classes together in the same file.

In the \Features\Counter\Store folder create a file named CounterStore.cs. Remove the class CounterStore; we're not going to need it. This file will instead hold all of the Store pieces listed above.

In the new CounterStore file, add a record to store the state of the Counter. We only need to track one property: the current count.



public record CounterState 
{
    public int CurrentCount { get; init; }
}

Note the CurrentCount property doesn't have a setter. It's inherently read-only, as is the intention in the Flux pattern.

Below the state we add the Feature class to expose the CounterState to Fluxor. This will require a using Fluxor; statement at the top of the file.



public class CounterFeature : Feature<CounterState>
{
    public override string GetName() => "Counter";

    protected override CounterState GetInitialState()
    {
        return new CounterState 
        {
            CurrentCount = 0
        };
    }
}

The Fluxor class Feature<T> has two abstract methods we must implement. One returns the name that Fluxor will use for the feature, and here I recommend a simple human-readable string that will uniquely identify the feature for this application. The second sets up the initial state of the State. We'll start with a CurrentCount of zero.

Now we need an Action to dispatch when the button is clicked, instructing the store to increment the counter. Below the Feature, add this class:



public class CounterIncrementAction {}

This class doesn't need any properties, since its name includes all the information needed by the Store to know what to do.

Note: I recommend a naming convention for Actions in the form of FeatureActivityAction where Feature in this case is "Counter", Activity is "Increment", and Action distinguishes the class as an Action. The reason for this is that eventually you may have a lot of Features, and if many of them have an Action class named public class Initialize {} then there is a decent chance of name clashes and confusion later. Naming your Actions this way keeps that from happening and makes it easy to keep track of all the pieces of the Store.

And finally, we need a Reducer method to handle the CounterIncrementAction when it is dispatched. Add this class to the Store file:



public static class CounterReducers 
{
    [ReducerMethod(typeof(CounterIncrementAction))]
    public static CounterState OnIncrement(CounterState state) 
    {
        return state with
        {
            CurrentCount = state.CurrentCount + 1
        };
    }
}

Note that this is a static class, and the ReducerMethod is a static method. This is intentional since a Reducer method should be a pure method with no side effects. It takes in the current State (the CounterState state parameter) and returns a new State with new values based on the Action it's handling. The Reducers class itself contains no state.

There are two ways to declare a ReducerMethod as it relates to the Action it is subscribing to. The most common way is to provide both the State and the Action as parameters to the method, like so:



[ReducerMethod]
public static CounterState OnIncrement(CounterState state, CounterIncrementAction action) 
{
    /// code
}

However, in the case of an Action with no payload, such as with CounterIncrementAction, the action parameter will not be referenced in the body of the method. Depending on your compiler settings, this may result in an 'unused parameter' warning. The alternative [ReducerMethod(typeof(Type))] attribute that takes an Action Type is a way of providing the same behavior without the compiler warning.

Note: I recommend a naming convention of OnActivity for the names of the Reducer methods. The name of the Reducer class and methods don't really matter to Fluxor, as they're identified by scanning for [ReducerMethod] attributes, but having a consistent and meaningful name is useful to the developers working on the application. Having a FeatureActivityAction action handled by an OnActivity Reducer method is easy to remember and understand.

With all of these pieces in place, the CounterStore.cs file should look like this:



using Fluxor;

namespace BlazorWithFluxor.Client.Features.Counter.Store
{
    public record CounterState 
    {
        public int CurrentCount { get; init; }
    }

    public class CounterFeature : Feature<CounterState>
    {
        public override string GetName() => "Counter";

        protected override CounterState GetInitialState()
        {
            return new CounterState 
            {
                CurrentCount = 0
            };
        }
    }

    public class CounterIncrementAction {}

    public static class CounterReducers 
    {
        [ReducerMethod(typeof(CounterIncrementAction))]
        public static CounterState OnIncrement(CounterState state) 
        {
            return state with
            {
                CurrentCount = state.CurrentCount + 1
            };
        }
    }

}

Updating the View

With the CounterStore in place, we're ready to update the Counter.razor page to use it.

In the Counter.razor file, just under the @page "/counter" directive, add:



@inherits FluxorComponent

This allows the Counter component to access the Fluxor resources.

Since we're going to need to reference the CounterStore, we need to add a using statement:



@using BlazorWithFluxor.Client.Features.Counter.Store

We'll need to access the CounterState, and in order to dispatch Actions we'll need a Fluxor Dispatcher, so we inject these:



@inject IDispatcher Dispatcher
@inject IState<CounterState> CounterState

We remove the local count property and replace it with a reference to @CounterState.Value.CurrentCount (the IState<T> wrapper exposes the wrapped state object using the .Value property) and replace the counter++ with a call to Dispatcher.Dispatch(new CounterIncrementAction());. The resulting file should look like:



@page "/counter"
@inherits FluxorComponent

@using BlazorWithFluxor.Client.Features.Counter.Store

@inject IDispatcher Dispatcher
@inject IState<CounterState> CounterState

<h1>Counter</h1>

<p>Current count: @CounterState.Value.CurrentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private void IncrementCount()
    {
        Dispatcher.Dispatch(new CounterIncrementAction());
    }
}

If we build and run the application, we should see the fruits of our labor:

Other components

Once the CounterStore is set up and running, it's not just the Counter.razor component that has access to it; any component in the application can reference it. As an example, let's the CurrentCount to the Nav Menu.

Update the \Shared\NavMenu.razor component to include the necessary Fluxor hooks at the top of the file:



@inherits FluxorComponent
@using BlazorWithFluxor.Client.Features.Counter.Store
@inject IState<CounterState> CounterState

Then change the NavLink label from Counter to Counter (@CounterState.Value.CurrentCount), getting a read-only reference to the CurrentCount property of CounterState.

Build, run, and voilà:

It's that easy.

ReduxDevTools

Ok, one more thing before moving on to the more advanced stuff.

Fluxor also supports the ReduxDevTools browser extension. To enable it, first install the NuGet package Fluxor.Blazor.Web.ReduxDevTools:



Install-Package Fluxor.Blazor.Web.ReduxDevTools

And enable it in the Program.cs by adding .UseReduxDevTools() to the AddFluxor options like so:



builder.Services.AddFluxor(o => o.ScanAssemblies(typeof(Program).Assembly).UseReduxDevTools());

After all of these steps, the solution should look like this branch of the demo repository.

In the next part of this series, I will "featurize" the template's Weather Forecasts component while using a Fluxor Effect method.

Advanced Blazor State Management Using Fluxor, part 1 - Introduction

Eric King — Sat, 06 Mar 2021 23:31:33 +0000

This is the first in a short series of blog posts where I will go beyond the introductory level and dig a bit deeper into using the Fluxor library in a Blazor Wasm project.

If you have written any application using Microsoft's Blazor WebAssembly SPA (single-page application) framework, you will have immediately encountered the challenge of maintaining the state of your application's components while navigating around the application. The out-of-the-box template provides no mechanism for managing state, nor any guidance for how to start.

This can be easily seen using the template's example "Counter" page. Click on the button and see the counter increment. If you navigate away and come back, that previous counter state is lost as the component resets.

If you want to maintain that component's state, it's up to the developer to determine how.

There are a number of resources that introduce the basics of Blazor state management, including this great video from the dotNET YouTube channel featuring Carl Franklin:

In the video, Carl demonstrates one strategy for managing and interacting with application state by creating a "AppState" service and a cascading parameter that all of the components can reference. Good stuff.

But, since Blazor is essentially a SPA, it's useful to consider how other SPA frameworks manage state. For instance, how does React do it? As it turns out, there are a lot of state management libraries that can be used with React, but one of the original (and still most commonly used) libraries is Redux.

Redux uses a an architectural pattern called Flux, introduced by Facebook developers several years ago to help them manage the growing complexity of the Facebook application. There's a great video on YouTube where the Facebook engineering team explain how and why they developed the Flux pattern alongside React:

The Flux pattern is distinguished by its unidirectional flow of changes to a Store that holds the application State, mediated by a Dispatcher that directs dispatched Actions to the appropriate Store functions (Reducers and Effects) that manage the State in a controlled manner.

Is it possible to use the Flux pattern with Blazor? Sure it is. There are a couple of libraries that have been written to implement Flux in .NET, and the one that seems to have the most traction and which I have enjoyed using is Fluxor, by Peter Morris.

mrpmorris / Fluxor

Fluxor is a zero boilerplate Flux/Redux library for Microsoft .NET and Blazor.

Fluxor

Fluxor is a zero boilerplate Flux/Redux library for Microsoft .NET

Introduction

If you are new to Fluxor, or to the Flux/Redux approach in general then this YouTube video by Chris Clement is an excellent introduction.

Goal

The aim of Fluxor is to create a multi-UI, single-state store approach to front-end development without the headaches typically associated with other implementations, such as the overwhelming amount of boiler-plate code required just to add a very basic feature.

Getting started

The easiest way to get started is to read the documentation. Which includes tutorials that are numbered in an order recommended for learning Fluxor. Each will have a README file that explains how the tutorial was created.

Installation

You can download the latest release / pre-release NuGet packages from the official Fluxor nuget pages.

Release notes

See the Releases page for release history.

Upgrading from Blazor.Fluxor (v1 or

…

View on GitHub

I first learned of Fluxor via this video from Nick Chapsas, as part of his excellent Blazor Tutorial series:

Nick has a great way of explaining concepts, and this video is no exception as he does an excellent job introducing an early version of the Fluxor library. Unfortunately, things move fast in the software development world, and the video is becoming a bit out-of-date as Fluxor has changed since November of 2019.

Finally, I watched this SSW TV video where Chris Clement demonstrates how new C# 9 features such as record can make Fluxor even easier and more enjoyable to use:

It was this last video that convinced me to give Fluxor a try. I'm glad I did.

However, as is the case with many introductory videos and tutorials, these only touch on the very basics of the topic. As I've developed more Blazor code, I've come across a number of cases that these introductions don't address, and some Fluxor features that they don't explain. I've also developed some conventions for code organization that I think are useful for any Blazor application that has more than a few features.

I'll share these insights in a series of blog posts, and the code on github. Please share your thoughts, and happy coding!