Forem: Henrick Tissink

8 🍨 Sweet Treats 🍨 in Modern C#

Henrick Tissink — Mon, 14 Mar 2022 07:07:50 +0000

C# through the Ages

Many, many eons ago ✨, C# 'twas but an archaic, OOP focused language. Alas, 'tis no more! Many updates and feature requests later C# has evolved, shedding the object focused shackles of its past, becoming a modern, functional, programming language.

Here are 8 🔥 sizzling 🔥 features to use from C# 7, 8, 9, and 10 to write modern C#.

Throw Expressions

A simple lil' nugget 💎 that is most useful in constructors, when combined with the null-coalescing operator is the throw expression

public string Color { get; set; }
public int Size { get; set; }

// ctor
public Car(string? color, int? size)
{
    Color = color ?? throw ArgumentNullException(nameof(color));
    Size = size ?? throw ArgumentNullException(nameof(size));
}

If either color or size is null, the application will throw a ArugmentNullException.

Another useful place to use this is in conjunction with the ternary operator.

public void SetCharacterLimitedName(string newName, int characterLimit)
{
    Name = newName.Length > characterLimit
        ? throw new ArgumentOutOfRangeException(nameof(newName))
        : newName;
}

The method will throw an ArgumentOutOfRangeException if the length of the new name exceeds the character limit.

Out Variables

Functions with out parameters, returning boolean values, make the best use of this feature. It allows us to do a conditional check, and if it passes we know something about the out variable, and can then use the variable within the scope of the check.

Old way

bool isLucky(int someNumber, out string result)
{
    // the number 7 is lucky
    result = someNumber == 7 ? "you win!" : "you lose...";
    return someNumber == 7;
}

string luckyMessage;
var isLucky = isLucky(11, out luckyMessage);

if (isLucky)
    Console.WriteLine(luckyMessage);

New way

bool isLucky(int someNumber, out string result)
{
    // the number 7 is lucky
    result = someNumber == 7 ? "you win!" : "you lose...";
    return someNumber == 7;
}

if (isLucky(7, out var message))
    Console.WriteLine(message);

This is much more concise, and easy to read!

Pattern Matching with `and`, `or`, and `not`

The and, or, and not keywords have been added to pattern matching in C# to further enrich the pattern matching experience. It makes the code more readable in English, and allows for many combinations of boolean checks in a single line, ensuring there is much less code. With the addition of and, or and not pattern matching goes into overdrive.

// Setup
public enum Color
{
    Red,
    Orange,
    Green,
    Yellow
}

public class Fruit
{
    public string? Name { get; set; }
    public Color Color { get; set; }
    public bool IsTasty { get; set; }
    public int Quantity { get; set; }
}

// Implementation
var firstFruit = new Fruit
{
    Name = "Tomato",
    Color = Color.Red,
    IsTasty = true,
    Quantity = 10
};

var secondFruit = new Fruit
{
    Name = "Banana",
    Color = Color.Green,
    IsTasty = false,
    Quantity = 12
};

var thirdFruit = new Fruit
{
    Name = "Orange",
    Color = Color.Orange,
    IsTasty = false,
    Quantity = 50
};

if (firstFruit is {Name:"Tomato", IsTasty:true, Quantity:>1}
or {Name:"Tomato", Color:Color.Red, Quantity:>10})
    Console.WriteLine("Tomato, at least one tasty or at least 10 red");

if (secondFruit is {Name:"Banana"} and {IsTasty:true}
and {Color:Color.Yellow} and {Quantity:>12})
    Console.WriteLine("Banana, tasty and yellow and at least 12");

if (thirdFruit is {Name:"Orange"} and not {IsTasty:true}
or not {Color:Color.Orange, Quantity:<5})
    Console.WriteLine("Orange, not tasty or orange and less than 5");

Pattern Matching 🍨 and `out`

Combining the aforementioned out variables with pattern matching, gives a wonderfully short, readable result

object numberObject = "12345";

