This post lists open source libraries available on Nuget.org that I regularly use and recommend. These packages will save you time and make your applications better. They have good documentation and a great developer experience.

MediatR

MediatR is a simple in-process implementation of the mediator pattern. It helps developer write clean, decoupled and extendable code. Mediator is configured using dependency injection with out of the box support for .NET Core, Autofac and others. The documentation on Github is the best place to get started.

I like to use MediatR to write simple command query type requests using the IRequest interface. IRequest handle messages sent to a single handler. Examples of types of IRequests in a standard web application might be "GetUserQuery" or "UpdateCartCommand". The example below uses an internal nested class to keep the query model and query handler together in one class.

//a simple "query" type request
public class GetUserQuery : IRequest<User>
{
    public int UserID { get; set; }

    internal class GetUserQueryHandler : IRequestHandler<UserGetQuery, UserDto>
    {
        private readonly UserService _userService;

        public UserGetQueryHandler(UserService userService)
        {
            _userService = userService;
        }

        public async Task<UserDto> Handle(GetUserQuery request, CancellationToken cancellationToken)
        {
            //normlly something more extensive here...
            return await _userService.GetUser(request.UserID);
        }
    }
}

//calling code
var user = await mediator.Send(new GetUserQuery(1));

Mediatr also supports notification messages which can have multiple handlers through INotification. Notifications work in a similar way to requests but don't return values. They are great for exposing a "extension point" in your application that you may need to build on later.

As a side note: everything Jimmy Bogard writes code or otherwise is great.

Serilog

Serilog provides structured logging which can target output to just about anywhere. Structured logs capture your log statements and objects as json. They give much more context into what is happening in your application and with the right tools they can be queried and analysed in more detail than standard text logs.

var position = new { Latitude = 25, Longitude = 134 };
var elapsedMs = 34;

log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);

//log output
//{"Position": {"Latitude": 25, "Longitude": 134}, "Elapsed": 34}

One of the best things about Serilog is the community has written sinks - which write logs to an provider for just about every service you can think of. The provided sinks Github page has a full list. A couple I recommend checking out:

• Seq - self hosted structured log viewer
• Sentry - exception reporting service that plugs in automatically to error log events

Hangfire

Hangfire is an easy way to perform scheduled or fire-and forget background jobs for .NET Core and Framework applications. I love how easy it is to get up an running as the jobs can run in your app's main process without requiring a dedicated service.

//Fire and forget
BackgroundJob.Enqueue(() => {
	Console.WriteLine("This will run once, in the background");
});

//Recurring job
RecurringJob.AddOrUpdate(
    () => {
    	Console.WriteLine("This will run daily");
    },
    Cron.Daily
);

//Calling a dependency injection job
BackgroundJob.Enqueue<MyService>(myService => myService.Execute());

Hangfire has a great built in dashboard, dependency injection support and storage options for SQL server, PostgreSQL, Redis and more.

FluentEmail

FluentEmail (written by me) helps you implement complete email sending functionality in your app in less than 10 minutes. It features built in providers for the most popular email senders including SendGrid and Mailgun along with Razor templates out of the box. I recently wrote a full guide to .NET email using FluentEmail that will get you started.

var email = await Email
    .From("bill.gates@microsoft.com")
    .To("luke.lowrey@example.com", "Luke")
    .Subject("Hi Luke!")
    .Body("Fluent email looks great!")
    .SendAsync();

LazyCache

LazyCache is an easy to use, thread safe and developer friendly wrapper for in-memory caching in .NET Core. I've written a bit about LazyCache in the past and I still reach for it every time I need a cache provider.

LazyCache uses a "GetOrAdd" pattern for caching where you request an item from the cache and at the same time provide the function to add that item to the cache if it is missing.

var model = await cache.GetOrAddAsync("HomePageData", 
   async () =>
   {
       return homePageService.GetData(); //function to get cachable data
   }
   , new TimeSpan(12, 0, 0) //12 hour cache expiry
); 

LazyCache is easy to extend so if you need to move beyond a simple in memory cache to something distributed the step up should be pretty seamless.

Dapper

Sometimes SQL data access with Entity Framework is overkill or just too slow. When you want to run raw SQL but still get some nice object mapping Dapper is the way to go.

Dapper is a NuGet library that you can add in to your project that will extend your IDbConnection interface.

Dapper takes your existing database connection and adds extension methods to run raw SQL and map it back to C# classes.

public class Dog
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

var dogs = connection.Query<Dog>(
    "select * from Dogs where Age > @Id", //sql query, @ parameters
    new { Age = 5 } //anonymous object to map parameters
);

MiniProfiler

MiniProfiler is a simple performance profiler for .NET Core and framework (also Ruby, Go and Node) web applications. It attaches automatically to the key parts of your application - mainly database access. MiniProfiler will then render an awesome little timing result directly on your app. It is great for running during development to pick up rogue LINQ queries.

MiniProfiler has great setup documentation with a heap of options. For security reasons, I normally only have it enabled during development.

LinqKit

LINQKit is a set of extensions for querying Entity Framework with Linq. LINQKit allows you to build linq queries and conditions as predicates.

My most common use for LINQKit is simplifying queries with lots of criteria (think grids with filters) using the PredicateBuilder.

//base linq query
var users = from u in context.Users
            select u;

//add conditions as required
var predicate = PredicateBuilder.New<User>(true);

if (!string.IsNullOrWhiteSpace(filters.Name))
    predicate.And(u => u.Name.Contains(filters.Name));

if (!string.IsNullOrWhiteSpace(filters.Email))
    predicate.And(u => u.Email.Contains(filters.Email));

//apply conditions to query
var filteredUsers = users.AsExpandable().Where(predicate);

FluentMigrator or DbUp

If you are looking for an alternative to running EntityFramework code first migrations both FluentMigrator and DbUp will do the job.

