We all know the two value types DateTime and TimeSpan.

With this article, I will write about two simple (yet, very neat) value types, that has been part of the Cuemon family for a very long time (pun intended) and supplement the above mentioned almost to perfection; they are DateSpan and TimeRange.

After the v.6.0.0 release of Cuemon for .NET, TimeRange was changed to a class an renamed to DateTimeRange that inherits from the abstract class named Range{T}. Also, the former TimeRange was added - but covering a range between two TimeSpan value types.

DateSpan

With this struct I was aiming for a simple way to calculate the interval between two DateTime values. Although it seemed like a simple task, it was not without challenges as I had to think about CultureInfo and Calendar at the same time.

Just looking through the code while writing this, I am sure I would refactor most, as it dates back to 2010 (with some modifications over the years).

Update: the code was refactored with the release of Cuemon for .NET v6.0.0 🎉

Anyway, here is a sample on how to calculate the interval from January 1st this year up till today (2018-10-01):

public void DateSpanExample()
{
    var ds = new DateSpan(new DateTime(2018, 1, 1), DateTime.Today);
    Trace.WriteLine($"{ds.Years} year");
    Trace.WriteLine($"{ds.Months} months");
    Trace.WriteLine($"{ds.GetWeeks()} weeks");
    Trace.WriteLine($"{ds.TotalDays} days");
    Trace.WriteLine($"{ds.TotalHours} hours");
    Trace.WriteLine($"{ds.TotalMinutes:N0} minutes");
    Trace.WriteLine($"{ds.TotalSeconds:N0} seconds");
}

This writes out the following output:

Debug Trace:
0 year
10 months
40 weeks
273 days
6552 hours
393.120 minutes
23.587.200 seconds

DateTimeRange

Similiar to DateSpan, this class also represents a period of time between two DateTime values. However, the representation is pure and does not contain any code that can perform complex calculations as the case is with the DateSpan counterpart.

Here is a sample on how to define a period of time ranging from January 1st this year up till today (2021-05-03):

public void DateTimeRangeExample()
{
    var dtr = new DateTimeRange(new DateTime(2021, 1, 1), DateTime.Today);
    Trace.WriteLine(dtr);
}

This writes out the following output:

Debug Trace:
A duration of 122.00:00:00 between 2021-01-01T00:00:00 and 2021-05-03T00:00:00.

TimeRange

Similiar to DateTimeRange, this class represents a period of time between two TimeSpan values.

public void TimeRangeExample()
{
    var tr = new TimeRange(TimeSpan.FromHours(4), TimeSpan.FromHours(6));
    Trace.WriteLine(tr);
}

Debug Trace:
A duration of 00.02:00:00 between 04:00:00 and 06:00:00.

Closing Words

This was a brief article of the struct DateSpan and the two classes DateTimeRange and TimeRange. I hope it brought something to mind and that you can see the value it might add to your projects.

Never the less; code with passion 🔥

With ASP.NET Core the primary way of creating middleware components is by using convention-based activation logic. A secondary way is to use factory-based implementation that was added with two interfaces, IMiddlewareFactory and IMiddleware.

An example of convention-based middleware class looks like this:

// You may need to install the Microsoft.AspNetCore.Http.Abstractions package into your project
public class ConventionalMiddleware
{
    private readonly RequestDelegate _next;
 
    public ConventionalMiddleware(RequestDelegate next)
    {
        _next = next;
    }
 
    public Task Invoke(HttpContext httpContext)
    {
 
        return _next(httpContext);
    }
}

And the factory-based implementation could look like this:

public class FactoryActivatedMiddleware : IMiddleware
{
    public Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        throw new NotImplementedException();
    }
}

However, although both ways are sleak and dandy, I wanted to improve the convention-based activation with two main abstractions; one for middleware components that does not need configuration - and one that requires additional setup.

Middleware with zero to five dependency injected parameters

For the first middleware abstraction, I decided to create an abstract class named Middleware and five additional implementations. The difference lies in the generic type parameters covering dependency injection.

Following our examples from before, we are ending up with a class like this:

public class ConventionalMiddleware : Middleware
{
    public ConventionalMiddleware(RequestDelegate next) : base(next)
    {
    }
 
    public override Task InvokeAsync(HttpContext context)
    {
 
        return Next(context);
    }
}

And if we we have one dependency on ITest, it could look like this:

public class ConventionalMiddleware : Middleware<ITest>
{
    public ConventionalMiddleware(RequestDelegate next) : base(next)
    {
    }
 
    public override Task InvokeAsync(HttpContext context, ITest test)
    {
        
        return Next(context);
    }
}

ConfigurableMiddleware with zero to five dependency injected parameters

For the second - and probably the most relevant middleware abstraction - I went for an abstract class named ConfigurableMiddleware that without dependency injection has one generic type parameter, TOptions.

The constructor defer a little from the first implementation; not only does it support TOptions, it also comes in two flavors: one that is supported by interface IOptions<TOptions> and one that is supported by delegate Action<TOptions>.

When creating the recommended extension method for IApplicationBuilder, do consider using the static ApplicationBuilderFactory class to insure correct invokation of either constructor.

To make the usage of this middleware implementation more clear, I have included a working example that is found in the Cuemon.AspNetCore assembly; it is the HostingEnvironmentMiddleware class:

/// <summary>
/// Provides a hosting environment middleware implementation for ASP.NET Core.
/// </summary>
public class HostingEnvironmentMiddleware : ConfigurableMiddleware<IHostingEnvironment, HostingEnvironmentOptions>
{
    /// <summary>
    /// Initializes a new instance of the <see cref="HostingEnvironmentMiddleware"/> class.
    /// </summary>
    /// <param name="next">The delegate of the request pipeline to invoke.</param>
    /// <param name="setup">The <see cref="HostingEnvironmentOptions" /> which need to be configured.</param>
    public HostingEnvironmentMiddleware(RequestDelegate next, IOptions<HostingEnvironmentOptions> setup) : base(next, setup)
    {
    }
 
    /// <summary>
    /// Initializes a new instance of the <see cref="HostingEnvironmentMiddleware"/> class.
    /// </summary>
    /// <param name="next">The delegate of the request pipeline to invoke.</param>
    /// <param name="setup">The <see cref="HostingEnvironmentOptions" /> which need to be configured.</param>
    public HostingEnvironmentMiddleware(RequestDelegate next, Action<HostingEnvironmentOptions> setup) : base(next, setup)
    {
    }
 
    /// <summary>
    /// Executes the <see cref="HostingEnvironmentMiddleware" />.
    /// </summary>
    /// <param name="context">The context of the current request.</param>
    /// <param name="he">The dependency injected <see cref="IHostingEnvironment"/> of <see cref="InvokeAsync"/>.</param>
    /// <returns>A task that represents the execution of this middleware.</returns>
    public override Task InvokeAsync(HttpContext context, IHostingEnvironment he)
    {
        context.Response.OnStarting(() =>
        {
            if (!Options?.SuppressHeaderPredicate(he) ?? false)
            {
                context.Response.Headers.AddIfNotContainsKey(Options.HeaderName, he.EnvironmentName);
            }
            return Task.CompletedTask;
        });
        return Next(context);
    }
}
 
/// <summary>
/// This is a factory implementation of the <see cref="HostingEnvironmentMiddleware"/> class.
/// </summary>
public static class HostingEnvironmentBuilderExtension
{
    /// <summary>
    /// Adds a hosting environment HTTP header to the <see cref="IApplicationBuilder"/> request execution pipeline.
    /// </summary>
    /// <param name="builder">The type that provides the mechanisms to configure an application’s request pipeline.</param>
    /// <param name="setup">The <see cref="CorrelationIdentifierOptions"/> middleware which need to be configured.</param>
    /// <returns>A reference to this instance after the operation has completed.</returns>
    public static IApplicationBuilder UseHostingEnvironmentHeader(this IApplicationBuilder builder, Action<HostingEnvironmentOptions> setup = null)
    {
        return ApplicationBuilderFactory.UseMiddlewareConfigurable<HostingEnvironmentMiddleware, HostingEnvironmentOptions>(builder, setup);
    }
}

As you can see, this implementation has two generic type parameters; the first is for dependency injection (in this case, we depend on an implementation of IHostingEnvironment) and the other is the required setup of HostingEnvironmentOptions.

The rest of the code should be rather self-explanatory, but do take note of the extension method associated with this middleware.

Closing Words

This was some insights to Middleware and ConfigurableMiddleware. I hope it brought something new for you to enjoy and triggered your curiosity to try it out in your projects.

