Updated 2021-12-31: Updated to .NET 6.0 and Mailkit 3.0

Updated 2021-02-14: Updated to .NET 5.0 and latest Mailkit

Updated 2020-06-20: Update for new Razor Class Library options for “support pages and views” option that is required for this to work.

Updated 2020-04-18: As of .NET Core 3, ASP.NET Core targets .NET Core directly, instead of .NET Standard.  This means you cannot use a .NET Standard Class Library and reference ASP.NET Core.  Please see this repo for an example of getting Razor Emails working with .NET Core 3.1.  This post has been updated to just reference a .NET Core Library instead of .NET Standard Library.

tldr;

• View the GitHub repo here
• Create a new ASP.NET Core Web Application or use an existing one
• Create a Razor Class Library
• Create a new class for the RazorViewToStringRenderer to turn Razor into an HTML String
• Create your base EmailLayout.cshtml
• Create a re-usable EmailButton.cshtml partial view
• Create your HTML email utilizing EmailLayout.cshtml and EmailButton.cshtml
• Create a .NET Core Class Library
• Call the RazorViewToStringRenderer from that Class Library and get the HTML back
• Send that HTML in an Email
• Cry happy tears that HTML Emails is slightly less painful and looks half-way decent like this:

Full Code: https://github.com/scottsauber/RazorHtmlEmails

 

Usually I don’t blog walkthroughs and instead prefer to go a little deeper on a small topic, but I thought it would be useful to blog our approach on generating HTML emails using Razor for an ASP.NET Core insurance application at work.

 

If you’re looking to generate HTML Emails outside of ASP.NET Core (such as a Console app), I also recommend checking out Derek Comartin‘s post: Using Razor in a Console Application (outside of ASP.NET Core MVC).

 

Purpose

HTML emails are the absolute worst.  Inlined styles.  Nested tables.  Different apps and platforms render the markup differently.  It’s an absolute train wreck.  However, sending plain text emails isn’t a great way to impress your users and often makes emails look fake or like spam.  So fine, HTML emails.  Let’s do it.

 

What I would like to do is create an HTML Email Template library, and let developers focus on the content of their email, and not worry about the extra HTML and CSS voodoo that is HTML Emails.

 

Also, I want to be able to generate these HTML Emails from within a .NET Class Library, so that the sending of the emails happens right next to all my other business logic.  That way I can re-purpose this logic into an ASP.NET Core app or a .NET Console app (such as a Worker Service).

 

So at a high level, the requirements are:

1. Create a base Email Layout to enforce a consistent layout (Header, Footer, base styles, etc.) and to hide the complexity of HTML Email Layouts.
2. Create re-usable HTML Email components (such as buttons) to enforce consistent styling and hide the complexity of the implementation of the HTML Email components.
3. Use Razor.
4. Be able to call it from a .NET Core Class Library.

 

Razor checks the box for #1, because it already has the concept of a Layout view and a child view.  It also is a good fit for #2, because it lets you re-use UI components via Partials (among other methods).  In fact, you can actually achieve #1, #2, and #3 in regular ASP.NET 4.x fairly easily.  However, I haven’t ever been able to achieve #4 in regular ASP.NET or pre-2.1 ASP.NET Core.  That is, I want to use Razor in a non-ASP.NET/ASP.NET Core setting such as Class Libraries.

 

It’s super common for applications to put their business logic in a Class Library to remove any dependency on the UI project and to allow that logic to be re-used across other applications.  However, when I tried to send HTML Emails from a Class Library in ASP.NET 4.x and ASP.NET Core pre-2.1, I couldn’t figure out how to get the Class Library to find the Views I was creating and ultimately I gave up.

 

Enter Razor Class Libraries

I won’t go into much detail about Razor Class Libraries, when the documentation already does a fantastic job, but the basic idea behind them is that you can share UI between multiple ASP.NET Core applications.  This UI can be Views, Controllers, Razor Pages, etc.

 

The simplest way to think about Razor Class Libraries is if you add a View in your Razor Class Library, it essentially gets copied down into that same relative path into your main application.  So if you add an Index.cshtml file to the /Views/Home path of your Razor UI Class Library, then that file will be available at /Views/Home/Index.cshtml of your ASP.NET Core Application.  That’s pretty sweet and useful. But the question is would it find those files in a normal .NET Core Class Library?  The answer is – yes.

 