DbUp works best if you like raw SQL and simple scripts. You simply create a console application and add SQL files as embedded resources. Some simple code in Program.cs will run your migration scripts in order - easy to integrate into a devops pipeline.

static int Main(string[] args)
{
    var connectionString = args.FirstOrDefault(); //or some configuration

    var upgrader =
        DeployChanges.To
            .SqlDatabase(connectionString)
            .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly())
            .LogToConsole()
            .Build();

    var result = upgrader.PerformUpgrade();
    //omitted error handling...
    return 0;
}

FluentMigrator takes a similar concept with a more code-based approach. Instead of adding raw scripts you create small classes for each migration. This approach gives you more flexibility in building migrations (and saves you remembering the create foreign key sql syntax) and allows for more complete up/down migration scenarios.

using FluentMigrator;

namespace Migrations
{
    [Migration(20180430121800)]
    public class AddLogTable : Migration
    {
        public override void Up()
        {
            Create.Table("Log")
                .WithColumn("Id").AsInt64().PrimaryKey().Identity()
                .WithColumn("Text").AsString();
        }

        public override void Down()
        {
            Delete.Table("Log");
        }
    }
}

CsvHelper

CsvHelper is my go to package for reading and writing csv files.  The library is flexible enough that you can creating custom mapping classes and rules for your C# classes or use the low level row and column methods directly.

//import csv to a class
using (var reader = new StreamReader("importfile.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
   csv.Context.RegisterClassMap<YourClassMap>(); //optionally use a mapping class
   var records = csv.GetRecords<YourClass>();
}

//use a mapping class
public class YourClass
{
    public int Id { get; set; }
    public string Name { get set; }
}

public sealed class YourClassMap : ClassMap<YourClass>
{
    public FooMap()
    {
        Map(m => m.Id).Name("Identifier"); //overrider column names and more
        Map(m => m.Name).Name("TheName");
    }
}

//or access columns directly
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    csv.ReadHeader();
    while (csv.Read())
    {
        var id csv.GetField<int>("Id"),
        var name = csv.GetField("Name");
    }
}

There are similar options for exporting csv files either with direct column writes or using classes and mapping.

using (var writer = new StreamWriter("path\\to\\file.csv"))
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
   csv.WriteRecords(records);
}

Hashids

Hashids for .NET generates short, unique string identifiers from integers - similar to YouTube video ids. It is great for turning one or more integers into a single short, non sequential hashes to use in urls and sharing. Just don't use it in place of security.

var hashids = new Hashids("example salt");

//creates "R9tGSE" hash
var id = hashids.Encode(1, 2, 3);

//decodes "R9tGSE" back into int[] {1, 2, 3}
var numbers = hashids.Decode(id);

Humanizer

Humanizer is for turning dates, numbers, enums and more in human friendly readable strings. It supports lots of data types and can be used with multiple languages.

//These are some methods I use all the time, check out the documentation for the full list

//dates
DateTime.UtcNow.AddHours(-25).Humanize() => "yesterday"
DateTime.UtcNow.AddHours(4).Humanize() => "4 hours from now"

//timespan
TimeSpan.FromDays(16).Humanize() => "2 weeks"

//Pluralize and singularize
"Dog".Pluralize() => "Dogs"
"Dogs".Singularize() => "Dog"

//truncate
"Long text to truncate".Truncate(10) => "Long text…"

Bogus

Bogus is a "fake" data generator for .NET. I shudder at the thought of generating "demo" data and "test" data but Bogus takes a bit part of that pain away.

Bogus allow you to map you C# classes to fake data to quickly generate lots of data. It is also possible to access the underlying methods directly and generate a phone number, email address etc on demand.

//map a class
var userIds = 0;
var testUsers = new Faker<User>()
	.RuleFor(b => b.Id, (f, u) => userIds++)
	.RuleFor(u => u.FirstName, (f, u) => f.Name.FirstName(u.Gender))
	.RuleFor(u => u.LastName, (f, u) => f.Name.LastName(u.Gender))
	.RuleFor(u => u.Avatar, f => f.Internet.Avatar())
	.RuleFor(u => u.UserName, (f, u) => f.Internet.UserName(u.FirstName, u.LastName))
	.RuleFor(u => u.Email, (f, u) => f.Internet.Email(u.FirstName, u.LastName));

//generate users
var user = testUsers.Generate();

//use methods directly
var faker = new Faker("en");
faker.Internet.DomainName(); //eg "sylvester.com"
faker.Company.Bs().Dump(); // eg "enable leading-edge architectures"

Honourable mentions

I also love these libraries but this post was taking me forever to finish.

• FluentValidation
• AutoMapper
• Autofac - if you are stuck on .NET framework this if your best dependency injection option

If you enjoyed the post, please share the thread on Twitter and let me know if I missed out your favourite libraries.

Want more? for a massive community list of .NET resources check out quozd/awesome-dotnet.

FluentEmail is an open-source .NET library (created by me but with lots of help) that helps you implement complete email sending functionality in your dotnet app in less than 10 minutes (probably). It features built in providers for the most popular email senders including SendGrid and Mailgun along with Razor or Liquid templates out of the box.

lukencode/FluentEmail

.NET Core email sending. Contribute to lukencode/FluentEmail development by creating an account on GitHub.

GitHublukencode

Why use FluentEmail?

FluentEmail pieces together the components your application needs for sending email.

• The API is so simple that autocomplete (almost) writes your code for you!
• Well tested providers for the popular email senders and template engines are available out of the box (keep reading to see examples)
• Solid dependency injection keeps your code clean and allows you to easily write tests or switch out email options for different tenants/environments

Basic Usage

FluentEmail and its providers can be installed via Nuget. The FluentEmail.Core library is all you need to get started.

dotnet add package FluentEmail.Core

To construct and send an email you just keep building up the fluent methods on the IEmail class. When you are ready to send call SendAsync().