if (numberObject is int number
|| (numberObject is string numberString 
    && int.TryParse(numberString, out number))
{
    Console.WriteLine($"It's a number alright! {number}");
}

Here we check if the object is an int, or a string. If it is a string, we then try and parse it. If it parses then we have the result number available to use within the if block.

Pattern matching also extends far beyond simple type checks. Properties can be matched too!

public class Fighter 
{
    public string? Name { get; set; }
    public string? Style { get; set; }
    public int Strength { get; set; }
    public bool IsChampion { get; set; }
}

var fighter = new Fighter { ... };

if (fighter is {IsChampion:true})
    Console.WriteLine($"{fighter.Name} is a champ!");

if (fighter is {Style:"Karate", Strength:>9000) 
    Console.WriteLine($"{fighter.Name} is powerful!");

Doing property patterns in this way also has the added benefit of an implicit null check. The {} pattern matches with everything except null.

Switch Expressions + Property Patterns 💅

The greatest 👏 the best 👏 the most amazing 👏 of the new features - Switch Expressions! 😎

Combined with property patterns they allow a whole host of conditional operations, in a few short lines of 🧊 crisp C#.

We got em basic 🌼

public string Alakazam(int magicNumber)
{
    return magicNumber switch
    {
        1 => "pow",
        2 => "magic!",
        3 => "behold...",
        // default case
        _ => "ummm, I got nothing..."
    }
}

And extra spicy 🌶️ 🌶️ 🌶️

// The setup
public class Monster
{
    public string? Name { get; set; }
    public int? NumberOfTentacles { get; set; }
    public bool? IsScary { get; set; }
    public Power? Power { get; set; }
}

public class Power
{
    public int Level { get; set; }
    public string? Element { get; set; }
    public bool? DoesPierceArmour { get; set; }
}

// The execution!!!
var monster = new Monster
{
    Name = "Mildred",
    NumberOfTentacles = 23,
    IsScary = true,
    Power = new Power
    {
        Level = 3000,
        Element = "Fire",
        DoesPierceArmour = false
    }
};

var res = monster switch
{
    var m when monster.NumberOfTentacles > 100 =>
        $"Too many damn tentacles! {m.NumberOfTentacles}",
    { IsScary: true } => "Ahhhhhhh!",
    { Power.Element: "Fire"} => "Ooo hot! hot! hot!",
    { Power.DoesPierceArmour: false } => "I ain't afraid of you!",
    var m when monster.Power.Level > 3000 =>
        $"So much power! {m.Power}",
    _ => "ummm, I got nothing?"
};

Each of the case statements are so declarative that their meaning is implicit. Simply by reading the code you already know what's being checked at each case. So much meaning is suddenly contained in so little code.

This is the true power of 🌟 Switch Expressions 🌟.

(Named) Tuples

Ah, the humble tuple 🌝. So short. So sweet. And so very useful. Tuples really shine in places where you need to return multiple values but don't want to create a new object/type to do so.


public (string name, bool isReadyToParty) SomeThing() =>
("Gerry", true);

// Destructuring the tuple
var (name, isReadyToParty) = SomeThing();

Console.WriteLine($"Name: {name}, Ready to Party? {isReadyToParty}")

When using named tuples, where each property of the tuple has a name, it can then be deconstructed on invocation, as var (name, isReadyToParty). This gives a clean way to return multiple variables AND extract them in the calling code.

Records

record types have the potential to be amazing. They're supposed to represent immutable objects - but are only immutaable through the use of init only setters. The init only setters ensure that their properties cannot be set after initialization - and hence guarantees immutability. *BUT record types are not currently immutable by default, and that makes me sad 🐼.

Immutability is on of the cornerstones of the functional programming paradigm.

public record Person
{
    public string? Firstname { get; init; }
    public string? Lastname { get; init; }
};

var person = new Person { Firstname = "Sam" };

// this throws an error
person.Lastname = "Person";

Immutability prevents the following pattern


public record Person
{
    public string? Fullname { get; set; }
    public int? Counter { get; set; }
    public bool? IsTrue { get; set; }
};

var person = new Person { Fullname = "Anna" };

person.Counter++;
person.Fullname += " Luisa";
person.IsTrue != person.IsTrue;

someOtherMethod(person);
andAnotherMethod(person);
yetAnother(person);

/*
 *
 * 20 lines of code
 * passing person around
 *
*/

person.Counter++;
person.Fullname += " Magdalena";
person.IsTrue != person.IsTrue;

/*
 *
 * 20 lines of code
 * passing person around
 *
*/

person.Counter++;
person.Fullname += " Susanna";
person.IsTrue != person.IsTrue;

What is the Person object's name? What is the value of Counter? Do we know if it was mutated inside one of the methods - or maybe not. What is the value of IsTrue? By making Person immutable we can only set this once, and prevent this sort of mess from forming, or compounding on a single object. It simplifies the logical flow through the code.

Adios Amigos

The breadth and scope of the Modern C# programming language, with its wealth of new features 🪐, introduced over the last 4 years, may seem overwhelming at first 😅. However, learning to use these features a few at a time is easy 🏖️ - and will drastically increase the enjoyment derived from working with C#.

Easy Guide to Worker Services in .NET Core

Henrick Tissink — Tue, 17 Nov 2020 07:18:49 +0000

Worker Service

.NET finally feels like a complete framework - you can build RESTful APIs; Console Applications; Background Services; Web front-ends; and most importantly Windows Services - all without needing 3rd party software.

Worker Services are .NET's background service offering. It's the perfect way to create long running services, or services that need to fire at set intervals.

With the advent of .NET Core 3.0, Worker Services can now be created, and installed, as Windows Services without needing 3rd party tools like TopShelf.

Getting Started

The latest version of Visual Studio now comes with a Worker Service template - create a Worker Service Project from this template and call it SimpleFarm.

A farm is a good example project to illustrate the concept of a worker services, because for a farm you need to

do things at set intervals,
and in a set order.

Setting up config

Firstly, we'll touch on the nifty way that .NET handles config. Create a Config folder in your project, and add the following class to it:



public class FarmConfig
{
   public int TillTimeInMinutes { get; set; }
   public int PlantTimeInMinutes { get; set; }
   public int HarvestTimeInMinutes { get; set; }
   public int FertileLandInMetersSquared { get; set; }
   public string Crop { get; set; }
}

The appsettings.json file is where you will be keeping all your config settings - update this file with the following entry:



...
"Farm": {
  "TillTimeInMinutes": 3,
  "PlantTimeInMinutes": 3,
  "HarvestTimeInMinutes": 3,
  "FertileLandInMetersSquared": 100,
  "Crop": "Grain"
} 
...

We're going to be planting grain, on a 100 square meter plot of land. We'll till the land for 3 minutes, plant the crop for 3 minutes, and harvest it in 3 minutes.

Setting up Processes

The farming logic won't be invoked directly in the Worker Service - rather, it will be moved to a set of classes I like to call processes. Create a Process folder in your project, and add the following interface and class to it:



public interface IFarmingProcess
{
   Task TillTheLand();
   Task PlantTheCrop();
   Task HarvestTheCrop();
}

And



public class FarmingProcess : IFarmingProcess
{
   private readonly FarmConfig config;
   private readonly ILogger<FarmingProcess> logger;

   public FarmingProcess(IOptions<FarmConfig> config, ILogger<FarmingProcess> logger)
   {
      this.config = config.Value;
      this.logger = logger;
   }

   public async Task TillTheLand()
   {
      logger.LogInformation($"Tilling {config.FertileLandInMetersSquared} m^2 for {config.Crop} crop!!!");
      await Task.Delay(TimeSpan.FromMinutes(config.TillTimeInMinutes));
   }

   public async Task PlantTheCrop()
   {
      logger.LogInformation($"Planting {config.FertileLandInMetersSquared} m^2 for {config.Crop} crop!!!");
      await Task.Delay(TimeSpan.FromMinutes(config.PlantTimeInMinutes));
   }

   public async Task HarvestTheCrop()
   {
      logger.LogInformation($"Harvesting {config.FertileLandInMetersSquared} m^2 for {config.Crop} crop!!!");
      await Task.Delay(TimeSpan.FromMinutes(config.HarvestTimeInMinutes));
   }
}

The IOptions<FarmConfig> config parameter in the constructor for FarmingProcess is how .NET Core injects config. This will all be wired up once we define what goes into the Dependency Injection container in the Startup.cs file.

Setting up the Worker

Now, we'll set up our Worker Service. Create a Worker folder and add the following class to it:



public class FarmWorker : BackgroundService
{
   private readonly IFarmingProcess farmingProcess;
   private readonly ILogger<FarmWorker> logger;

   public FarmWorker(IFarmingProcess farmingProcess, ILogger<FarmWorker> logger)
   {
      this.farmingProcess = farmingProcess;
      this.logger = logger;
   }

   protected override async Task ExecuteAsync(CancellationToken stoppingToken)
   {
      // This is how we keep the app running (in the background)
      while (!stoppingToken.IsCancellationRequested)
      {
         logger.LogInformation("FarmWorker running at: {time}", DateTimeOffset.Now);

     await farmingProcess.TillTheLand();
     await farmingProcess.PlantTheCrop();
     await farmingProcess.HarvestTheCrop();
      }
   }
}

This is the Worker Service - and it is created by inheriting the BackgroundService class, and overriding ExecuteAsync(...).

When the application runs, it will execute ExecuteAsync(...) in the background. We ensure that ExecuteAsync(...) keeps running/processing its task by wrapping it in a while (!stoppingToken.IsCancellationRequested) {...} loop, which only ends once the application terminates (and cancellation is requested).

Setting up the Application Host

Finally, we set up the host. Add the following Nuget package to your project, to allow it to be installed as a Windows Service:

Microsoft.Extensions.Hosting.WindowsServices

Now remove everything from the Program.cs file and replace with the following:



public class Program
{
   public static void Main(string[] args) => CreateHostBuilder(args).Build().Run();

   public static IHostBuilder CreateHostBuilder(string[] args) =>
      Host.CreateDefaultBuilder(args)
          .ConfigureLogging(logging =>
          {
             logging.ClearProviders();
             logging.AddConsole();
                         logging.AddEventLog();
          })
          // Essential to run this as a window service
          .UseWindowsService()
          .ConfigureServices(configureServices);

   private static void configureServices(HostBuilderContext context, IServiceCollection services)
   {
      services.Configure<FarmConfig>(context.Configuration.GetSection("Farm"));
      services.AddLogging();
      services.AddSingleton<IFarmingProcess, FarmingProcess>();
      services.AddHostedService<FarmWorker>();
   }
}

lastly, add the following to the "Logging" property in your appsettings.json,



  "Logging": {
...
    "EventLog": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.Hosting.Lifetime": "Information"
      }
    }
  },

There are 4 really important things happening here.

1.) .UseWindowsService() allows your worker service to be installed as a Windows Service.

2.) context.Configuration is how you access the configuration that you set within the appsettings.json file.

3.) services.AddHostedService<FarmWorker>() is how you hook your worker service into the application Host process.

4.) logging.AddEventLog() logs messages directly to the Windows Event Log, so we can see if your Worker Service is actually working.

It's crucial that we update the appsettings.json to configure logging to the Windows Event Log.

Running the application, the console should look similar to the following, after all three farming processes have been completed:

Installing as a Windows Service

Great! We now have a Worker Service that can process data at set intervals, execute some SQL cleanup commands, or even do some farming!

This worker service can be attached to any running .NET Core host - an ASP.NET Core API might be a good place to do this, or it can be conveniently installed as a Windows Service and run all on it's own.

To install this as a Windows Service, run a command line shell from the root of your solution and execute



dotnet build

Secondly, use the Service Create (sc) tool on Windows to install your worker service as a Windows Service. I recommend using PowerShell for this. Run your command line shell as Administrator and execute the follow script/command:



sc.exe create FarmWorkerService binPath=C:\...\path to your solution\SimpleFarm\SimpleFarm\bin\Debug\netcoreapp3.1\SimpleFarm.exe

Your service has been created! but it's not running just yet.

Open the Services app on Windows, and look for your service by name - FarmWorkerService. You should see something similar to this.

You can manage the FarmWorkerService through the Services UI or you can manage it through the console with the following 3 commands

sc.exe start DemoWorkerService start the service
sc.exe stop DemoWorkerService stops the service
sc.exe delete DemoWorkerService deletes the service

Either start your service using the Service Create command line tool, or start it using the Services UI. Your FarmWorkerService should now be running!

To confirm that your service is actually running, you can open the Event Viewer app on windows and...

See it happily plodding along!

git hub link to the SimpleFarm project

ASP.NET Core API - Path Versioning + Swashbuckle

Henrick Tissink — Mon, 09 Nov 2020 08:15:10 +0000

The Specifications

.NET Core and ASP.NET Core have come a long way - and so have the different tools to version your ASP.NET Core APIs.

There are three main ways to version your API endpoints

Path versioning version www.some-site.com/v1/potatoes
Query String www.some-site.com?api-version=1.0
Http Header api-supported-version: 1.0 in the request header

Path Versioning

The request path is an address for a resource. When versioning a resource, versioning in the request path makes the most sense - it's declarative, readable, and expresses the most meaning.

A Simple Implementation

First create a new ASP.NET Core API project, and add the following Nuget Package

Microsoft.AspNetCore.Mvc.Versioning

Now, create a controller and add the following endpoints

[Route("api/[controller]")]
[ApiController]
public class SpaceEmporiumController : ControllerBase
{
   [HttpGet("MoonRocks")]
   public IActionResult GetMoonRocks() => Ok("Here are some Moon Rocks! v1");

   [HttpGet("MoonRocks")]
   public IActionResult GetMoonRocksV2() => Ok("Here are some Moon Rocks! v2");
}

Now there are two endpoints to get moon rocks - a version 1, and a newer version 2. ASP.NET Core has no idea how to setup these endpoints because currently they have the same path (and REST verb), viz.

GET api/SpaceEmporium/MoonRocks

