Stavros Kasidis

Blazor state management without using any libraries

Thu, 01 Aug 2019 13:00:00 +0300

Disclaimer: This post assumes that you know what Blazor is and that you know some of its basic concepts. For more info and documentation on Blazor please visit https://blazor.net.

TL;DR: All the code in this post can be found in this repo (the different iterations contained in branches) https://github.com/stavroskasidis/BlazorSimpleState.BlogPostSample

Intro

When you start creating complex applications using Blazor, you will soon realize that you need a way to manage your application’s state. If you don’t, your code will start to fill with events being passed down to child components, so that parent components can stay up-to-date.

Let’s use an example to see how that looks like.

We will create a page that shows a “counter”, having two buttons: an “increment counter” button that increases the counter and a “reset counter” button that sets the counter back to zero.

Note: The example is quite simple, all of it could be a single component but for demo purposes we will break it up into multiple small components.

Iteration 1 - Using events (no “state management”)

Let’s how we could approach this using events. We will create 4 components:

Counter.razor - This will be our “page” component, in other words, the component that represents the whole page.
CounterDisplay.razor - This will be the component that shows the current count and hosts the two buttons.
CounterIncrementButton.razor - This is the button that increments the counter.
CounterResetButton.razor - This is the button that resets the counter.

Here’s what they look like:

Counter.razor

@page "/counter"
<h1>Counter</h1>
<CounterDisplay CurrentCount="currentCount" OnIncrement="OnIncrement" OnReset="OnReset"/>
@code{
    private int currentCount = 0;
    private void OnIncrement()
    {
        currentCount++;
    }
    private void OnReset()
    {
        currentCount = 0;
    }
}

CounterDisplay.razor

<p>Current count: @CurrentCount</p>
<CounterIncrementButton OnIncrement="@OnIncrement" />
<CounterResetButton OnReset="@OnReset" />
@code {
    [Parameter] protected int CurrentCount { get; set; }
    [Parameter] protected EventCallback<UIMouseEventArgs> OnIncrement { get; set; }
    [Parameter] protected EventCallback<UIMouseEventArgs> OnReset { get; set; }
}

CounterIncrementButton.razor

<button class="btn btn-primary" @onclick="OnIncrement">Click me</button>
@code {
    [Parameter] protected EventCallback<UIMouseEventArgs> OnIncrement { get; set; }
}

CounterResetButton.razor

<button class="btn btn-primary" @onclick="OnReset">Reset Counter</button>
@code {
    [Parameter] protected EventCallback<UIMouseEventArgs> OnReset { get; set; }
}

As you can see, we are passing down events to the component tree so that the “root” component (Counter.razor) stays updated. This is required because Blazor components will re-render only if:

Their parameters have changed.
After an EventCallback is invoked.
You invoke the StateHasChanged() method inside the component.

Well… this kinda sucks !!

We are passing down events everywhere, plus the counter’s state logic is included in the component’s code itself. This is where “state management” as a concept comes to help us.

So what is “state management” ?

No matter what pattern/library you decide to use, it all boils down to a couple simple principles:

You need a State Container: a read-only object that will hold the state of your page.
You also need a way to update the state throught a controlled API.

There are many state management libraries that you can use that have been ported from javascript, like Redux, Fluxor etc. You can find a good collection of libraries in this awesome repo here: https://github.com/AdrienTorris/awesome-blazor.

These libraries are supposed to be super optimal in re-rendering, that is why they usually bring quite a bit of boilerplate code in my opinion.

However, if you want something simple and you want to avoid 3rd party dependencies, you can create your own state management following the principles above.

Iteration 2 - Using a “State” object

So, we need a read-only object that will hold the state of the counter. The object will be passed down to all child components as a CascadingParameter and it will contain public methods to allow state to be changed.

It will also contain an OnCountChanged event so that the “page” component (Counter.razor) will subscribe to, listening for changes to re-render itself.

CounterState.cs

public class CounterState
{
    public int CurrentCount { get; private set; }
    public void IncrementCounter()
    {
        CurrentCount++;
        OnCountChanged?.Invoke();
    }
    public void ResetCounter()
    {
        CurrentCount = 0;
        OnCountChanged?.Invoke();
    }
    public event Action OnCountChanged;
}

This state object will be created in the “page” component (Counter.razor) and the child components will receive state info through parameters.