var email = await Email
    .From("bill.gates@microsoft.com")
    .To("luke.lowrey@example.com", "Luke")
    .Subject("Hi Luke!")
    .Body("Fluent email looks great!")
    .SendAsync();

There are the most common methods available on the email object (for the full list see IFluentEmail.cs)

• .To(string emailAddress) - add recipients
• .SetFrom(string emailAddress) - change the sender address
• .CC/BCC(string emailAddress) - add CC or BCC
• .Subject(string subject) - set the subject
• .Body(string body) - set the message body (without templating)
• .Attach(Attachment attachment) - add attachments
• UsingTemplate(string template, T model, bool isHtml = true) - set a template, keep reading for more templating information
• SendAsync() - send the email using the configured sender

Dependency Injection

The best way to use FluentEmail is to configure your sender and template choices with dependency injection. There is good out of the box support for the built in .NET DependencyInjection classes.

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")
        .AddRazorRenderer()
        .AddSmtpSender("localhost", 25);
}

This example sets up FluentEmail with a default SendFrom address and uses the injection helpers to add the SmtpSender and RazorRenderer.

• ISender - this interface is the provider that will be used to send the email. In this example the AddSmtpSender() method configures an SmtpSender provider.
• ITemplateRenderer - this is an optional interface to provide email templating support. In the example the AddRazorRenderer() method is setting up the RazorRenderer provider.

Using dependency injection will make a couple of interfaces available to your code. See the example below for sending email with the configured services.

public class EmailExampleController : Controller
{
    public async Task<IActionResult> SendSingleEmail([FromServices] IFluentEmail singleEmail)
    {    
        var email = singleEmail
            .To("test@test.test")
            .Subject("Test email")
            .Body("This is a single email");

        await email.SendAsync();
        
        return Ok();
    }
    
    public async Task<IActionResult> SendMultipleEmail([FromServices] IFluentEmailFactory emailFactory)
    {    
        var email1 = emailFactory
            .Create()
            .To("test@test.test")
            .Subject("Test email 1")
            .Body("This is the first email");

        await email1.SendAsync();
        
        var email2 = emailFactory
            .Create()
            .To("test@test.test")
            .Subject("Test email 2")
            .Body("This is the second email");

        await email2.SendAsync();
        
        return Ok();
    }
}

• IEmail - this is a single instance of an email to be sent as demonstrated in the basic example above. Use this to send one email (but no more!)
• IEmailFactory - this interface has a method .Create() which will give you an IEmail instance. Use this interface to send multiple emails in the same method or request - see the following example.

Template Rendering

FluentEmail has core support for multiple template renderer providers. To use template rendering, include one of the providers and configure it as part of your dependency injection.

// Using Razor templating package (or set using AddRazorRenderer in services)
Email.DefaultRenderer = new RazorRenderer();

var template = "Dear @Model.Name, You are totally @Model.Compliment.";
var model = new 
{
    Name = "Luke Lowrey",
    Position = "Developer",
    Message = "Hi Luke, this is an email message"
};

var email = Email
    .From("bob@hotmail.com")
    .To("somedude@gmail.com")
    .Subject("woo nuget")
    .UsingTemplate(template, model);

The UsingTemplate method accepts a string for the template and an object for the model to use. The template itself will depend on the provider you are using, this example uses the standard RazorRenderer

FluentEmail also providers helper methods to source template files from disk or as embedded resources as well as serving different templates based on culture.

• UsingTemplateFromEmbedded(string path, T model, Assembly assembly) - pass the assembly with the embedded resource and the path eg "YourApp.EmailTemplates.Welcome.txt"".
• UsingTemplateFromFile(string filename, T model) - pass the file path for the template.

Razor Email Templates

The examples above use the FluentEmail.Razor template renderer. This is the most popular option for templating. The Razor render uses the RazorLight library to render Razor strings.

dotnet add package FluentEmail.Razor

The RazorRenderer supports any valid Razor code. This example (taken from the test project) shows how you can use layout pages in templates.

//configure the Razor Renderer
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")
        
        //pass in the root directory for files
        .AddRazorRenderer(Directory.GetCurrentDirectory()) 
        
        //OR pass in a type in the assemble with embedded templates
        .AddRazorRenderer(typeof(Startup));
}


//In your template code include a layout file
//the template could be sourced from file/embedded if that is configured
var template = @"
    @{ Layout = ""./Shared/_Layout.cshtml""; }
    
    Hi @Model.Name here is a list @foreach(var i in Model.Numbers) { @i }
";

var model = new { Name = "LUKE", Numbers = new[] { "1", "2", "3" } };

var email = new Email()
    .To("test@test.test")
    .Subject("Razor template example")    
    .UsingTemplate(template, model});

Liquid Templates

Liquid templates are a more restricted templating language created by Shopify. They are more lightweight than Razor templates as well as safer and simpler for end users to create. Properties on the model are made available as Liquid properties in the template. FluentEmail uses Fluid (see samples) to render the templates in C#.

//configure the Razor Renderer
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")     
        .AddLiquidRenderer(options =>
        {
            // file provider is used to resolve layout files if they are in use
            options.FileProvider = new PhysicalFileProvider(Path.Combine(someRootPath, "EmailTemplates")); ;
        });
}


// Liquid template which utilizes layout
var template = @"
    {% layout '_layout.liquid' %}    
    Dear {{ Name }}, You are totally {{ Compliment }}.
";

var model = new ViewModel { Name = "Luke", Compliment = "Awesome" };

var email = Email
    .From()
    .To("somedude@gmail.com")
    .Subject("Liquid templates")
    .UsingTemplate(template, model);

Email Senders

FluentEmail allows you to plug in popular email sending providers (or build your own by implementing ISender). To use a sender include the provider and configure it as part of dependency injection.

The following senders are available as core libraries. The same core FluentEmail methods are used to send emails, the only difference is what sender you configure.

SMTP Sender