We can now use Microsoft.AspNetCore.Mvc.Versioning to indicate which versions go where.

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1")]
[ApiVersion("2")]
[ApiController]
public class SpaceEmporiumController : ControllerBase
{
   [MapToApiVersion("1")]
   [HttpGet("MoonRocks")]
   public IActionResult GetMoonRocks() => Ok("Here are some Moon Rocks! v1");

   [MapToApiVersion("2")]
   [HttpGet("MoonRocks")]
   public IActionResult GetMoonRocksV2() => Ok("Here are some Moon Rocks! v2");
}

A few simple things are happening here

The attribute [Route("api/v{version:apiVersion}/[controller]")] tells ASP.NET Core to add the version attribute to the request path.
The attribute [ApiVersion("x")] specifies the API versions present on this controller
The attribute [MapToApiVersion("x")] maps an endpoint to the specific version

We now have two endpoints:

GET api/v1/SpaceEmporium/MoonRocks
GET api/v2/SpaceEmporium/MoonRocks

returning

"Here are some Moon Rocks! v1"
"Here are some Moon Rocks! v2"

respectively.

For our convenience we'll add one last thing. Within your Startup.cs file add

public void ConfigureServices(IServiceCollection services)
{
   services.AddApiVersioning(o =>
   {
      o.AssumeDefaultVersionWhenUnspecified = true;
      o.DefaultApiVersion = new ApiVersion(1, 0);
   });
}

The .ApiVersioning options are now configured so that we don't have to configure versioning throughout our entire application. If we don't specify versioning on the controllers or endpoints, then it is assumed to be version 1.

Now run the application and test it using Postman or cURL. You should be able to run the following cURL commands, with responses respectively:

curl -X GET https://localhost:5001/api/v1/SpaceEmporium/MoonRocks
Here are some Moon Rocks! v1

curl -X GET https://localhost:5001/api/v2/SpaceEmporium/MoonRocks
Here are some Moon Rocks! v2

Great! Our API is now versioned - the code is easy to read and maintain, and the path versioning it generates is easy to understand and use.

Swagger Generation with Swashbuckle

Now we'll focus on getting versioning working with Swagger Generation and Swashbuckle.

First, add these Nuget Packages:

Swashbuckle.AspNetCore.Swagger
Swashbuckle.AspNetCore.SwaggerGen
Swashbuckle.AspNetCore.SwaggerUI

Now, to get Swashbuckle to understand what's actually going on we'll need to implement two filters:

RemoveVersionFromParameter
ReplaceVersionWithExactValueInPath

RemoveVersionFromParameter removes the version parameter from the Swagger doc that's generated as a result of the [Route("api/v{version:apiVersion}/[controller]")] attribute.

ReplaceVersionWithExactValueInPath replaces the version variable in the path, with the exact value e.g. v1, v2.

public class RemoveVersionFromParameter : IOperationFilter
{
   public void Apply(OpenApiOperation operation, OperationFilterContext context)
   {
      if (!operation.Parameters.Any())
         return;

      var versionParameter = operation.Parameters.Single(p => p.Name == "version");
      operation.Parameters.Remove(versionParameter);
   }
}

and

public class ReplaceVersionWithExactValueInPath : IDocumentFilter
{
   public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
   {
      var paths = new OpenApiPaths();

      foreach(var (key, value) in swaggerDoc.Paths)
         paths.Add(key.Replace("v{version}", swaggerDoc.Info.Version), value);

      swaggerDoc.Paths = paths;
   }
}

In your Startup.cs file, add the following:

public void ConfigureServices(IServiceCollection services)
{
   services.AddApiVersioning(o =>
   {
      o.AssumeDefaultVersionWhenUnspecified = true;  
      o.DefaultApiVersion = new ApiVersion(1, 0);

   });
   services.AddControllers();
   services.AddSwaggerGen(configureSwaggerGen);
}

private static void configureSwaggerGen(SwaggerGenOptions options)
{
   addSwaggerDocs(options);

   options.OperationFilter<RemoveVersionFromParameter>();
   options.DocumentFilter<ReplaceVersionWithExactValueInPath>();

   options.DocInclusionPredicate((version, desc) =>
   {
      if (!desc.TryGetMethodInfo(out var methodInfo))
         return false;

      var versions = methodInfo
         .DeclaringType?
     .GetCustomAttributes(true)
     .OfType<ApiVersionAttribute>()
     .SelectMany(attr => attr.Versions);

      var maps = methodInfo
         .GetCustomAttributes(true)
     .OfType<MapToApiVersionAttribute>()
     .SelectMany(attr => attr.Versions)
     .ToList();

      return versions?.Any(v => $"v{v}" == version) == true
               && (!maps.Any() || maps.Any(v => $"v{v}" == version));
   });
}

private static void addSwaggerDocs(SwaggerGenOptions options)
{
   options.SwaggerDoc("v1", new OpenApiInfo
   {
      Version = "v1",
      Title = "Space Emporium API",
      Description = "API for the Space Emporium",
   });

   options.SwaggerDoc("v2", new OpenApiInfo
   {
      Version = "v2",
      Title = "Space Emporium API",
      Description = "API for the Space Emporium",
   });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
   ...
   app.UseSwagger(c => { c.RouteTemplate = "dev/swagger/{documentName}/swagger.json"; });
   app.UseSwaggerUI(options =>
   {         
      options.SwaggerEndpoint("/dev/swagger/v1/swagger.json", "Space Emporium API v1");
      options.SwaggerEndpoint("/dev/swagger/v2/swagger.json", "Space Emporium API v2");
      options.RoutePrefix = "dev/swagger";
   });
   ...
}

This will generate a v1 and a v2 Swagger doc. Hosted at localhost:5001/dev/swagger.

Both Swagger docs should now work and you should see:

Small trick

Within your Properties/launchSettings.json add the following profiles.

  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "dev/swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "SpaceEmporium": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "dev/swagger",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }

This will launch your application straight onto the Swagger page.

Closing

Path versioning in ASP.NET Core is powerful and easy to implement. Once you have Swagger Generation implemented with versioning it gives that versioning power to whoever is consuming your APIs through the relevant Swagger docs.

SpaceEmporium Versioning App on Github

Objective JS with IIFE

Henrick Tissink — Mon, 21 Sep 2020 06:54:14 +0000

JavaScript is a Multi-Flavored Beast

As a C# developer; an OOP developer; a developer who likes encapsulation and re-usability, Vanilla JavaScript, and all its wonderful uses scared me - until I stumbled upon the simple concept of an IIFE - Immediately Invoked Function Expression.

Some OOP in the JavaScript Sauce

There are so many ways to do things in JavaScript, it can be a little overwhelming for an OOP developer. Where are the classes? Where is the encapsulation? It's all so functional - and so very against the nature of OOP.

IIFEs may not be good (or bad) but they give a way to bring order to Vanilla JavaScript, without having to use any frameworks or clever packages. They're relatively simple, and easy to understand - as will be seen in the example. IIFEs are by no means the correct way to do this - just simply a way that brings a little bit of order to the creative chaos.

The Simplest Example

// Reusable modules
var someModule = (function() {
  // private "members" - Here we use closure to ensure that only the object being returned can access these members
  var privateVar = 'A private variable';

  function privateMethod() {
    console.log('This is a private method')
  };

  return {
    // Public variables
    PublicVar: 'A public variable',

    // Public methods
    publicMethod() {
      console.log('A public function');
    },
    usingPrivateVariables() {
      console.log('Using a private variable')
      console.log(privateVar);
    },
    usingPrivateMethod() {
      console.log('Calling a private method')
      privateMethod();
    }
  };

}());

Does it work as Advertised?

someModule.publicMethod();
// Output: 'A public function'

someModule.usingPrivateVariables();
// Output: 'using a private variable'
// Output: 'A private variable'

someModule.usingPrivateMethod();
// Output: 'Calling a private method'
// Output: 'This is a private method'

console.log(someModule.PublicVar)
// Output: 'A public variable'

console.log(someModule.privateVar)
// Output: undefined
// It's private :)

console.log(someModule.privateMethod())
// Output: someModule.privateMethod is not a function
// It's private too!

IIFE or Iffy?

With modern frameworks, IIFEs are a little redundant (or Iffy) - the likes of Angular, Vue, and React (to name a few) with their structured way of doing things makes the concept a little obsolete.

However I've found IIFEs to be wildly useful in older projects - like ASP.NET MVC, especially with JQuery added to the mix. You can abstract out the actual JQuery calls to separate modules; create private and public variables and functions, and do this all in a modular way. IIFEs add a level of re-usability to code in a way that makes sense to my OOP oriented mind.

They've helped me tremendously in untangling otherwise very complex blotches of JavaScript - and I hope they may help some other poor souls struggling with similar issues.

.NET Essentials - NDepend

Henrick Tissink — Mon, 07 Oct 2019 07:41:48 +0000

Two Types of Software