⚠️ It is important that the child components use parameters to read any data they need and NOT read them directly of the state, otherwise the UI may not update correctly in some cases.

Here is how the components will look like with the CounterState class:

Counter.razor

@page "/counter"
<h1>Counter</h1>
<CascadingValue Value="state">
    <CounterDisplay CurrentCount="state.CurrentCount" />
</CascadingValue>
@code{
    private CounterState state;
    protected override void OnInit()
    {
        state = new CounterState();
        // When counter changes, trigger the component's StateHasChanged 
        // method to notify it to rerender
        state.OnCountChanged += StateHasChanged;
    }
}

CounterDisplay.razor

<p>Current count: @CurrentCount</p>
<CounterIncrementButton  />
<CounterResetButton />
@code {
    [Parameter] protected int CurrentCount { get; set; }
}

CounterIncrementButton.razor

<button class="btn btn-primary" @onclick="State.IncrementCounter">Click me</button>
@code {
    [CascadingParameter] protected CounterState State { get; set; }
}

CounterResetButton.razor

<button class="btn btn-primary" @onclick="State.ResetCounter">Reset Counter</button>
@code {
    [CascadingParameter] protected CounterState State { get; set; }
}

This is an improvement over the the first iteration, however this solution is still mediocre in my opinion. The problem is that you have to pass down the state object and it may be “misused” by the child components if they read data directly from the state.

To improve on this concept, we need another class that will “manage” the state without exposing the state itself down the tree, while keeping it read-only.

This is where C# ‘s nested classes come into play, because a nested class can access the private members of the parent class.

Iteration 3 - Using a “StateManager” nested class

So, we will create a “StateManager” class, nested in the “State” class, that will contain all the logic for altering the state. This new class will then be passed down the tree for the child components to consume.

CounterState.cs

/* Optional: Created as partial class so that the Manager class can be in a different file. */
public partial class CounterState
{
    public int CurrentCount { get; private set; }
}

CounterStateManager.cs

public partial class CounterState
{
    // This is nested inside the CounterState class
    // Bonus: We can reuse a generic name like "Manager" because to reference 
    //        this class, you have to do it through the CounterState class:
    //        e.g. var manager = new CounterState.Manager(state);
    public class Manager
    {
        private readonly CounterState state;
        public Manager(CounterState state)
        {
            this.state = state;
        }
        public void IncrementCounter()
        {
            //We can access private setter of CurrentCount, because this class is nested inside CounterState
            this.state.CurrentCount++;
            OnCountChanged?.Invoke();
        }
        public void ResetCounter()
        {
            //We can access private setter of CurrentCount, because this class is nested inside CounterState
            this.state.CurrentCount = 0;
            OnCountChanged?.Invoke();
        }
        public event Action OnCountChanged;
    }
}

Counter.razor

<h1>Counter</h1>
<CascadingValue Value="stateManager">
    <CounterDisplay CurrentCount="state.CurrentCount" />
</CascadingValue>
@code{
    private CounterState state;
    private CounterState.Manager stateManager;
    protected override void OnInit()
    {
        state = new CounterState();
        stateManager = new CounterState.Manager(state);
        stateManager.OnCountChanged += StateHasChanged;
    }
}

CounterDisplay.razor

<p>Current count: @CurrentCount</p>
<CounterIncrementButton  />
<CounterResetButton />
@code {
    [Parameter] protected int CurrentCount { get; set; }
}

CounterIncrementButton.razor

<button class="btn btn-primary" @onclick="StateManager.IncrementCounter">Click me</button>
@code {
    [CascadingParameter] protected CounterState.Manager StateManager { get; set; }
}

CounterResetButton.razor

<button class="btn btn-primary" @onclick="StateManager.ResetCounter">Reset Counter</button>
@code {
    [CascadingParameter] protected CounterState.Manager StateManager { get; set; }
}

In my opinion, this is a much cleaner approach. We’ve seperated the state from the logic that updates it and as a bonus the child components cannot misuse the state object.

Conclusion

I like this approach and this is what I am currently using in my projects. Maybe this is not as optimal as a dedicated state management library theoretically is, but this way you are avoiding boilerplate code and extra dependencies.

What do you think? Would you do something like this or use a library? Feel free to comment your own ideas and suggestions.

Thank you for reading.

Introducing Blazor Context Menu

Wed, 31 Jul 2019 13:00:00 +0300