Code with passion 🔥

With this article I will show how this website, www.cuemon.net, has been configured in ASP.NET Core MVC 2.1.
I will go through it, line by line, where there is a reference to Cuemon related code.

This is the Startup.cs file in my project which is invoked by convention by ASP.NET Core.

using Cuemon.AspNetCore;
using Cuemon.AspNetCore.Mvc.DependencyInjection;
using Cuemon.AspNetCore.Mvc.Filters.Cacheable;
using Cuemon.Homepage.Razor.TagHelpers;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using WBPA.WellKnownLocations;
 
namespace Cuemon.Homepage
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
 
        public IConfiguration Configuration { get; }
 
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddOptions();
            services.Configure<CdnTagHelperOptions>(Configuration.GetSection("CdnTagHelperOptions"));
            services.Configure<HttpCacheableOptions>(o =>
            {
                o.Filters.AddEntityTagHeader(etho =>
                {
                    etho.UseEntityTagResponseParser = true;
                });
            });
            services.AddCacheBusting();
            services.AddMvc(o =>
            {
                o.Filters.Add<HttpCacheableFilter>();
            }).SetCompatibilityVersion(CompatibilityVersion.Latest);
        }
 
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseHostingEnvironmentHeader();
            app.UseCorrelationIdentifierHeader();
            app.UseWellKnownLocations();
            app.UseMvc();
        }
    }
}

Breakdown of ConfigureServices(IServiceCollection)

The first thing we do is configuring our services. Personally, I am a big fan of the Options Pattern (either by interface IOptions<TOptions> or delegate Action<TOptions>), and in this configuration, we are using the former way.

services.Configure<CdnTagHelperOptions>(Configuration.GetSection("CdnTagHelperOptions"));

What happens here is actually new functionality that will be released in a near future.
We are adding the options necessary for our production environment, that will be injected to or Razor views.

This is what the configuration looks like in appsettings.Production.json:

{
  "CdnTagHelperOptions": {
    "Scheme": "Relative",
    "BaseUrl": "nblcdn.net"
  }
}

And this is what the _ViewImports.cshtml looks like:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, cuemon.net

On the next line, we are adding the options for HTTP ETag Header which will be injected to HttpCacheableFilter.
We are allowing dynamic parsing of the body.

services.Configure<HttpCacheableOptions>(o =>
{
    o.Filters.AddEntityTagHeader(etho =>
    {
        etho.UseEntityTagResponseParser = true;
    });
});

On the next line, we are adding AssemblyCacheBusting capabilities using the default shorthand. It basicly juts add a thumbprint to the earlier mentioned Cdn*TagHelpers. from the running assembly of the application. Since stylesheets changes rather often, we could consider using a DynamicCacheBusting instead.

services.AddCacheBusting();

On the last line, we are doing the actual configuration of MVC to use the earlier mentioned HttpCacheableFilter.

services.AddMvc(o =>
{
    o.Filters.Add<HttpCacheableFilter>();
}).SetCompatibilityVersion(CompatibilityVersion.Latest);

Breakdown of Configure(IApplicationBuilder, IHostingEnvironment)

Lastly, we are configuring our application to make use of some the features that are not strongly necessary, but can help in your everyday development with ASP.NET Core MVC.

First we add a HTTP header to the response, that reveals the current environment. Default header name is X-Hosting-Environment.

app.UseHostingEnvironmentHeader();

Next, and this is because if work with SOA in my daily work, we add a Correlation-ID to the response. Default header name is X-Correlation-ID.

app.UseCorrelationIdentifierHeader();

Lastly, and this is a sister project to Cuemon, we configure the application to use RFC 5785 that defines a path to /.well-known/. We do this as the website is using LetsEncrypt SSL.

app.UseWellKnownLocations();

Closing Words

This was a walkthrough of the somewhat simple setup of this website. I hope it brought something new for you to enjoy.

Code with passion 🔥

As you have probably noticed by now - all is new!

The homepage is new - the blog is new. In fact, the blog is so new, that it was impossible to import the old content to this new version.

Long story short; i went from Ghost 0.11 --> 2.1.4, and the changes has been many.

Fear not .. I will make it my goal to keep this blog alive with new and exiting content.

For now, this is just a placeholder to see that the blog engine is working - and that content is coming .. just like winter ;-)