As developers we deal with two kinds of software. The first kind is when we start a project fresh. It's the most fun and exciting. We get to play with new tech and implement various different solutions that, at the time, we think are the best.

The second kind of software is working with Legacy Systems - maintaining code that others have written. It's often painful, frustrating, and a lot of the time an exercise in patience - untangling a very very tangled ball of spaghetti.

The majority of what we do as software developers is centred around the second kind, the Legacy kind.

Working Effectively with Legacy Code

As a software engineer, diving into the cobwebs and crevices of a legacy system can be an altogether daunting task.

With complex Dependency Injection configurations it can be difficult to tell exactly what is talking to what, especially when configured outside of the code.

Naming conventions can be strange (and bad). I've seen things from "MyControlA" to "FILE_CONTROL_1X" - where nothing makes sense, and absolutely nothing reads like well written prose (as Uncle Bob would say).

And how exactly do you measure the extent of the mess that you're facing when dealing such a system? Where do you start, how much effort will it take, and what exactly can you do?

Greenfields (and how to keep them green)

On the other hand, starting a new project, a new code base, is exciting because it's new and untainted. But without the proper controls things can get messy very quickly.

Good practice would be to set up some sort of Quality Gate in your DevOps pipeline. This is a great step to ensuring code quality - but it is dependent on the nature and quality of your Quality Gate. Can you add your own rules? And can you edit the rules that are already there?

NDepend is an essential .NET tool for both these types of projects, solving each set of problems in a unique, efficient way.

NDepend - a .NET Essential

NDepend comes in a few flavors.

A Visual Studio Extension
Visual NDepend - A UI Client
A Console Application (NDepend.Console.Exe)

The first point to highlight here is the ease of use of NDepend.

Download the NDepend zip from the official site
Unzip it!
Run whichever flavor you like

No messy Java installs; no issues running local servers; just, simply - run it!

Running Visual NDepend gives the option to integrate NDepend into Visual Studio or to simply run once-off analysis on a .NET Solution.

The Visual NDepend UI is clean and crisp, with the look and feel of a .NET product. Navigating the UI is trivial - I used all of the NDepend feature-set without having to look at the documentation once. Everything feels intuitive and easy to figure out.

For the purpose of this post I'll discuss running NDepend's once-off analysis on one of the legacy systems I'm currently working on.

The NDepend analysis ran under 30 seconds; a competitor product took about 20 minutes. This was seriously impressive. How good could such quick analysis be? It was fantastic - much deeper and more insightful. In part thanks to NDepend's rule-set, which is unique with very little overlap when compared to competitor products.

Analysis with NDepend generated a full report (as a webpage) that contained a staggering amount of information about the .NET solution.

The first is a series of diagrams outlining different aspects of your code base.

To understand these diagrams please see Scott Hanselman's excellent NDepend metrics placemat.

Each diagram gives a unique and very insightful look inside of your code-base.

The Dependecy Graph and Matrix is an excellent tool to start untangling your dependencies and to start getting them flowing in the correct direction.
The Treemap metric is great to visualise exactly where the majority of the technical debt sits in your project.
And the Abstractness vs. Instability diagram is just altogether wild - see for yourself - visualising metrics around code complexity etc.

The next thing it generates are Application Metrics.

The most interesting metric is the time estimation for the technical debt. This is unique to NDepend - generated based on the code complexity analysis. From my own personal experience this metric has proven to be quite accurate, and extremely insightful in developer meetings - during activities such as sprint planning.

I'm of the opinion that the most expensive part of software development is technical debt - so this aspect of NDepend makes me feel like a kid in a candy store, especially with its visual aspects. It summarises the debt, giving an exact visual layout of exactly where this debt has been built up, with guidance and time estimates to fixing it.

Finally, the last result of the analysis is the Quality Gate - whether the code is good enough to get a thumbs up from NDepend (or not).

It comes with an in-depth breakdown of rules within the rule-set that have been broken.

Now, opening this report in the Visual NDepend application gives even greater insights.

Each of the Quality Gate rules in the rule-set come with excellent explanations as to why they should not be violated. This makes it a great tool for less senior developers to learn good coding practices (and maybe even some senior ones too).

DevOps and NDepend

As a .NET developer I love my Azure DevOps - so it's a great thing that NDepend has it's own Azure DevOps Build Task as well as its own Azure DevOps extension. The extension has all of the aforementioned metrics at your fingertips, with each of the metrics being fully interactive.

If Azure DevOps isn't your thing - there are detailed tutorials of how to get NDepend set up easily for Jenkins, TeamCity as well as a bunch of other CI tools.

CQLinq - Your rules, Your decisions

NDepends rules are created using CQLinq or Code Quality Linq. It's a trivially simple query language to learn, and allows you to write your own rules (or edit the ones that are there already). For example, the CQLinq rule

//<Name>Avoid too large methods</Name>
warnif count > 0 
from m in Application.Methods 
where m.NbLinesOfCode > 30 
select m

raises a warning if the amount of lines in a method exceeds 30.

.NET Essentials

NDepend has proven to be an invaluable tool to me - dealing with legacy code, or maintaining the integrity of new projects. It blows it's competitors out of the water with performance and depth of analysis.

It has helped me tremendously in understanding software on a much deeper level - and given me insight into the murk of Legacy Code.

NDepend is a fantastic tool I would highly recommend to anyone looking for a reliable, performant, quality gate with deep and useful insights.

It's a .NET Essential.

C# Async Await, Simply

Henrick Tissink — Thu, 26 Sep 2019 06:00:10 +0000

One at a time

Code is executed to achieve a purpose. Usually it's run as a series of steps, eventually leading to a final result. Each of the steps take some time to execute, and running them synchronously, one after the other, can take a significant amount of time.

Say you're a Doctor of Evil - a Dr. Evil if you will. And you want to run a successful criminal enterprise to take over the world; maybe you're looking to make One Million Dollars... Would it be the most effective way to run all of your plans one after the other?

Running an Evil Empire

The first thing you'll need, as an evil mastermind, is of course an Evil Lair.

Task.Delay(x) gives a logical delay of x milliseconds without blocking the current thread



public static void BuildAnEvilLair()
{
    await Task.Delay(5000);
    Console.WriteLine("Evil Lair Built!");
}

After you build your lair, you're going to need to hire some henchman.



public static void HireSomeHenchman()
{
    await Task.Delay(2000);
    Console.WriteLine("Henchman Hired!");
}

And of course, you'll need to create a mini clone of yourself.



public static void MakeMiniClone()
{
    await Task.Delay(3000);
    Console.WriteLine("Mini Clone Created!");
}

Once all of this is in place, you can start working on your Super Evil Plan!



public static void SuperEvilPlan()
{
    await Task.Delay(4000);
    Console.WriteLine("Super Evil Plan Completed!");
}

And let's not forget threatening world leaders with your Super Evil Plan and ransoming One Million Dollars.



public static int MakeOneMillionDollars()
{

    await Task.Delay(2000);
    Console.WriteLine("Million Dollars Made!");
    return 1000000;
}

Finally, when everything has been completed, we can achieve World Domination.



public static void WorldDomination()
{
    await Task.Delay(6000);
    Console.WriteLine("World Domination Achieved!");
}

Putting our plan together,



BuildAnEvilLair();
HireSomeHenchman();
MakeMiniClone();
SuperEvilPlan();
var money = MakeOneMillionDollars();
WorldDomination();

which takes 22 000ms (or 22 seconds) synchronously.

All at once

Many of the steps in such a synchronous plan can be executed in parallel, asynchronously. So how is this done?

First, all the methods will be made asynchronous with the async descriptor, and their executing code will be awaited.

Awaiting asynchronous code, the awaiting code is processed asynchronously, and the code following the await is added as a continuation to the await. The continuation will be run after the code being awaited has run its duration and been successfully executed.



public static async Task BuildAnEvilLair()
{
    await Task.Delay(5000);
    Console.WriteLine("Evil Lair Built!");
}

public static async Task HireSomeHenchman()
{
    await Task.Delay(2000);
    Console.WriteLine("Henchman Hired!");
}

public static async Task MakeMiniClone()
{
    await Task.Delay(3000);
    Console.WriteLine("Mini Clone Created!");
}

public static async Task SuperEvilPlan()
{
    await Task.Delay(4000);
    Console.WriteLine("Super Evil Plan Completed!");
}

public static async Task<int> MakeOneMillionDollars()
{
    await Task.Delay(2000);
    Console.WriteLine("Million Dollars Made!");
    return 1000000;
}

public static async Task WorldDomination()
{
    await Task.Delay(6000);
    Console.WriteLine("World Domination Achieved!");
}

With output

Million Dollars Made!
Super Evil Plan Completed!
Mini Clone Created!
Evil Lair Built!
Henchman Hired!
World Domination Achieved!

Clearly this is a mess. Everything is happening at once. It's really fast - only dependent on the slowest method (6000ms). It's obvious that some calls are dependent on others. Now we need to synchronise them with each other.

Effectively Asynchronous

So, as an Evil Mastermind, which tasks would you run and in which order?