With the arrival of Blazor just around the corner, I would like to introduce you to a component I have created for blazor: BlazorContextMenu

This project started as a personal need of mine for another project, so I thought: “This could be a nice reusable component. Why not make it public?”. So, it started quite simple, but over time more and more features got added.

Basic usage

The most simple and basic usage is something like the following:

<ContextMenu Id="myMenu">
    <Item OnClick="@OnClick">Item 1</Item>
    <Item OnClick="@OnClick">Item 2</Item>
    <Item OnClick="@OnClick" Enabled="false">Item 3 (disabled)</Item>
    <Seperator />
    <Item>Submenu
        <SubMenu>
            <Item OnClick="@OnClick">Submenu Item 1</Item>
            <Item OnClick="@OnClick">Submenu Item 2</Item>
        </SubMenu>
    </Item>
</ContextMenu>

<ContextMenuTrigger MenuId="myMenu">
    <p>Right-click on me to show the context menu !!</p>
</ContextMenuTrigger>

@code{
    void OnClick(ItemClickEventArgs e)
    {
        Console.WriteLine($"Item Clicked => Menu: {e.ContextMenuId}, MenuTarget: {e.ContextMenuTargetId}, IsCanceled: {e.IsCanceled}, MenuItem: {e.MenuItemElement}, MouseEvent: {e.MouseEvent}");
    }
}

More Info

For more info like code samples and how to use it in your application, please visit the github repository: https://github.com/stavroskasidis/BlazorContextMenu.

And if you like it and end up using it in your project(s), consider giving it a ⭐!!

😀😀😀

Tips & Tricks #2: Smart minification with tag helpers in ASP.NET Core

Sun, 14 May 2017 10:00:00 +0300

When creating a new ASP.NET Core web application, the current template has the following setup for your css and js:

Views\Shared_Layout.cshtml

<!-- code omitted -->
<head>
<!-- code omitted -->
    <environment names="Development">
        <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.css" />
        <link rel="stylesheet" href="~/css/site.css" />
    </environment>
    <environment names="Staging,Production">
        <link rel="stylesheet" href="https://ajax.aspnetcdn.com/ajax/bootstrap/3.3.7/css/bootstrap.min.css"
              asp-fallback-href="~/lib/bootstrap/dist/css/bootstrap.min.css"
              asp-fallback-test-class="sr-only" asp-fallback-test-property="position" asp-fallback-test-value="absolute" />
        <link rel="stylesheet" href="~/css/site.min.css" asp-append-version="true" />
    </environment>
    <!-- code omitted -->
</head>
<!-- code omitted -->

bundleconfig.json

// Configure bundling and minification for the project.
// More info at https://go.microsoft.com/fwlink/?LinkId=808241
[
  {
    "outputFileName": "wwwroot/css/site.min.css",
    // An array of relative input file paths. Globbing patterns supported
    "inputFiles": [
      "wwwroot/css/site.css"
    ]
  },
  {
    "outputFileName": "wwwroot/js/site.min.js",
    "inputFiles": [
      "wwwroot/js/site.js"
    ],
    // Optionally specify minification options
    "minify": {
      "enabled": true,
      "renameLocals": true
    },
    // Optionally generate .map file
    "sourceMap": false
  }
]

I am not a big fan of this setup because when you create a new .js or .css file you have to add them to the bundleconfig.json and also add them to the layout’s head in the “Development” conditional part.

But then you may run into situations like “oops I added a script to the layout but forgot to add it to the bundler” or “hey, I don’t want all the js files to be loaded on all the pages of my website!”

So let’s see the solution that I am currently using for my ASP.NET Core projects.

1. Switching to gulp

First of all, we are going to change from the default bundler to gulp. We add the following gulpfile.js to our project:

/// <binding BeforeBuild='clean' AfterBuild='min' />
/*
This file in the main entry point for defining Gulp tasks and using Gulp plugins.
Click here to learn more. http://go.microsoft.com/fwlink/?LinkId=518007
*/

var gulp = require("gulp"),
  concat = require("gulp-concat"),
  cssmin = require("gulp-cssmin"),
  uglify = require("gulp-uglify"),
  rename = require('gulp-rename'),
  rimraf = require('rimraf');


var paths = {
    webroot: "./wwwroot/"
};

paths.js = paths.webroot + "js/**/*.js";
paths.minJs = paths.webroot + "js/**/*.min.js";
paths.css = paths.webroot + "css/**/*.css";
paths.minCss = paths.webroot + "css/**/*.min.css";