One potential gotcha: Make sure that your Views have unique names/paths.  If you make an HTML Email view that matches the path of an actual like MVC View or Razor Page, then they will conflict.  Therefore, I try to make my folder and/or view names clearly unique like “ConfirmAccountEmail.cshtml” which is unlikely to have a matching route on my ASP.NET Core application.

 

Alright then, let the walkthrough begin!

Again – all code can be found here on GitHub

Create an ASP.NET Core Web Application

First – create an ASP.NET Core Web Application or you can use an existing ASP.NET Core Web App.  It doesn’t really matter what it is.

With Visual Studio:

1. File
2. New Project
3. ASP.NET Core Web Application
   1. I just called it RazorHtmlEmails.AspNetCore
4. Web Application
5. OK

 

Or with the command line:

1. dotnet new sln -n RazorHtmlEmails
2. dotnet new razor -n RazorHtmlEmails.AspNetCore
3. dotnet sln RazorHtmlEmails.sln add RazorHtmlEmails.AspNetCore

 

 

Create a Razor Class Library

Next – create an ASP.NET Core Razor Class Library.

With Visual Studio:

1. Right-click the Solution
2. Add
3. New Project
4. Razor Class Library
5. Next
6. Give it a name, I just called it RazorHtmlEmails.RazorClassLib
7. Create
8. Check the box for “Support pages and views” in the bottom right
   1. 
9. Create

 

Or… with the command line (NOTE: the -s for “support pages and views”):

1. dotnet new razorclasslib -n RazorHtmlEmails.RazorClassLib -s
2. dotnet sln RazorHtmlEmails.sln add RazorHtmlEmails.RazorClassLib

 

After you’ve created your Razor Class Library, delete out the Areas folder, because we won’t need it.

 

Create the RazorViewToStringRenderer class

Tucked away in the aspnet/Entropy GitHub repo is the RazorViewToStringRenderer which shows you how to take a Razor View and render it to an HTML string.  This will be perfect for taking our Razor View, converting it to a string of HTML, and being able to stick the HTML into the body of an email.

 

Add this class to your Razor Class Library you just created.  I tucked mine under a folder called Services and then created an Interface for it called IRazorViewToStringRenderer:

 

Create your base HTML Email Layout

The next step in the process is we are going to leverage Razor’s Layout system to create a base HTML Email Layout.  There are many HTML Email Layout templates out there so you don’t have to write one yourself (and trust me… if you’ve never seen HTML Email code before, you’re not going to want to write this yourself).

I’m picking this one from Litmus, which is the leading vendor  (as far as I know) for testing your HTML Emails on multiple different platforms, devices, and applications.  No they didn’t pay me to say that (although if someone from Litmus is reading this, it’d be cool if you did).

The layout looks like this:

 

However, all I really care about for the layout is everything outside of the white box for my layout.  Inside the white box will change based on whatever I’m sending (Email Registration Confirmations, Forgot Password requests, Password Updated Alerts, etc.).

 

Steps:

1. In your Razor UI Class Library, create a /Views/Shared folder
2. Add an EmailLayout.cshtml to that folder
3. Add the following code and try not to pass out

 

When you finish throwing up in your mouth, let’s look at a couple important bits. Line 165 has the RenderBody() call which is where the white box is and where our child view will be placed dynamically based on the email I’m sending.

 

Another interesting spot is line 142 where I’m dynamically pulling an EmailTitle property from ViewData.  ViewData allows us to pass messages from a child view up to the parent view.  In the email screenshot above, this is the “Welcome” hero text.

 

 

In a real application, I would have pulled that Welcome text down to the child view as well, but I left that as a demonstration of the ability for the child view to dynamically change the parent EmailLayout.  Some more examples of what you could do with ViewData could be the child view wants to dictate which Logo to use or what color the background is, or literally anything you want.  This is simply just leveraging a feature that’s been part of MVC for a long time.

 

Now that we’ve finished the Email Layout, let’s look at adding a custom button component.

 

 

Create a HTML Email Button Partial for re-usability