First, we need an evil lair. After that we can hire some henchman and create a mini clone of ourselves. Then we can come up with a Super Evil Plan, after which we can make One Million Dollars and achieve World Domination.

Changing the executing code we can achieve this by using the right mix of await and Task.WaitAll. Task.WaitAll fires off all the tasks asynchronously and finishes awaiting those tasks once all the tasks have completed - so the Task.WaitAll takes as long as the longest task it's awaiting.

Let's try this again.



// First we need an Evil Lair
await BuildAnEvilLair();

// Next, hire Henchman and create a Clone (asynchronously)
Task.WaitAll(HireSomeHenchman(), MakeMiniClone());

// Now, come up with the evil plan
await SuperEvilPlan();

// And finally, make One Million Dollars (and achieve World Domination)
Task.WaitAll(MakeOneMillionDollars(), WorldDomination());

With output,

Evil Lair Built!
Henchman Hired!
Mini Clone Created!
Super Evil Plan Completed!
Million Dollars Made!
World Domination Achieved!

Taking a cool 18 000ms (18 seconds). 4 seconds less than the synchronous implementation.

So remember, next time you want to become an Evil Genius consider asynchronous execution and some time. If it's up to those darn super spies, every second counts!

Gardening - Cultivating Better Software

Henrick Tissink — Thu, 12 Sep 2019 09:57:34 +0000

Entropy

Systems in life, it seems, no matter how hard we try as humans to keep them going, tend to entropy. No matter how hard we try we cannot build things that live forever - immortality, even in the abstract sense, seems an unattainable goal.

Systems are built and they exist for a period of a time, a lifetime. More successful systems lasting much longer, and doing more. Such systems can survive the ebb of time, and with maintenance and care the intensity of the erosion of use can be lessened - but not prevented.

There is one crucial component that keeps good systems running for much longer - gardening. The meticulous grooming, watering, and weeding of a garden bed is crucial to its survival. It requires continuous monitoring and vigilance - removing weeds, as they pop up; watering the flowers when the ground becomes dry; fertilising the soil when it becomes infertile.

Gardening

A beautiful garden is a joyful thing. The value of it, the time and care that went into it, are implicit in its existence. There is a certain joy found in its design - and this is the human element of the system.

A garden can only exist with a gardener; and a beautiful garden needs a good gardener that does constant gardening. Without a gardener a garden would wilt and die - just like a system. Gardening is essential, for the creation, maintenance and preservation of a beautiful garden; but gardeners come and pass, and just so gardens do too.

Software to me is the obsession with building beautiful systems, and just like beautiful gardens these systems require constant gardening. Without it they decay - the ground dries up; the soil becomes infertile, and the the weeds take over.

It's up to us as conscientious, well-mannered, gardeners to keep our gardens healthy. Healthy software lives much longer and performs much better. Maintenance is easier, and it responds well to change.

So how do we tend to our software? How do we water the beds of our code, weed out the bugs, and remove the rot?

Everything is on FIRE

Very seldom do we get to start on something new. The majority of what we do is maintaining that which is already done - and usually it's an awful mess. The welcoming committee on these projects always has reasons and excuses as to why this happened. There's always a reason for the mess. but honestly, who cares.

Let's take a minute to acknowledge those well-intentioned fools, ourselves included, without whom the majority of us wouldn't have jobs. Thanks past me, and thanks past you.

Starting on such a project is intimidating and daunting. The code base is big and tangled, and there are always parts of the code that no one touches. With both hands, and I can't stress this enough, reach out and grab those parts. Shake them around; break them some more; figure out how they work and slowly start to understand them.

Doing this will make you a key-player in your team - you're the guy that's willing to work with the icky stuff. It will allow you to fix it, clean it, and scrub away the rot.

Small fixes are fixes too

All fixes are valuable. Renaming variables, restructuring code, or large functional changes all add value to the code. Don't be hesitant because your change would be too small.

But what is Legacy Code?

Legacy code is untested code. Keep a good coverage percentage for your unit tests - choose one at your own discretion - and always ensure that the heart of your system is unit tested completely. This will allow you to chop and change, refactoring to your heart's content, without having to worry about breaking something crucial.

But don't get lost in a testing labyrinth. This can happen in a few ways. The first is when you start writing so many test that you end up testing silly things like controllers. A 100% test coverage is silly - it makes me think of Russell's Paradox what tests the tests? There is a good level of testing, and then there is an arbitrary level of testing - try and stick to the former.

The second maze you may find yourself in, is trying to test code that is coupled tighter than Betty White in the 1956 spandex swim suit catalog. You start injecting, and injecting and injecting dependencies and your test starts looking like a mess. In this case it's best to leave it for a later stage.

The Time Investment

When the weeds pop up take time to weed the garden. The most elegant fixes take time - and the most elegant fixes last the longest. Writing good code takes time - fixing bad code takes even longer. Tending to a bed of code, understand that it takes time and don't rush it (but don't go too slow either).

As a professional software engineer I adhere to the IEEE Code of Ethics. Because of this, I hold myself to a certain standard - and this is a standard my clients can expect. I simply won't rush something and push it into production because business needs it now. It's irresponsible, and unethical. I won't go at a snails pace either, but I'll ensure that I generate minimal technical debt.

A Full Bed of Roses

Reading code is a painful experience; writing code is a joyful one. This can lead us down a very dangerous path - where we start writing all the code that we need even though most of the functionality exists already.

Remember that any code you write is old already. Spend some time before you start, and scour the code base for what's already there. Extend it if you must and write new code if you absolutely have to. Practice your Coding golf.

Coding golf is the art of using as few key strokes as possible to write a function. It's a great exercise in being terse with your code.

Context is key

Ensure that you understand the context of what you're doing. Don't do something because you've been told to. The bigger picture is key to writing purposeful software. Understanding how all the moving parts work together allows you to write your API's cleanly, and to define those contracts strongly. You'll soon figure out exactly what your piece needs to look like to work cleanly in the bigger system.

Terminate with Extreme Prejudice

Another controversial point, very dear to my developer's heart, is eliminating bad code with extreme prejudice. If you can see it, if you can logically explain why it's bad - cut it out like a tumor.

With version control tools like Git removing bad code should be easy, and should be done without trepidation. If you break something, so what? You now have broken code with less rot - fix the thing that broke cleanly and everything is better. Worst case just roll back your change and try again.

Don't be scared to change things - the only way code can get better, healthier, is by taking a zero-tolerance approach to cleaning it.

Take a Break

Breaking things is bad, right? Let me be crystal clear here when I say

BREAKING THINGS IS GREAT (FANTASTIC EVEN)!

Did you just break some crucial part of the code? If the proper unit tests were in place, this code would never have made it into the code base. So write the tests to prevent this next time. fix it, understand it, and restructure the code so it can't break here again.

Good code should be written to do two things well - it should allow for itself break gracefully; and it should allow for itself to be fixed rapidly.

Breaking code might be a controversial topic. Because the concept of breaking is inherently bad. But if you keep breaking something, in different ways, and removed all the flaws that broke it you have a much stronger, more resilient system.

No Good Deed goes unpunished

In your crusade of truth, and honor, and better code, you're inevitable going to be stepping on some toes. Honestly, this is probably the hardest part of gardening. People have feelings, and people write code. These same people see their code as an extension of themselves. I do too - and I really shouldn't. It's going to happen and the best thing you can do is be very vocal about what you're doing and why you're doing it.

Explain yourself with complete clarity. Leave no shadow of a doubt over what you're doing; and make it crystal clear that you do so without contempt or malice. You're making the code better for everyone.

It's a hard cultural change, and it sucks hurting people's feelings - but you have to crack some eggs to make an omelet. And if that omelet is for the betterment of everyone then that's quite alright.

The Naked Truth

In the end we're all human. We err, and make mistakes. Work together, not against one another. You can achieve so much more as a team than an individual. Search for common ground and build unity with your fellow developers. We're all in this together, and a healthy work environment makes life better for everyone involved.

Goodbye, and thanks for all the Fish

This is a softer piece, and a lot less technical than what I usually write - but it comes straight from my heart. I stand by all the points I've made and I hope it helps you in your endeavors to build a beautiful garden.

Now if you don't mind me - I'll just be over here gardening :)

Pseudo Traits in C#

Henrick Tissink — Wed, 04 Sep 2019 07:05:19 +0000

C# 8.0 Interfaces are not really Interfaces anymore

C# 8.0 ships with the wonderfully horrible idea of interfaces with default implementations.

First of all I'd like to start by saying that interfaces with default implementation is a terrible idea. An interface is a contract void of implementation and has no place having default implementation. This defeats the entire purpose of an interface. What could possibly be better is for the allowance of multiple inheritance of abstract classes. But I digress.

Traits

The idea behind interfaces with default implementations all comes from a programming concept known as a trait. A trait is a programming construct that allows you to attach default behaviour to objects, by simply having them exhibit the trait.

You could have traits like Runner, Swimmer, and Flyer.