gulp.task("clean:js", function (cb) {
    rimraf(paths.minJs, cb);
});

gulp.task("clean:css", function (cb) {
    rimraf(paths.minCss, cb);
});

gulp.task("clean", ["clean:js", "clean:css"]);

gulp.task("min:js", function () {
    return gulp.src([paths.js, "!" + paths.minJs], { base: "." })
               .pipe(uglify())
               .pipe(rename({
                    suffix: '.min'
                }))
               .pipe(gulp.dest("."));
});

gulp.task("min:css", function () {
    return gulp.src([paths.css, "!" + paths.minCss], { base: "." })
      .pipe(cssmin())
      .pipe(rename({
            suffix: '.min'
        }))
      .pipe(gulp.dest("."));
});

gulp.task("min", ["min:js", "min:css"]);

Note: You can go here for a full guide about adding gulp to your project.

What the “min” task does is scan our .js and .css files and create their “.min” equivalent. So for example if we have “page1.js” and “page2.js”, gulp will create (side-by-side) “page1.min.js” and “page2.min.js” respectively.

By keeping the files seperate we can load them individually in our pages when appropriate. Now we can move to the next step.

2. Creating a tag helper to serve the appropriate files

So by now you may be thinking, “But dude, now we have to micromanage all of our .js and .css files!”.

We are going to solve this with a set of tag helpers.

The intent is that when the application is running in “Development”, then the non-minified version of the file should be served for debugging purposes, but for “Staging” and “Production” we definitely want the minified version for performance.

We will create a couple tag helpers that do that automatically.

This is the intended markup:

<script src="~/js/page1.js" asp-append-version="true" minified-auto-switch="true"></script>

Notice the minified-auto-switch=“true” part ? That will be our tag helper.

When the above example code would be run in development then “page1.js” would be served, but when we are running in production then “page1.min.js” would be served instead.

Likewise for css files:

<link rel="stylesheet" href="~/css/site.css" asp-append-version="true" minified-auto-switch="true" />

Here is the full code of the tag helpers that implement the above functionality:

/// <summary>
/// Base tag helper that contains the core code for "minified-auto-switch"
/// </summary>
public abstract class MinifiedAutoSwitchTagHelper : TagHelper
{
    public const string MinifiedAutoSwitchAttributeName = "minified-auto-switch";

    private IHostingEnvironment HostingEnviroment;

    protected abstract string AffectedAttribute { get; }

    public MinifiedAutoSwitchTagHelper(IHostingEnvironment hostingEnviroment)
    {
        HostingEnviroment = hostingEnviroment;
    }

    public override int Order
    {
        get
        {
            return int.MinValue;
        }
    }

    /// <summary>
    /// Value indicating if the file path should automatically switch to its' normal 
    /// or its' minified version, depending on the enviroment (Development: normal,
    /// Staging,Production: minified)
    /// </summary>
    [HtmlAttributeName(MinifiedAutoSwitchAttributeName)]
    public bool? MinifiedAutoSwitch { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        TagHelperAttribute originalAttribute;
        if (MinifiedAutoSwitch.HasValue && 
            MinifiedAutoSwitch.Value && 
            context.AllAttributes.TryGetAttribute(AffectedAttribute, out originalAttribute) &&
            originalAttribute.Value != null)
        {
            string attributeValue = originalAttribute.Value.ToString();
            var extension = Path.GetExtension(attributeValue);
            if (HostingEnviroment.IsDevelopment())
            {
                if (attributeValue.EndsWith(".min" + extension))
                {
                    attributeValue = attributeValue.Replace(".min" + extension, extension);
                }
            }
            else
            {
                if (!attributeValue.EndsWith(".min" + extension))
                {
                    attributeValue = attributeValue.Replace(extension, ".min" + extension);
                }
            }

            output.Attributes.SetAttribute(AffectedAttribute, attributeValue);
        }
    }
}


/// <summary>
/// The javascript "minified-auto-switch" tag helper
/// </summary>
[HtmlTargetElement("script", Attributes = MinifiedAutoSwitchAttributeName)]
public class MinifiedAutoSwitchScriptTagHelper : MinifiedAutoSwitchTagHelper
{
    public MinifiedAutoSwitchScriptTagHelper(IHostingEnvironment hostingEnviroment) 
          : base(hostingEnviroment)
    {
    }