The SMTP sender use System.Net.Mail.SmtpClient to send email. It is set up using dependency injection. You can provide basic host and port details or a full SmtpClient instance.

dotnet add package FluentEmail.Smtp

//configure smtp sender
public void ConfigureServices(IServiceCollection services)
{
    services
       .AddFluentEmail("fromemail@test.test")
       .AddSmtpSender("yoursmtphost.com", 25) //configure host and port
       .AddSmtpSender(new SmtpClient() { }); //OR provide your own SmtpClient instance
}


//Send email as per examples above
await new Email
    .To("test@test.test")
    .Subject("Email example")    
    .Body("Email body")
    .SendAsync(); //this will use the SmtpSender

Mailgun Sender

Mailgun is an API based email sender. The FluentEmail Mailgun sender supports most functionality including attachments, tags and headers.

dotnet add package FluentEmail.Mailgun

//configure Mailgun sender
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")
        .AddMailGunSender("domainname.com", "yourapikey", FluentEmail.Mailgun.MailGunRegion.USA);
}


//Send email as per examples above
await new Email()
    .To("test@test.test")
    .Subject("Mailgun example")
    .Body("Email body")
    .Tag("tagname") //the Mailgun sender supports tags
    .SendAsync() //this will use the MailgunSender

SendGrid Sender

SendGrid is another popular API based email sender. The FluentEmail SendGrid provider can be used in "live" or "sandbox" mode.

dotnet add package FluentEmail.SendGrid

//configure SendGrid sender
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")
        .AddSendGridSender("apikey");
}

//Send emails as per examples above

MimeKit Sender

MimeKit is an open source .NET email library with support for IMAP, POP3, and SMTP. If you need to do anything advanced with email protocols you need to use MimeKit.

The MimeKit sender for FluentEmail lets you to set up whatever flavour of email sending you need and include it in the FluentEmail framework.

dotnet add package FluentEmail.MailKit

//configure MailKit sender
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddFluentEmail("fromemail@test.test")
        .AddMailKitSender(new SmtpClientOptions
        {
            Server = "server",
            Port = 25,
            Password = "password",
            UseSsl = true,
            User = "user"
        });
}

//Send emails as per examples above

Other Senders

Other people in the open source community have built and maintain senders for different email providers.

• Microsoft Graph API Sender - Microsoft Graph API Sender - https://www.nuget.org/packages/FluentEmail.Graph/
• Postmark Sender - https://www.nuget.org/packages/FluentEmail.Postmark/
• MailJet Sender - https://www.nuget.org/packages/FluentEmail.Mailjet/
• MailTrap Sender - https://www.nuget.org/packages/FluentEmail.Mailtrap/

Extending FluentEmail

FluentEmail was built to make it easy to plug in your own providers for templating and sending. If you are working on something you think belongs in the core repository head on over to the Github repo and let me know.

If you found this post useful and want to help me (and others out) please share the thread on twitter.

💡 Want more? Check out my list of 14 .NET libraries I always recommend.

Pull request validation saves time and encourages better coding practices. You can easily set up a GitHub action to validate new code by building and running tests when a new PR is created.

Create a GitHub Action to run on new pull requests

Add an action to your repository using the "Actions" tab -> New workflow on github.com or by creating a build-and-test.yml file in the .github/workflows/ directory.

Example dotnet-core.yml from FluentEmail

name: Build & Test

on:
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.101
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --configuration Release --no-restore
    - name: Test
      run: dotnet test --no-restore --verbosity normal

• The action uses the on: pull_request trigger which accepts the branches you want to run the workflow
• actions/checkout@v2 and actions/setup-dotnet@v1 are community actions that will get your code and setup dotnet
• The run steps make the calls the the dotnet cli to restore, build and test
• Be sure to run on ubuntu rather than Windows for better stability and more minutes

View status of validation on pull requests

When the action is in place you will see the validation status of all pull requests on the pull request tab. You will also see the checks inside the PR details and can prevent contributors merging pull requests with failing checks.

Check out these other GitHub Actions 👇

• Add blog posts to your GitHub profile
• Publish nuget packages to nuget.org

GitHub now allows you to add custom content to your profile page via a special repository with a readme.md file. All you need to do is create a repository named the same as your username and add a README.md file. For example my profile repo is lukencode/lukencode.

2. Update README.md

The README.md can have any valid markdown content you want. In addition to that you need a specially marked up readme-section that the action workflow below will use to inject content.

This example uses <!--START_SECTION:feed--> as the target. You can use multiple named sections.

# 👋 Hi friends! I'm Luke.