Runner would have an implementation for Running() { ... }
Swimmer would have an implementation for Swimming() { ... }
and Flyer would come with an implementation for Flying() { ... }.

Now you could simply define a Penguin with both the traits Runner and Swimmer without actually having to write the code for Swimming() or Running() because by having the traits the functionality is already implemented.

C# really wasn't developed to do this, or at least to do this well. Traits are a more functional construct. A language like Swift, with it's Protocol-Oriented Programming style, caters to this concept very nicely with Protocol Extensions.

Let's take a look at a creative way of doing this in C# 7.0, and I use the term creative very loosely.

Get Schwifty

In Swift a Protocol behaves very similarly to an Interface in C#, and achieves the ability of traits through a Protocol Extension. A Protocol Extension in Swift should in theory then be similar to an Interface extension in C#. This inspired me to try and figure out a way to achieve traits in C#.

Let's create shapes.

Some shapes can roll
and some shapes can bounce.
Some shapes can both roll and bounce.

The Object-Oriented way of implementing this would be to create interfaces for rolling and bouncing.

Any shape that rolls must implement the rolling interface, and any shape that bounces must implement the bouncing interfaces. Could it perhaps be agreed that rolling and bouncing are not so different for each of the shapes? That a bounce is a bounce and a roll is a roll. And maybe we don't want to go and implement a bounce or a roll for every single shape we create.

But wait, you may say, why not just create a super class that rolls? or a super class that bounces?

Firstly, inheritance is bad. Secondly, are you going to create a super class that rolls, a super class that bounces, and a super class that rolls and bounces? Mmm, if only you had multiple inheritance...

You don't have multiple inheritance with classes - but you can implement multiple interfaces.

So... what do we do now? I hinted at interface extensions, let me explain how it works.

disclaimer: this is in no-way recommended as a good way of writing code, it is strictly a thought experiment.

Let's Get Cooking

Let's put together some trait boilerplate.

public abstract class Trait { }

interface ITrait<T> where T : Trait { }

We have an abstract class Trait to be a filter for our traits. We never want to implement Trait directly, but we sure do want a family of things that are traits. The trait class will be used when we define the interfaces.

Using an interface is key, because we can implement multiple of them, we can have as many traits as we want.

Next, let's create some traits.

public CanRoll : Trait { }

public CanBounce: Trait { }

Again, this is kind of boiler plate. It's the bit of fluff that will allow us to implement magical traits.

Finally, lets get to the juice.

public static class ShapeTraits
{
    // this only applies to objects that CanBounce
    public static void Bounce(this ITrait<CanBounce> bouncer)
    {
        Console.WriteLine("I can bounce!");
    }

    // this only applies to objects that CanRoll
    public static void Roll(this ITrait<CanRoll> roller)
    {
        Console.WriteLine("I can roll!");
    }
}

There it is - our two beautiful traits implemented. Next, let's create some shapes.

// A cylinder can roll
public class Cylinder: ITrait<CanRoll>
{
    // this is empty!
}

// A cube can bounce
public class Cube: ITrait<CanBounce>
{
    // this is empty!
}

// And, implementing multiple interfaces,
// a ball can bounce and roll!
public class Ball: ITrait<CanBounce>, ITrait<CanRoll>
{
    // this is empty!
}

Now we can create instances of these classes, classes containing no code at all, and because of these pseudo traits they can actually do things!

var cylinder = new Cylinder();
cylinder.Roll(); // this works!

var cube = new Cube();
cube.Bounce(); // this works!

var ball = new Ball();
// a ball that rolls and bounces
ball.Roll();
ball.Bounce();

By using interface extensions, we have managed to mimic the ability of traits, to create something I call pseudo traits. It's a different way of thinking about objects, and I must say I really like it.

You can build extensions methods and hand pick which ones you want to belong to a certain trait. Picking which traits you want on an object allows you to construct an object bit-by-bit, just by implementing the right interfaces.

Is this a good idea? Honestly, I don't know. Is it a fun thought experiment? I definitely think so :]

Zen and Functional C#

Henrick Tissink — Thu, 29 Aug 2019 22:16:24 +0000

Writing functional programming can induce a Zen like experience. With clean, short blocks of code that reveal their intent and inner workings plainly to you functional C# untangles the knots, and declutters the space.

No more side effects

Take a deep breath in. Hold it for 5 seconds. Exhale.

It's time to think functionally, and it's time to say goodbye to those nasty, no-good side effects.

Side effects occur when you modify state outside of your current scope, mutating state unknowingly somewhere else in the program. This leads to unwanted behaviour, and unwanted cause-and-effects.
Instead prefer functions that don't have side effects. These functions are known as pure functions. (disclaimer: writing pure functions is quite addictive - once you start you just can't stop)

The Zen Code Advises:

AVOID: Impure functions

public void UpdatePrice(decimal vat, decimal cost, decimal markup)
{
    this.price = (cost + markup) * (1 + vat);
}

PREFER: Pure functions

public decimal PriceIncludingVat(decimal vat, decimal cost, decimal markup)
{
    return (cost + markup) * (1 + vat);
}

price = PriceIncludingVat(0.2m, 10m, 2m);

Calling PriceIncludingVat doesn't modify existing state; it returns new state. You can call it as many times as you want and your current price won't be affected until you actually set it.

Practice creating pure functions out of longer impure methods. Break the side effects out of methods and turn them into their own functions returning new state. You may find yourself untangling some really, nasty messes - it's cathartic and brings you closer to Zen.

Immutability

Close your eyes. Breathe in. Breath out. Embrace the tranquillity of immutability.

No longer will your state be mutable. In with the new, and out with the old. By making your objects immutable, you ensure that nothing, within any scope whatsoever, can change them. This prevents side effects altogether. The only way to achieve a changed property on an immutable object is to replace that object with a new one that contains the change.

The Zen Code Advises:

AVOID: Mutable Objects

public class ZenGarden
{
    public int Tranquillity { get; set; } // mutable
    public int Peace { get; set; } // mutable

    public ZenGarden(int tranquillity, int peace)
    {
        Tranquillity = tranquillity;
        Peace = peace;
    }
}

This leads to

var garden = new ZenGarden(10, 20);
garden.Peace = -1000;
// or even worse
public int TranquilityAndPeace(ZenGarden garden)
{
    garden.Peace -= 1; // a side effect
    return garden.Tranquillity + garden.Peace;
}

PREFER:

public class ZenGarden
{
    public readonly int Tranquillity;
    public readonly int Peace;

    public ZenGarden(int tranquillity, int peace)
    {
        Tranquillity = tranquillity;
        Peace = peace;
    }
}

This leads to

var garden = new ZenGarden(10, 20);
garden = new ZenGarden(10, 21); // peace goes up, because of immutability :]
// pure function
public int TranquilityAndPeace(ZenGarden garden)
{
    var calculatedGarden = new ZenGarden(garden.Tranquillity, garden.Peace - 1);
    return calculatedGarden .Tranquillity + calculatedGarden .Peace;
}

Note, readonly is used instead of a private setter to ensure that the values can't be changed even within the class itself.

No more worries about unwanted changes (side effects) - immutability ensures that nothing is mutating the same state, wave a friendly goodbye to race conditions and thread locks too.

Referential Transparency

Embrace the Zen of clarity. A referentially transparent function can be replaced by the value that it returns when it's called. It returns the same value for the same arguments regardless of its context. Referentially opaque functions do the opposite - usually due to referencing some external value which may change.

Referential transparency helps the code to read cleaner. It untangles functions that grab values from outside of their scope, and restricts them to act only on their parameters when calculating their return values.

It isolates functions, protecting them from external changes in code.

The Zen Code Advises:

AVOID: Opaque functions

public double PriceOfFood(double price) 
{
    // if the number of people changes, the price of food changes
    // regardless of price changing
    return this.numberOfPeople * price;
}

PREFER: Transparent functions

public double PriceOfFood(double price, int numberOfPeople) 
{
    return numberOfPeople * price;
}

Higher-Order Functions

It's first-class (functions) baby all the way. Let's pick those functions up and start treating them like the (first-class) citizens they are. C# treats functions like first-class citizens. This means that functions can be used as arguments to methods; functions can be assigned to variables; and function can even be returned from other functions.

Using functions as first-class citizens allows us to break our code into small building blocks, each of which encapsulates a little bit of (hopefully clean, pure, and referentially transparent) functionality. These small blocks can be used in many combinations to get different functionality. They can be swapped out and interchanged as our requirements change with little impact on the code base.

Generate your functionality as you need it - don't write reams of code. Let the functions behave like the moving parts we know they are.

Higher-order functions take in functions as parameters, or return functions. Because C# treats functions as first-class citizens it allows as to create higher-order functions.

The Zen Code Advises:

AVOID: Unclear lambdas

var range = Enumerable.Range(-20, 20);
range.Where(i => i % 2 == 0);
range.Where(i => i % 5 != 0);

PREFER: Named functions