    protected override string AffectedAttribute
    {
        get
        {
            return "src";
        }
    }
}

/// <summary>
/// The css "minified-auto-switch" tag helper
/// </summary>
[HtmlTargetElement("link", Attributes = MinifiedAutoSwitchAttributeName)]
public class MinifiedAutoSwitchLinkTagHelper : MinifiedAutoSwitchTagHelper
{
    public MinifiedAutoSwitchLinkTagHelper(IHostingEnvironment hostingEnviroment) 
          : base(hostingEnviroment)
    {
    }

    protected override string AffectedAttribute
    {
        get
        {
            return "href";
        }
    }
}

Note: To learn more about tag helpers and how to add them to your project, go here.

Now when we create a new js or css file, all we have to do is add our tag helper attribute at the file’s reference tag, as shown above:

<script src="~/js/page1.js" asp-append-version="true" minified-auto-switch="true"></script>

Awesomeness achieved !!

Designing a flexible Fluent API - Part 3

Sun, 07 May 2017 15:00:00 +0300

In the previous post, while designing our API we stumbled on a flexibility problem. How do we add common methods to our API builders without compromising on flexibility?

We are going to use C#’s extension methods. Here is how:

public interface ICustomCssEnabledBuilder<TBuilder>
{
    TBuilder GetBuilderInstance();
    ICustomCssEnabledComponent GetComponent();
}

public static class CustomCssEnabledBuilderExtensions
{
    public static TBuilder AddCssClass<TBuilder>
            (this ICustomCssEnabledBuilder<TBuilder> builder, string cssClass)
    {
        builder.GetComponent().CssClasses.Add(cssClass);
        return builder.GetBuilderInstance();
    }
}

Now when a builder needs to support adding a css class to a css enabled component, it just has to implement the ICustomCssEnabledBuilder interface.

public class TextBoxBuilder : ICustomCssEnabledBuilder<TextBoxBuilder>
{
    TextBox _textBox;