The next thing I want to do is start to make reusable components via partial views in order to abstract away the complexity of certain HTML Email components, as well as always providing a consistent look to the end user.

 

A good example of this is the button:

 

All that really needs to be dynamic about this is the text and the link. That should be easy enough.

Steps:

1. Under /Views/Shared add a EmailButtonViewModel.cs record
2. Add the following code:

3. Add an EmailButton.cshtml file
4. Add the following code:

 

Now we can re-use buttons in our child views by simply doing this:

That saves us from copying and pasting that crazy table code around every time we need a button for our Emails, which is useful.

 

Create your HTML Email Content

Now we’ve got all of our foundation pieces in place, let’s start building on top of them. The last thing we need to do in our Razor Class Library is add our custom email.

 

1. Add a new folder under Views called Emails. This folder will house all of our custom HTML Emails.
2. Add a _ViewStart.cshtml and add the following code so that every HTML Email has the EmailLayout.cshtml we created above as its parent layout

3. Add a ConfirmAccount folder under /Views/Emails.  This folder will house our ConfirmAccount email logic.

4. Add a ConfirmAccountEmailViewModel.cs record with the following code:

5. Add a ConfirmAccount.cshtml file with the following code:

Right now is where it all starts to come together, and you can see the power of being able to use Razor to build out our HTML emails.  On our day-to-day emails that we build out for the rest of our application, we no longer have to worry about gross table syntax or inline style craziness, we can just focus on the custom content that makes up that HTML Email.

 

Create a .NET Core Class Library

But one of the coolest things about this, is the fact that we can call this code from regular .NET Core) Class Libraries, and have it all “just work.”  This means we can share our email templates across multiple applications to provide the same look and feel across all of them, and have all that logic live right next to the rest of our business logic.

 

So let’s create a .NET Core Class Library.  If you want you can create a .NET Core Library and it’ll work as well.

With Visual Studio:

1. Right-click the Solution
2. Add
3. New Project
4. Class Library (.NET Core)
   1. I just called it RazorHtmlEmails.Common
5. OK

 

Or with the command line:

1. dotnet new classlib -n RazorHtmlEmails.Common
2. dotnet sln RazorHtmlEmails.sln add RazorHtmlEmails.Common

 

Then delete out Class1.cs

 

Call the RazorViewToStringRenderer in your business logic

Now it’s time to hook up the .NET Core Class Library to the Razor Class Library.

1. In the .NET Core Class Library (.Common), add a reference to the Razor Class Library (.RazorEmailLib)
2. Install MailKit, a fantastic cross-platform, .NET Core-friendly email library
3. Create a class called RegisterAccountService that will house our business logic for creating the account and sending the email.

The interesting bits are lines 25, where we create our ConfirmAccountEmailViewModel with the link we want to use and line 27 where we pass that model into our RazorViewToStringRenderer, and get back our Email’s HTML body.

As an aside, for testing local emails without an email server, I love using Papercut.  It’s a simple install and then you’re up and going with an email server that runs locally and also provides an email client.  No Papercut didn’t pay me to say that either.  It’s free.  If some paid service that does the same thing as Papercut does and wants to sponsor this blog, feel free to reach out to me and get rejected because you will never get me to give up Papercut.

 

Hook it up to the UI

The last step we have to do is to hook this up to the UI.  I’m just going to hook this up on a GET request of the /Index page just for demo purposes.  In reality, you’d have an input form that takes registration and have this happen on the POST.

1. In your .AspNetCore project, add a project reference to .Common
2. Wire up the IRegisterAccountService and IRazorViewToStringRenderer to ther implementations.
3. If using the Minimal Hosting Model, then add the following: 

      4. If using the Startup.cs Hosting Model then add the following to the ConfigureServices method:

5. In /Pages/Index.cshtml.cs, call the IRegisterAccountService in the OnGetAsync method

 

 

And you’re done!  When I run the app, and open up Papercut, I get my email in all its glory.

Going forward, anytime I need an email, I can simply leverage the EmailLayout and EmailButton infrastructure I’ve created to make creating HTML emails incredibly easy and less table-y which is a huge win.

 

Just a reminder if somehow you’ve made it this far, all the code is out here on GitHub.

 

Hope this helps!