Func<int, bool> isMod(int n) => i => i % n == 0;
range.Where(isMod(true, 2));
range.Where(!isMod(false, 5));

AVOID: Procedural functional calls (where applicable)

public class Car {...}

public void ChangeOil(Car car) {...}
public void ChangeTyres(Car car) {...}
public void Refuel(Car car) {...}

public void PitStop(Car car)
{
    ChangeOil(car);
    ChangeTyres(car);
    Refuel(car);
}

PitStop(car);

PREFER: Dynamic function calls (where applicable)

public class Car {...}

public void ChangeOil(Car car) {...}
public void ChangeTyres(Car car) {...}
public void Refuel(Car car) {...}

public void PitStop(Car car, IEnumerable<Action<Car>> pitstopRoutines)
{
    foreach(var routine in pitstopRoutines)
        routine(car);
}

PitStop(car, new List<Action<Car>>{ChangeOil, ChangeTypes, Refuel});

The method PitStop is much more extensible. It can easily be extended and should hardly ever need modifying. This is achieved by simply passing in the functions you want to execute as parameters, treating them like first-class citizens.

Now go forth and embrace the Zen my dudes

Versioning ASP.Net Core APIs with Swashbuckle - Making Space Potatoes V-x.x.x

Henrick Tissink — Mon, 26 Aug 2019 21:50:01 +0000

Updated Path Versioning Post Here

Creating a new API with ASP.NET Core is fun and easy; versioning that API is a bit harder. The cinch though is how generating Swagger for the initial version is a breeze while generating versioned swagger is a little trickier.

Disclaimer: due to bugs in ASP.Net Core 2.2.0, please use ASP.Net Core 2.1.0

Let's dive into this by creating a simple ASP.Net Core Api (2.1.0) to give us some Space Potatoes. First we'll create a controller called SpaceFarmController.

[Route("api/[controller]")]
[ApiController]
public class SpaceFarmController : ControllerBase
{
    [HttpGet("Potatoes")]
    public string SpacePotatoes() => "Space Potatoes v1";
}

Now, let's add some versioning to this little API. Add the following Nuget Package to your project:

Microsoft.AspNetCore.Mvc.Versioning (version 3.0.0)

Our API will be versioned using Route Versioning, this simply means that our API will be versioned according to its routes, with

version	route
v1	`.../api/controller/v1/something`
V2	`.../api/controller/v2/something`
v{n}	`.../api/controller/v{n}/something`

The API can now easily be versioned by adding attributes to the controller:

[ApiVersion("1")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class SpaceFarmController : ControllerBase
{
    [HttpGet("Potatoes")]
    public string SpacePotatoes() => "Space Potatoes v1";
}

And modifying the Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning(); // just add this
}

Running your app locally, you'll now be able to get some Space Potatoes by making a GET request to https://localhost:5001/api/v1/spacefarm/potatoes.

Let's add some Swagger generation to the mix. For this we'll be using Swashbuckle. Add the following Nuget Package to your project:

Swashbuckle.AspNetCore (version 4.0.1)

Adding Swagger generation to your project is now as simple as adding the following to your Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning();

    // Add this
    services.AddSwaggerGen(options => 
        options.SwaggerDoc("v1", new Info
        {
            Version = "v1",
            Title = "v1 API",
            Description = "v1 API Description",
            TermsOfService = "Terms of Service v1"
        }));
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    // And add this, an endpoint for our swagger doc 
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"v1");
    });
    app.UseMvc();
}

For a final trick, change your launchSettings.json entry for your application to:

"*YOUR APPLICATION NAME HERE*": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }

Now when you run your application, it immediately launches the Swagger page.

If you've done all this correctly, when you run your app you should see a screen similar to:

This is great - you've got Swagger generation and a v1 of your API. But it's an ever changing world in the Space Potato market, and pretty soon you're going to want to create an additional way to get Space Potatoes - a v2.0 if you will.

Now, adding another version is quite easy, but getting the Swagger generation to work with this new version is a bit tricky.

First, let's add a v2 for our endpoint in the SpaceFarmController.cs:

[Route("api/v{version:apiVersion}/[controller]")]
// Which versions the controller responds to
[ApiVersion("1")]
[ApiVersion("2")]
[ApiController]
public class SpaceFarmController : ControllerBase
{
    [HttpGet]
    // Which version the route corresponds to
    [MapToApiVersion("1")]
    [Route("Potatoes")]
    public string GetPotatoes() => "Space Potatoes v1";

    [HttpGet]
    // Which version the route corresponds to
    [MapToApiVersion("2")]
    [Route("Potatoes")]
    public string GetPotatoesV2() => "Space Potatoes v2";
}

Great, fantastic even. We now have two versions of our API. If we run this, we can make requests to https://localhost:5001/api/v1/spacefarm/potatoes and https://localhost:5001/api/v2/spacefarm/potatoes (but the Swagger generation will fail).

Swashbuckle doesn't know that there is a difference in the two routes - it sees them as one and the same. So let's help Swashbuckle out. For this we'll need to create two classes:

public class RemoveVersionFromParameter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        var versionParameter = operation.Parameters.Single(p => p.Name == "version");
        operation.Parameters.Remove(versionParameter);
    }
}

and

public class ReplaceVersionWithExactValueInPath : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Paths = swaggerDoc.Paths
            .ToDictionary(
                path => path.Key.Replace("v{version}", swaggerDoc.Info.Version),
                path => path.Value
            );
    }
}

Both classes a types of special filters that Swashbuckle provides to aid Swagger generation. RemoveVersionFromParameter will remove the API Version as a parameter from the Swagger document. ReplaceVersionWithExactValueInPath will change the path from being variable api/v{version:apiVersion}/[controller] to having a fixed path e.g. api/v1/[controller] .

Finally, the filters will need to be applied to the Swagger generation in Startup.cs, and some other minor modifications need to be made:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning();

    services.AddApiVersioning(o =>
    {
        o.AssumeDefaultVersionWhenUnspecified = true;
        o.DefaultApiVersion = new ApiVersion(1, 0);
    });

    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1",
            new Info
            {
                Version = "v1",
                Title = "v1 API",
                Description = "v1 API Description",
                TermsOfService = "Terms of usage v1"
            });

        // Add a SwaggerDoc for v2 
        options.SwaggerDoc("v2",
            new Info
            {
                Version = "v2",
                Title = "v2 API",
                Description = "v2 API Description",
                TermsOfService = "Terms of usage v3"
            });

                // Apply the filters
        options.OperationFilter<RemoveVersionFromParameter>();
        options.DocumentFilter<ReplaceVersionWithExactValueInPath>();

                // Ensure the routes are added to the right Swagger doc
        options.DocInclusionPredicate((version, desc) =>
        {
            var versions = desc.ControllerAttributes()
                .OfType<ApiVersionAttribute>()
                .SelectMany(attr => attr.Versions);

            var maps = desc.ActionAttributes()
                .OfType<MapToApiVersionAttribute>()
                .SelectMany(attr => attr.Versions)
                .ToArray();

            return versions.Any(v => $"v{v.ToString()}" == version)
                          && (!maps.Any() || maps.Any(v => $"v{v.ToString()}" == version));;
        });

    });

}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration.GetSection("Logging"));
    loggerFactory.AddDebug();

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"v1");
                // Specify and endpoint for v2
        c.SwaggerEndpoint($"/swagger/v2/swagger.json", $"v2");
    });
    app.UseMvc();
}

Most of what was done is quite self-explanatory. The only part that might be of interest is the options.DocInclusionPredicate. The little bit of code defining this predicate finds the versions attributed to the controller and the version mappings associated with a particular endpoint, and ensures that the endpoint is included in the correct Swagger doc.

If everything has been done correctly, running the application should now launch a Swagger doc with multiple versions,

And routes for each version:

Let's talk Strategy Pattern

Henrick Tissink — Thu, 22 Aug 2019 06:49:59 +0000

Porygon

Porygon is a Normal-type Pokemon created entirely from computer code. It can transform itself into code to travel across cyberspace. It has two signature moves, Conversion and Conversion 2. These transform Porygon's type when it's in a Pokemon battle. So Porygon is some code that changes it's type (or execution) during a battle (at run-time). This in essence is the Strategy Pattern.

Dynamic Dispatch

The Strategy Pattern is built on this nifty little thing called dynamic dispatch. Dynamic dispatch is when a program decides what code to execute at run time. The opposite of dynamic dispatch is static dispatch. This is when a program knows what code it's going to execute at compile time.

Being Functional

This pattern forms a fundamental part of functional programming - the ability to create and use families of functions at run time is essential to writing good functional code. A family of functions share the same type-signature - which means that they take the same parameters, and return the same type.

There are many different variations of the Strategy Pattern. The two main implementations will be discussed.

The first is my favourite. It's the neatest with the smallest amount of code. For this we'll be building a simple calculator.

It's Calculated

First, let's define the functionality.

public enum Operation
{
    Addition,
    Subtraction,
    Division,
    Multiplication
}