    public TextBoxBuilder(TextBox textBox)
    {
        _textBox = textBox;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public TextBoxBuilder GetBuilderInstance()
    {
        return this;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public ICustomCssEnabledComponent GetComponent()
    {
        return _textBox;
    }

    //Textbox specific option
    public TextBoxBuilder Name(string name)
    {
        _textBox.Name = name;
        return this;
    }

    //code omitted
}

Now our builder can be used like this

panel.AddTextBoxFor(model => model.TextProp2)
                 .TextBoxSpecificOption(...)
                 .AddCssClass("custom-css-class")
                 .OtherTextBoxSpecificOption(...);

The same technique can be used for the events API.

public interface IEventEnabledBuilder<TBuilder, TEventBuilder>
{
    TBuilder GetBuilderInstance();
    TEventBuilder GetEventBuilder();
}

public static class EventEnabledBuilderExtensions
{
    public static TBuilder Events<TBuilder, TEventBuilder>(this IEventEnabledBuilder<TBuilder, TEventBuilder> builder, 
                                                           Action<TEventBuilder> eventBuilderExpression)
    {
        var eventBuilder = builder.GetEventBuilder();
        eventBuilderExpression(eventBuilder);
        return builder.GetBuilderInstance();
    }
}

public class TextBoxEventBuilder
{
    private TextBox _textBox;

    public TextBoxEventBuilder(TextBox textBox)
    {
        _textBox = textBox;
    }

    public TextBoxEventBuilder OnChange(string jsHandle)
    {
        _textBox.Events.Add(new ComponentEvent()
        {
            EventName = "change",
            JsHandler = jsHandle
        });
        return this;
    }
}

So our TextBoxBuilder is changed to this.

public class TextBoxBuilder : ICustomCssEnabledBuilder<TextBoxBuilder>,
                              IEventEnabledBuilder<TextBoxBuilder, TextBoxEventBuilder>
{
    private TextBox _textBox;

    public TextBoxBuilder(TextBox textBox)
    {
        _textBox = textBox;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public TextBoxBuilder GetBuilderInstance()
    {
        return this;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public ICustomCssEnabledComponent GetComponent()
    {
        return _textBox;
    }

    [EditorBrowsable(EditorBrowsableState.Never)]
    public TextBoxEventBuilder GetEventBuilder()
    {
        return new TextBoxEventBuilder(_textBox);
    }

    //Textbox specific option
    public TextBoxBuilder Name(string name)
    {
        _textBox.Name = name;
        return this;
    }

    //code omitted
}

And now it can be used like this.

panel.AddTextBoxFor(model => model.TextProp2)
                 .TextBoxSpecificOption(...)
                 .AddCssClass("custom-css-class")
                 .OtherTextBoxSpecificOption(...)
                 .Events(e=> e.OnChange("jsHandlerName"));

Awesomeness achieved !!

Designing a flexible Fluent API - Part 2

Sat, 06 May 2017 21:00:00 +0300

In the previous post, we saw a real life requirement (a custom view engine) and the intended API that the developers would use.

Let’s begin with some of the basic constructs used:

public interface IComponent
{
     //Code omitted
}

public interface IComponentContainer : IComponent
{
     List<IComponent> ChildComponents {get; set;}
     //Code omitted
}

/// Root component of our view
public class View : IComponentContainer
{
    //Code omitted
}

The View class is the root component that contains all of our other components. As you can see it is an IComponentContainer. In the code displayed in the previous post, you may remember a Panel component that contained some other components. A Panel is also an IComponentContainer.

Bear with me, there is a reason I am explaining all of this.

Lets see the TextBox component:

public class TextBox: ICustomCssEnabledComponent, 
                      IEventEnabledComponent
{
    public string Name {get; set;}
    //Code omitted
}

//Not all components will expose access to custom css 
public interface ICustomCssEnabledComponent : IComponent
{
    List<string> CssClasses {get; set;}
}

//A component that supports events will implement this interface
public interface IEventEnabledComponent : IComponent
{
    List<ComponentEvent> Events {get; set;}
}

public class ComponentEvent
{
    public string EventName {get; set;}
    public string JsHandler {get; set;}
}

Now, let’s get into the component builders that provide the fluent API we saw in the previous post.

//Provides the API for the TextBox component
public class TextBoxBuilder
{
    private TextBox _textBox;

    public TextBoxBuilder(TextBox textBox)
    {
        _textBox = textBox;
    }
    
    //Textbox specific option
    public TextBoxBuilder Name(string name)
    {
        _textBox.Name = name;
        return this;
    }
    //code omitted
}

//This is the builder that all component containers' builders inherit. 
//It provides the base entry point for adding components
public class ContainerBuilder<TModel>
{
    protected IComponentContainer _container;

    public TextBoxBuilder AddTextBoxFor<TProperty>
                    (Expression<Func<TModel,TProperty>> propertyExpression)
    {
        var textBox = new TextBox();
        //code omitted: Extracting info from the property expression like: 
        //              property name , caption (MVC style, reading attributes) etc
        return new TextBoxBuilder(textBox);
    }
     //code omitted
}

Ok, so the TextBoxBuilder is where the textbox specific options will be and each call to an option will return the builder instance so that the chain can keep going.

But what about all those properties that are inherited from the common interfaces, like ICustomCssEnabledComponent and IEventEnabledComponent. We do not want to duplicate the code for handling these properties in every builder, right?

If we try to solve the problem using inheritance, like having TextBoxBuilder inherit from a base ComponentBuilder class that contains those common options, we run into a flexibility problem.

What happens if an other component builder doesn’t need all of those methods? We would expose methods that are not appropriate is some cases and this is bad.

In the next post we will see how we are going to solve this problem, using C#’s extension methods.

Designing a flexible Fluent API - Part 1

Sat, 06 May 2017 11:00:00 +0300

Through this series we will see a real life example of how to create a fluent API that is flexible. Keep reading to see what I mean.

Recently, I had to design and create a web platform. The platform would be used by other developers to create business applications. One of the many problems I had to solve is a pretty common requirement for this kind of sofware:

“The end user must be able to customize the layout of a CRUD view; e.g. change the order of the fields, hide them, change their captions or size etc”

The solution I went for is creating a custom view engine for ASP MVC, so that the developers will describe views by code (not razor). The view is created as a tree of component objects that get’s rendered as html. The end users are provided with a designer that allows them to modify and save the component tree, thus achieving customization.

I won’t go into more details about the view engine since it is not the focus of this post, so lets get to the “fluent API” part.

I designed the API that the developers would use like this:

public class MyView : ICodeView<ViewModel>
{
    public void BuildView(ContainerBuilder<ViewModel> builder)
    {
        
        builder.AddTextBoxFor(model => model.TextProp1);

        builder.AddPanel(panel=> 
        {
            panel.AddTextBoxFor(model => model.TextProp2)
                 .AddCssClass("custom-css-class")
                 .Events(e=> e.OnChange("myView.textBoxOnChangeJsHandler"));

            panel.AddCheckBoxFor(model => model.BoolProp)
                 .AddCssClass("custom-css-class")
                 .AddCssClass("custom-css-class2")
                 .Events(e=> e.OnCheck("myView.checkBoxOnCheckJsHandler"));

            //Code omitted
        });
    }
}

Any respectful API should be easy to understand and not expose irrelevant methods or throw “NotSupported” exceptions.

For example, if a component does not support adding a css class to it, then the “AddCssClass” should not be exposed for that component. The same is true for the Events API, not all components support the same events.

In the next post we will see how you can design a flexible API like that.

Tips & Tricks #1: Guard Clauses in C#

Thu, 04 May 2017 14:34:00 +0300

Following the guidelines of defensive programming and fail-fast system design, a method should always validate it’s input.

The code that validates your method’s inputs is called a Guard Clause. It makes your code more understandable and it protects you from bugs and unexpected behaviors.

For example, lets assume we have a simple method that validates a Url:

public bool IsUrlValid(string url)
{
    return Uri.TryCreate(url, UriKind.Absolute, out Uri result) && 
           (result.Scheme == "http" || result.Scheme == "https");
}

If we pass null as the url parameter then the method will return false. At first glance, this may seem ok, since null is indeed an invalid url. However this wasn’t our intention and we do not consider null a valid input value.

So we could rewrite the method as:

public bool IsUrlValid(string url)
{
    if(url == null) 
        throw new ArgumentNullException(nameof(url));
    return Uri.TryCreate(url, UriKind.Absolute, out Uri result) && 
           (result.Scheme == "http" || result.Scheme == "https");
}

That if expression is a Guard Clause. However we can do better than that, since repeating this code over and over in all of our methods is a bad practice. (DRY principle).

So lets create a helper class:

public static class GuardClauses
{
    public static void IsNotNull(object argumentValue, string argumentName)
    {
        if (argumentValue == null) 
            throw new ArgumentNullException(argumentName);
    }
}

And use it like this:

public bool IsUrlValid(string url)
{
    GuardClauses.IsNotNull(url,nameof(url));
    return Uri.TryCreate(url, UriKind.Absolute, out Uri result) && 
           (result.Scheme == "http" || result.Scheme == "https");
}

Note: I am usually against the usage of static methods. However in this case, I believe this a rare exception where a static method can be used since it is not affecting our code’s testability and it does not increase it’s complexity.

We can keep adding more Guard Clauses to our helper class as needed. Here are some more:

public static class GuardClauses
{
    public static void IsNotNull(object argumentValue, string argumentName)
    {
        if (argumentValue == null) 
            throw new ArgumentNullException(argumentName);
    }

    public static void IsNotNullOrEmpty(string argumentValue, string argumentName)
    {
        if (string.IsNullOrEmpty(argumentValue)) 
            throw new ArgumentNullException(argumentName);
    }

    public static void IsNotZero(int argumentValue, string argumentName)
    {
        if (argumentValue == 0) 
            //C# 7.0 syntax: $"Argument '{argumentName}' cannot be zero"
            throw new ArgumentException("Argument '" + argumentName +"' cannot be zero",
                                         argumentName);
    }

   public static void IsLessThan(int maxValue, int argumentValue, string argumentName)
   {
       if (argumentValue >= maxValue) 
            //C# 7.0 syntax: $"Argument '{argumentName}' cannot exceed '{maxValue}'"
            throw new ArgumentException("Argument '" + argumentName +"' cannot exceed " + maxValue,
                                         argumentName);
   }

   public static void IsMoreThan(int minValue, int argumentValue, string argumentName)
   {
       if (argumentValue <= minValue) 
            //C# 7.0 syntax: $"Argument '{argumentName}' cannot be lower than '{minValue}'"
            throw new ArgumentException("Argument '" + argumentName +"'  cannot be lower than " + minValue,
                                         argumentName);
   }
}

Note: Some may disagree with Guard Clauses like “IsLessThan” and “IsMoreThan” because they may step into business logic rules. It’s up to you to decide.