I lead tech teams and build things on the web. Currently CTO at [Endpoint IQ](https://endpointiq.com.au/'). 


### 📙 Blog Posts
<!--START_SECTION:feed-->
<!--END_SECTION:feed-->

Example readme.md

3. Create a GitHub Action workflow

Add a GitHub Action to your repository using the "Actions" tab -> New workflow on github.com or by creating a workflow.yml file in the .github/workflows/ directory. The action will be setup to run on a schedule , look for new content in an RSS feed and update readme.md in the repository.

I used JasonEtco/rss-to-readme action to read the rss. All you need to provide is an RSS endpoint for it to look for.

name: Update readme with blog posts
on: 
  schedule:
    # Once a day at 8 AM
    - cron: 0 8 * * *

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: JasonEtco/rss-to-readme@v1
        with:
          feed-url: https://lukelowrey.com/rss/
          readme-section: feed
          max: 10 # max number of items (default 5)
          template: "#### [{{ title }}]({{ link }}) \n*{{ contentSnippet }}*\n\n"

Example update-readme-rss.yml

The YAML is pretty start forward. Rather than triggering on an action like pushing to branch it uses a simple schedule and cron expression to run daily. The rss-to-readme step reads RSS from the feed-url and injects it into the marked up section with the feed key in readme.md.

The template property is optional, if you leave it out the posts will display in a simple list. You can customise the output with a {{handlebars}} style template. Under the covers the action uses rss-parser to get the content. The properties available to you when using a custom template can be found here.

The main options are:

• title
• link
• pubDate
• content
• contentSnippet

👉 TIP: change the on trigger to "push to master" for easy testing.

on:
  push:
    branches: [ master ]

🎆Success! Like clockwork the action runs, finds the latest items in RSS and updates readme.md. Check out my profile on GitHub github.com/lukencode.

GhostSolo is a free and open source Ghost theme created primarily for solo bloggers.

GhostSolo source on Github

I wanted something clean and simple that was focused around a single author writing mostly technical content. I wanted to make us of Ghost's inbuilt email newsletter and membership options. Finally, I wanted to build something flexible that others might find useful.

I have a little bit of work to go before the theme can be considered "ready for public release" but if you think you might like to try it out, feel free to contact me for help.

Features

• Clean responsive design
• Dark/light theme toggle
• The theme is customisable via CSS variables (see https://github.com/lukencode/GhostSolo#customise)
• Ghost membership support (click subscribe in the header for a live demo!)
• Curate the homepage with pinned posts using #pinned tag
• Tag pages - eg Code

Roadmap

• Better support for Ghost editor blocks (bookmark etc)
• Full paid membership support
• Post template with table of contents
• Some sort of "clips" tag option to format shorter posts. (Inspired by the awesome linear.app changelog)
• Tag listing page
• A cool animated header with the current post title
• More post curation options

Technical

GhostSolo is built on Bootstrap v5 and the Ghost Starter Theme.

I learned a lot about Ghost themes and modern frontend development while building the theme. These are posts (some coming soon) that I have written about it.

• CSS variable dark mode toggle
• How to build a custom Ghost theme
• Use Github actions to build, create and publish a release

I have been working on a custom Ghost theme to power my blog (you are looking at an early version right now!). One thing I wanted to have a crack at was a dark/light theme switcher. It turns out with modern CSS this is pretty straight forward.

The approaches I considered were:

• CSS classes set on the <body>
• Switch out style sheet entirely
• CSS variables

I went with CSS variables because my blog audience tends to be on the latest browser versions so I don't need to worry much about browser support (not that it is too bad).

If a blog post is too much for you, I managed to condense it into 4 tweets:

Using CSS variables for themes

CSS variables are properties you can set in your stylesheets that can be used in later styles. They are similar to tools such as SASS but built directly into CSS. This makes them very well suited for theming.

This is a simplified snippet from the default variables used in my theme GhostSolo.

:root {
    --background-color: #fff;
    --text-color: #121416d8;
    --link-color: #543fd7;
}

html[data-theme='light'] {
    --background-color: #fff;
    --text-color: #121416d8;
    --link-color: #543fd7;
}

html[data-theme='dark'] {
    --background-color: #212a2e;
    --text-color: #F7F8F8;
    --link-color: #828fff;
}

The :root selector is the default set of values. When <html data-theme='dark'> is set those values are overridden by the html[data-theme='dark'] values. It is really just a matter of applying the variables in your CSS to get the effect.

body {
    background: var(--background-color);
    color: var(--text-color);
}

a {
    color: var(--link-color);
}

a:hover {
    text-decoration: underline;
    filter: brightness(80%);
}

In my theme I have variables for a couple of key style choices to allow distinct colour themes beyond dark/light.

:root {
    --background-color: #fff;
    --alternate-background-color: #f7f7f9;
    --text-color: #121416d8;
    --text-color-light: #777676bb;
    --link-color: #543fd7;
    --masthead-color: #543fd7;
    --masthead-text: #fff;
    --button-color: #263238;
    --button-text: #fff;
    --bs-font-sans-serif: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
    --bs-font-serif: Georgia, serif;
    --bs-font-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}

Note: the --bs prefixed variables are CSS variables bootstrap 5 supports. The css variable support in Bootstrap is a bit limited and doesn't apply to things like .btn-primary or .bg-light.

JavaScript dark mode toggle

With the CSS theming in place I needed a simple way to switch between "dark" and "light" modes.

var toggle = document.getElementById("theme-toggle");

var storedTheme = localStorage.getItem('theme') || (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
if (storedTheme)
    document.documentElement.setAttribute('data-theme', storedTheme)


toggle.onclick = function() {
    var currentTheme = document.documentElement.getAttribute("data-theme");
    var targetTheme = "light";

    if (currentTheme === "light") {
        targetTheme = "dark";
    }

    document.documentElement.setAttribute('data-theme', targetTheme)
    localStorage.setItem('theme', targetTheme);
};

This simple JavaScript snippet will set the theme based off the user's system preferred setting using a media query for "prefers-color-scheme: dark". It will also store the value in local storage so it can be persisted across each page. The selected theme is set as a data-theme attribute on the html node.

Other CSS theming tricks

I couldn't quite get form inputs looking nice with a pure CSS variable approach. When using data attributes, you can always target them in your CSS the traditional way. This CSS gives the inputs a nice dark overlay against any background colour but didn't look right on the light theme.

[data-theme='dark'] .form-control {
    background-color: rgba(0, 0, 0, 0.6);
    border-color: rgba(0, 0, 0, 0.6);
    color: var(--text-color) !important;
}

[data-theme='dark'] .form-control:focus {
    color: var(--text-color) !important;
}

I needed to show/hide my sun moon icons in the dark mode toggle button. I went with a Bootstrap inspired display utility approach to change an element display based on the theme.

[data-theme='light'] .d-block-light,
[data-theme='dark'] .d-block-dark {
    display: block !important;
}

<button id="theme-toggle" class="btn btn-link btn-sm ml-2 small" type="button">
 <span class="d-block-light d-none">{{> "icons/moon"}}</span>
 <span class="d-block-dark d-none">{{> "icons/sun"}}</span>
</button>

See it in action

Use the sun/moon icon in the nav bar of this page to see it in action. Or just watch the gif:

References

• Dark theme in a day - Marcin Wichary - some great advanced techniques with HSL colours and transitions
• A complete guide to dark mode - CSS tricks

One of the most frustrating aspects of maintaining an open source .NET Core library has been publishing the nuget packages on nuget.org. In the world of devops automation, manually creating and uploading packages felt so old-fashioned (don't get me started on Azure Devops).

Here is how I automated pushing packages to nuget.org for FluentEmail.

1. Create a Github Action that runs on push to the master branch
2. Use Publish Nuget action to package and publish nuget packages
3. Create a Nuget.org API key and set it as a GitHub secret
4. Nuget packages are published on push to master!

Create a GitHub Action

GitHub actions makes it easy to automatically build test and deploy code hosted on GitHub. There are heaps of community built actions that cover the whole #devops spectrum.

Creating a new workflow creates a yaml file in .github/workflows for the repository. Infrastructure as code! The best way to start is create a new workflow using the .NET Core starter action.

This action sets up a simple dotnet environment. It is a great starting point for running validation builds and tests on new pull requests. For publishing packages running the action on push to the master branch works best.

Here is the full yaml for the workflow I am using. It uses actions to setup .Net Core, restore packages, build and publish nuget.

name: Publish Packages

on:
  push:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.101
    - name: Install dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --configuration Release --no-restore
    - name: Publish FluentEmail.Core
      uses: brandedoutcast/publish-nuget@v2.5.2
      with:
          PROJECT_FILE_PATH: src/FluentEmail.Core/FluentEmail.Core.csproj
          NUGET_KEY: ${{secrets.NUGET_API_KEY}}

Publish nuget package action

brandedoutcast has created a reusable GitHub Action to Publish Nuget packages. You can see it referenced in the "uses:" section in the workflow above. This action does the heavy lifting for packaging and publishing nuget packages. whenever the project version is updated. The action (by default) looks for changes to the <version>1.0</version> tag in your csproj file.

There are a couple of variables you can set to get the process working just right. For a basic setup you only really need to set PROJECT_FILE_PATH and NUGET_KEY.

The full publish-nuget variable list allows you to tweak the versioning method and format as well as target package sources other than nuget.org.

# Filepath of the project to be packaged, relative to root of repository
PROJECT_FILE_PATH: YourProject/YourProject.csproj
          
# NuGet package id, used for version detection & defaults to project name
# PACKAGE_NAME: YourProject

# API key to authenticate with NuGet server
NUGET_KEY: ${{secrets.NUGET_API_KEY}}

# NuGet server uri hosting the packages, defaults to https://api.nuget.org
# NUGET_SOURCE: https://api.nuget.org
          
# Filepath with version info, relative to root of repository & defaults to PROJECT_FILE_PATH
# VERSION_FILE_PATH: Directory.Build.props

# Regex pattern to extract version info in a capturing group
# VERSION_REGEX: <Version>(.*)<\/Version>
          
# Useful with external providers like Nerdbank.GitVersioning, ignores VERSION_FILE_PATH & VERSION_REGEX
# VERSION_STATIC: 1.0.0

# Flag to toggle git tagging, enabled by default
# TAG_COMMIT: true

# Format of the git tag, [*] gets replaced with actual version
# TAG_FORMAT: v*


# Flag to toggle pushing symbols along with nuget package to the server, disabled by default
# INCLUDE_SYMBOLS: false

Create Nuget.org API key as GitHub Action Secret

The workflow above uses the nuget API to automatically push the package. You need to create an API key for your profile on nuget.org.

You can then enter the key as a secret in your GitHub repository. The key for the secret must be NUGET_API_KEY. The API key will then be available to the publish package action workflow.

Results

Now when code is push to the master branch (and the project version changes) the publish packages action run and publishes the nuget package!

A more advanced branching and action setup would allow you to publish pre-release versions from a beta branch and full release versions from master.

If you found this useful, retweet or like the thread on twitter.

Giving product demos can be stressful and overwhelming. You need to focus on the software, your presentation and keep your potential client's needs at the front of your mind. These tips help me stay focused and deliver a confident and professional demo.

Be prepared

The most valuable step you can take to improve your product demos is preparation. I have written a demo preparation guide that outlines the research, planning and practice techniques that have helped me.

Don't go alone

It is very difficult to maintain your focus and enthusiasm for any presentation longer than half an hour. In my experience it is nearly always best to bring some backup from your team. An extra person can concentrate closely on questions, get a better read on how the demo goes, and give you a chance to catch your breath every now and then.

• Only bring people that will be able to contribute. I have found that using two presenters works well. One person takes control of the software and the other handles the introductions and company overview, and is the first call for questions.
• Each person included in the presentation should be given some space to contribute. It could be as simple as splitting the introduction and demo between you or handing off a standard technical explanation. There is nothing more awkward then sitting through an hour meeting and never having a chance to contribute.
• Try to include people to cover both business and technical expertise.

Be friendly but stick to business

It is very useful to break the ice with your audience before you kick on into the demo. My advice is to keep it simple and brief; you don't want to appear unfriendly but you also need to ensure you have time to show your software in the best light.

Mostly stick to your plan

Hopefully you have come prepared with a demo of some high-level user stories and a demo script. A demo where no one says anything is not a good sign but being peppered with questions and never getting into a groove is also an issue. You need to balance answering questions and adapting to the audience's preference with telling the story of your product the way you have planned.

• Let the audience know up front what you are going to show them. It gives them a chance to point out what is important to them and will also give them an idea of what will be shown so they don't need to jump ahead with questions.
• Always describe the software in business terms rather than technical functions. An easy way to remind yourself to do this is starting explanations with "As a [end user type] I can..."
• Stop and ask for questions at convenient spots in your presentation. For example, once you have completed some workflow.

Control your tempo

A problem that many developers have (including me) when presenting software is moving too fast. When you know the product well and have a time limit it is easy to blow through every function of the software at a million miles an hour.

• Don't try to show everything. You should spend the most time on your product's strongest features; no need to open every page.
• Deliberately pause at key discussion points. I normally mark these in my demo script. You want to leave on the screen interesting, strong features of the product as you pause and make your point.
• When you pause, take your hands completely off the keyboard and mouse. This is your cue to look at the camera or audience and speak using hand gestures.
• Go easy on the mouse. Try not to dart your mouse all over the screen. An annoying habit I need to be aware of is flicking my mouse all around the button I am talking about. Slow your mouse movement down and take your hand off completely when you talk.

Tips for presenting remotely over video

• Prepare your software and desktop. Get your product setup in its own window or tabs. Close down your chat app, email and anything else that could pop something embarrassing onto the screen.
• Share as little as possible. If you are demoing a web application, stick to the web browser. As above you want to limit the chance of oversharing.
• Keep your script on screen. If you have a big monitor and can limit your screen sharing to a single window it is very useful to keep your notes visible to the side of the main demo.
• Get the right window size and zoom level. With a big widescreen monitor sharing Fullscreen is not always the best option. Play around with window size and zoom level before the demo to find a good fit.
• Open by stating "We are looking at the homepage..." this should prompt someone to interrupt your screenshare is not working and is more natural than "can everyone see this?"
• Make sure you look at the camera. I have a habit of watching my own video feed when presenting. Because of this I tend to move my video to just below my webcam to ensure I am always facing the camera.
• Try a custom virtual background. For a simple, branded background try actionablebackground.com. If you know the audience well or have a nice office, I don't think this is necessary.

Tips for presenting in person

• Try to position yourself at the front of a meeting room (in front of the big screen) facing toward the audience.
• Pausing is your cue to look around and make eye contact. It is also a good way to encourage questions from your audience.
• Always assume the presentation equipment will be missing the cables and adaptors you need. Bring your own.
• As above, have a backup internet source ready to go.

If you enjoyed the post, like or retweet the thread on twitter.

You don't have to be a sales person to deliver a great software demonstration. I have found the key to improving the quality and consistency of my demos is research, planning and practice.  This demo preparation checklist helped me transform from rambling techie to educated and coherent domain expert.

Know your audience

I view software demonstrations similarly to job interviews; there is an expectation that you have researched the company you are presenting to and the people who will be attending. You need solid grasp of their core business and where your product fits it. It is also useful to know in advance the roles of the attendees and a little about their background. Hopefully you can save yourself the embarrassment of over explaining a point to an expert in the field. Public company websites and LinkedIn profiles are a good source of information.

Ask Questions in Advance

Send an email before the meeting to ask questions in advance. Use this information to tailor your demo. These types of questions are good options to discover the key issues:

• What are the roles and background of those attending?
• What are your top 3 pain points with your current process?
• Are you currently using any other tools in the process?

What you learn here researching your audience should then be used to fine tune the demo story and script.

Craft user stories

Before you start rattling off the product features to show in your run through, take a step back and imagine the software through a user's eyes. Those in software would be familiar with a user story. User stories help frame software requirements from the point of view of the end user. They are useful when preparing your product demo for the same reason.

A typically agile user story is formatted like this:

As a [ROLE], I want to [ACTION] (so that [BENEFIT])

The format works for planning software demos as well. The key difference is while in an agile framework the user story is the smallest unit of work in a software demo it tends to have a larger scope. Depending on how your product works it may be useful to design one story for each type of user interacting with the system.

Here are some examples I have used recently.

As a potential student, I want to apply for a research project so that I can start research at the university

As a supervisor, I want to review and progress my student projects so that my students don't miss any milestones

As a research officer, I want to ensure student projects are meeting milestones so that ....

You should have a couple of key user stories for your product that you can mix and match depending on what you know about your audience. The more familiar your demo feels the easier it is for the potential client to imagine themselves using your software in production.

I tend to pick two or three user stories to base my demos around. These stories are separate but should fit together to form the overall picture of your software. Often "data collection, "data workflow" and "reporting and analytics" flow well together.

Write a demo script

After you have a clear idea of the stories you want to tell draft a script or run sheet around them. The script needs to act as a high-level guide, not detail step by step actions to complete. When presenting as you need to be flexible with audience questions and preferences but try to act within your broad script.

If you don't know the product well enough to work off high level notes it should be someone else running the show.

Write a section for each user story you are going to cover. You should try to simulate the process that the user would take in the product.

• Don't hold back on the good stuff. Including some stronger features/screens/reports early on in your run through. You want people to be engaged early.
• Don't try to include everything. You need to spend time showing your best and most relevant features so don't feel like you need to "feature dump" every button and every screen in your plan. This is a trap that developers often fall into.
• Include "actions" in your script. You need to show the process of your software, not just what every screen looks like. Seeing data change state and move around your system is key to making it "feel real" for the audience.
• Avoid complex data entry. You should "do things" in the demo as the point above suggests but no one will enjoy watching you fumble typing for 20 minutes only to fail form validation. If it is going to take too long, have an example ready to go.

My preference is for each user story to outline each function you intend to show. Within each function I add details on how it should be delivered. I tend to colour code the details along these lines:

• Yellow is a key talking point. This is normally a specific business benefit that I want to highlight. Yellow is my cue to slow down while presenting and make sure I get my point across.
• Green is an action I need to take in the system. I normally highlight in green things like submitting forms, changing status or anything that I need to actually do (as opposed to just show) in the system to proceed.
• Purple is a detour or action outside of the main system. I often end up cross selling related products during our demos. Purple is a reminder to me to open up that other product/tab/example outside of the normal demo flow.
• Red is something I need to sort out before the demo. Things I highlight in red include missing data, questions to clarify about the client or (hopefully not) errors in the product. Red needs to be sorted well before demo time.
• Uncoloured items are general reminders on the story flow or minor talking points.

Do I need demo slides?

Slide decks are not my strong point and I am a firm believer in the "show don't tell" method. However, having some simple high-level slides ready can help structure your introductions and drive home the key benefits you are pitching.

• Introductions. Include the names and roles of the presenters from your company. This is a good reminder to actually do intros as it is something that can be missed and is awkward to pick up later on.
• Company overview. Your company's key information and mission.
• Product overview and key benefits. Include the name and logo of the product you are showing. Try to distil the top 1-3 benefits into this slide and refer to them in your script.
• [Optional] Description of the user stories you want to show. Sometimes a simple process diagram can be useful here.
• Conclusion. A slide to show at the end of the demo. Summarise the next steps and key contact details.

Demo Data

In the ideal world you configure your demo data to match the audience as closely as possible. For important demonstrations I have used publicly available client polices and documents to configure our demonstration site as closely as possible to how I envision the client would operate in production.

The bottom line is your demo data has to be good. "Test project 1" and "This is a comment" is not good enough.

Your demo data should be good enough that you not find yourself saying "this is just demo data".

You should avoid "smoke and mirrors" in your data and functionality. If you don't have good data for a report showing a screenshot is fine as long as you aren't trying to pass it off as the real deal.

Know your weaknesses

Put yourself into the shoes of your future client and ask "what is missing from this product?". You will know the software better than anyone so it shouldn't be too difficult to come up with some potential gaps. They key is to have a decent (and honest) answer to what may be lacking in your product.

Here are some ways to frame missing functionality when asked:

• Ensure you have accounted for it on your product road map. This should be something you can provide to a client if requested.
• Have an explanation for an alternative method or workaround in the system.
• Accept the question (if it comes) as important feedback and make an effort to acknowledge it in any follow up communications.
• Be confident about what is out of scope for your product

PRACTICE

Like all things in life, the more you practice the better you get. It can be tricky to find an audience for a "real" dry run of a software demo. You can fall into the trap of not selling to them because they are not a real client.

I normally go with two types of practice. One is a "simulated" run through of the demo with a team member - ideally someone who is involved in the meeting. I have my script up on screen and we step through making tweaks where necessary.

The second practice is a "live" run of the demo. This can still work well with team members, especially those not familiar with the product. Often the best candidates (and the hardest to get hold of) are in leadership and executive positions as they best emulate the decision makers that you need to convince.

Another option is to do regular internal team "functionality presentations". These work best if kept short - one user story from your plan. Internal demonstrations have the added benefit of knowledge sharing - both of the product and how to show it off effectively.

Presentation and delivery

I have written a separate post with my top product demo presentation tips. They relate closely to the preparation outlined in this post.

If you enjoyed the post, perhaps like or retweet the thread on twitter

I love bootstrap (and other css frameworks). For a developer like me who often works on web projects without any design input it is a real lifesaver.
The problem is since bootstrap is a kitchen sink type framework (although you can pick and choose via sass) the css file size can get out of hand quickly.
Bootstrap.min.css weighs in at 138 KB. If you add a theme and custom css it can easily bump you over 200 kb.

What is PurgeCSS?

PurgeCSS is a node.js package that can detect and remove unused css selectors. It will analyze your view pages - be they HTML
or a templating engine and build a list of the css selectors in use. PurgeCSS will then take your stylesheets and remove any selectors that are not
present in your views.

How to use PurgeCSS with Webpack

I setup PurgeCSS using the webpack plugin which works in conjunction with the extract-text-webpack-plugin. My webpack config
is based off the Simple webpack config I have written about previously.

The webpack config was already setup to process sass and combine css into a single file. I added the PurgecssPlugin which will run at after the initial css processing.

npm i -D purgecss-webpack-plugin

npm i -D extract-text-webpack-plugin

const path = require('path')
const glob = require('glob')
const webpack = require('webpack')
const ExtractTextPlugin = require('extract-text-webpack-plugin')
const PurgecssPlugin = require('purgecss-webpack-plugin')

const outputDir = './wwwroot/dist'
const entry = './wwwroot/js/app.js'
const cssOutput = 'site.css'

module.exports = (env) => {    
    return [{
        entry: entry,
        output: {
            path: path.join(__dirname, outputDir),
            filename: '[name].js',
            publicPath: '/dist/'
        },
        module: {
            rules: [
                {
                    test: /\.js$/,
                    use: 'babel-loader'
                },
                {
                    test: /\.css$/,
                    use: ExtractTextPlugin.extract({
                        use: ['css-loader'],
                        fallback: 'style-loader'
                    })
                },
                {
                    test: /\.scss$/,
                    use: ExtractTextPlugin.extract({
                        use: ['css-loader', 'sass-loader' ],
                        fallback: 'style-loader'
                    })
                }
            ]
        },
        plugins: [
            new ExtractTextPlugin(cssOutput),
            new PurgecssPlugin({
                paths: glob.sync('./Views/**/*.cshtml', { nodir: true }),
                whitelistPatterns: [ /selectize-.*/ ]
            })
        ]
    }]
}

The plugin accepts an array of paths to view files to search for css selectors in use. The glob package accepts a search pattern
and generates a list of files. I am looking for .cshtml view files in my .net web app.

paths: glob.sync('./Views/**/*.cshtml', { nodir: true })

Whitelist selectors

The whitelistPatterns parameter allows you to exclude selectors from the purge that may not have been present in the paths.
I found that the selectize plugin I am using has css classes that are added dynamically and were being removed
so I added a pattern to match the prefix of its css classes. I could alternatively include the .js file for this plugin with the paths parameter.

whitelistPatterns: [ /selectize-.*/ ]

Running PurgeCSS on one of my (admittedly heavy) bootstrap based web sites reduced the css file size from 159KB to 60KB with essentially no effort on my end!

If you found this post useful please like or retweet the thread on twitter.