Great, now that the functionality has been defined a rad little bit of functionality will be cooked up using the Func delegate and a Dictionary.

var Operations = new Dictionary<Operation, Func<int, int, int>>
{
    { Operation.Addition, (x, y) => x + y },
    { Operation.Subtraction, (x, y) => x - y },
    { Operation.Division, (x, y) => x / y },
    { Operation.Multiplication, (x, y) => x * y }
};

At run time, the program (or user) can decide which of the operations to call. Each of the functions belong to the same family, having the type-signature (int, int) -> int. A dictionary of functions gives a sexy bit of syntactic sugar, using it to add two numbers (at run time) as follows:

var result = Operations[Operation.Addition](1, 2) // result = 3

More formally, these functions can be called at run time based on some user selected operation, and allow the addition and removal of functionality based on what's in the dictionary.

Colour Me Crazy

Next, we'll have a look at the Strategy Pattern implemented using interfaces. For this we'll be making a simple shape drawing app. Assuming the app can already draw the shapes, the shapes will be shaded and coloured using the Strategy Pattern. First, create an interface for the shapes.

public interface IShape
{
    string Color { get; set; }
    string Shade { get; set; }
}

Great, now create a shape.

public class Circle: IShape
{
    public string Color { get; set; }
    public string Shade { get; set; }
}

Cooking with Grease! Now lets focus on the strategy - the colouring and shading.

public interface IColoring
{
    void ColorAndShade(IShape shape);
}

public class LightGreen : IColoring
{
    public void ColorAndShade(IShape shape)
    {
        shape.Color = "Green";
        shape.Shade = "Light";
    }
}

public class DarkOrange : IColoring
{
    public void ColorAndShade(IShape shape)
    {
        shape.Color = "Orange";
        shape.Shade = "Dark";
    }
}

public class MediumBlue : IColoring
{
    public void ColorAndShade(IShape shape)
    {
        shape.Color = "Blue";
        shape.Shade = "Medium";
    }
}

So we now have a strategy for shading and colouring, and we have three colours and shades. There's two ways we can go about this.

1. Strategy Property

Modifying the shape class a little.

public interface IShape
{
    string Color { get; set; }
    string Shade { get; set; }
    IColoring Filling { get; set; }
    void Fill();
}

public class Circle: IShape
{
    public string Color { get; set; }
    public string Shade { get; set; }
    public IColoring Filling { get; set; }
    public void Fill() => Filling?.ColorAndShade(this);
}

Now, creating a circle, it can be coloured and shaded at run-time doing

var circle = new Circle();
circle.Filling = new DarkOrange();
circle.Fill(); // Circle is new Dark Orange

2. Strategy Factory

public enum ShadeColor
{
    LightGreen,
    DarkOrange,
    MediumBlue
}

public static class ColoringStrategy
{
    public static IColoring Coloring(ShadeColor coloring)
    {
        switch (coloring)
        {
            case ShadeColor.DarkOrange:
                return new DarkOrange();
            case ShadeColor.LightGreen:
                return new LightGreen();
            case ShadeColor.MediumBlue:
                return new MediumBlue();
            default:
                throw new NotImplementedException();
        }
    }
}

Create and colour the circle like this,

var circle = new Circle();
var coloring = ColoringStrategy.Coloring(ShadeColor.DarkOrange);
coloring.ColorAndShade(circle);

In Closing

This is a trivial example but it illustrates the point easily. Similar implementations can be used to select the right sorting algorithm, or to filter out different objects to modify. Strategies can be used in a host of different ways that fit the need for dynamic dispatch.

Strategies are rad and they help decouple the complexities of your executing code from your calling code. In the first case all the code cared about was the type-signature, in the second case it was the interface. In both cases the code was decoupled from the actual execution, resulting in cleaner more maintainable code.

Factories are neat

Henrick Tissink — Mon, 19 Aug 2019 21:50:02 +0000

Design patterns are kind of old news by now. They're the training wheels we use before we really understand what it means to write clean code; before we really come to grips with SOLID principles and all that cal.

I've always been fond of design patterns when building complex applications; they help to manage complexity and solve repeated, simple problems. There are a few that I use every day, and some I haven't used at all.

Creational Patterns are some of the most useful - and factories are really neat. Factories help us to keep the creational code separate from the actual meat and potatoes of our program.

A factory ensures that we always code toward an interface, and never to an implementation. It helps us decouple our code from the dependencies on low level types, and keep calling code as generic as possible.

The only downside I think, is that it's really REALLY really hard to make factories adhere to the Open-Closed principle. There are ways around this, but they just add more complexity and affect the simple elegance of a factory. So just accept it. They won't be Open-Closed adherent; but they'll be really neat.

Let's C a little Sharper

So how does a factory work, you might ask?

Let's demonstrate with a chocolate factory:

We'll create some Maltezers; a Lunch-Bar; a Kit-Kat; and finally an Aero.
Each of these items is a chocolate. They all satisfy what it means to be a chocolate, and belong to the family of chocolates.

First, lets create an interface (family) called Chocolate

public interface Chocolate 
{
    public void Eat();
}

Next, let's create the different types (instances) of chocolate.

public class Maltezers: Chocolate
{
    public void Eat() 
    {
        Console.WriteLine("Crunch!");
    }
}

public class LunchBar: Chocolate
{
    public void Eat()
    {
        Console.WriteLine("Crisp!");
    }
}

public class KitKat: Chocolate
{
    public void Eat()
    {
        Console.WriteLine("Have a break!");
    }
}

public class Aero: Chocolate
{
    public void Eat()
    {
        Console.WriteLine("Bubbles!");
    }
}

We'll need some easy way to identify them, and don't get me started on magic strings...

public enum ChocolateType 
{
    Maltezers,
    LunchBar,
    KitKat,
    Aero
}

And now for the factory. As a matter of style, I like to name the method creating the object after the family. It's just a little developer preference. The name is usually a noun, and this reads like English.

public class ChocolateFactory
{
    public Chocolate Chocolate(ChocolateType identifier)
    {
        switch(identifier)
        {
            case ChocolateType.Maltezers:
                return new Maltezers();
            case ChocolateType.LunchBar:
                return new LunchBar();
            case ChocolateType.KitKat:
                return new KitKat();
            case ChocolateType.Aero:
                return new Aero();
            default:
                throw new NotImplementedException();
        }
    }
}

And there you have it. What would you like? A Kit-Kat? Well certainly, let me just...

var factory = new ChocolateFactory();
var yourKitKat = factory.Chocolate(ChocolateType.KitKat);

And there you go - a Kit-Kat that looks, feels, and definitely tastes like a chocolate. It responds to being a chocolate and your calling code would never know it was anything other than a chocolate, decoupling the code from the implementation KitKat, and allowing you to code to the interface Chocolate.

Forem: Henrick Tissink

8 🍨 Sweet Treats 🍨 in Modern C#

C# through the Ages

Throw Expressions

Out Variables

Old way

New way

Pattern Matching with and, or, and not

Pattern Matching 🍨 and out

Switch Expressions + Property Patterns 💅

We got em basic 🌼

And extra spicy 🌶️ 🌶️ 🌶️

(Named) Tuples

Records

Adios Amigos

Easy Guide to Worker Services in .NET Core

Worker Service

Getting Started

Setting up config

Setting up Processes

Setting up the Worker

Setting up the Application Host

Installing as a Windows Service

ASP.NET Core API - Path Versioning + Swashbuckle

The Specifications

Path Versioning

A Simple Implementation

Swagger Generation with Swashbuckle

Small trick

Closing

Objective JS with IIFE

JavaScript is a Multi-Flavored Beast

Some OOP in the JavaScript Sauce

The Simplest Example

Does it work as Advertised?

IIFE or Iffy?

.NET Essentials - NDepend

Two Types of Software

Working Effectively with Legacy Code

Greenfields (and how to keep them green)

NDepend - a .NET Essential

DevOps and NDepend

CQLinq - Your rules, Your decisions

.NET Essentials

C# Async Await, Simply

One at a time

Running an Evil Empire

All at once

Effectively Asynchronous

Gardening - Cultivating Better Software

Entropy

Gardening

Everything is on FIRE

Small fixes are fixes too

But what is Legacy Code?

The Time Investment

A Full Bed of Roses

Context is key

Terminate with Extreme Prejudice

Take a Break

No Good Deed goes unpunished

The Naked Truth

Goodbye, and thanks for all the Fish

Pseudo Traits in C#

C# 8.0 Interfaces are not really Interfaces anymore

Traits

Get Schwifty

Let's Get Cooking

Zen and Functional C#

No more side effects

The Zen Code Advises:

Immutability

The Zen Code Advises:

Referential Transparency

The Zen Code Advises:

Higher-Order Functions

The Zen Code Advises:

Now go forth and embrace the Zen my dudes

Versioning ASP.Net Core APIs with Swashbuckle - Making Space Potatoes V-x.x.x

Let's talk Strategy Pattern

Pattern Matching with `and`, `or`, and `not`

Pattern Matching 🍨 and `out`