Use Razor syntax to write emails, compatible with .NET Core.
DotNet Core only allows reflection on projects that have the preserveCompilationContext
enabled. This is a requirement
of the RazorLight
library which this project uses for the default template generator.
To enable this setting, open up your project.json
file for your project (the executing project) and add the following:
"buildOptions": {
"preserveCompilationContext": true
// ...
},
The base path is configured via an Environment variable named BaseTemplatePath
. This path is either relative to the executing
project or can be an absolute path. In Visual Studio you can set an Environment variable by going into the project properties,
Debug tab, and adding the value to the Environment variables section.
Example: BaseTemplatePath
=> RazorEmail
<BaseTemplatePath>\settings.json
contains the base configuration file (can be named something else .json
)
<BaseTemplatePath>\TemplateName\TemplateName.json
contains the template override settings file (optional)
<BaseTemplatePath>\TemplateName\TemplateName.razor
contains a razor template to produce an HTML mail message content (optional)
<BaseTemplatePath>\TemplateName\TemplateName.text
contains a razor template to produce a plain text mail message content (optional)
Either the .razor
file or the .text
file must exist. You can also supply both to support email messages with both content types.
Note: The name of the file is unimportant, there just needs to be only one .json
file, .razor
or .text
file each!
A .json
file is required in <BaseTemplatePath>
to serve as the master settings for all templates. The idea is that default settings are kept here, and templates will override them if needed. Settings like subject
will usually be overridden, but settings like server
, username
, and password
will usually be defined once.
This configuration takes the format of the example below:
{
"from": "\"RazorEmailCore\" <donotreply@SomeDomain.com>",
"subject": "New User Created",
"cc": "",
"bcc": "nate.zaugg@SomeDomain.com;joe@go.com",
"server": "smtp://smtp.sendgrid.net:587",
"username": "",
"password": ""
}
As with any credentials in a project, we recommend not committing them to your source control.
Templates may override settings in the Base Configuration by adding their own .json
file of the same format as the Base Configuration.
// Simple Example
var razoremail = new RazorEmail();
razoremail.CreateAndSendEmail("nate.zaugg@SomeDomain.com", "NewUserTemplate",
new { Name = "Nate Zaugg" });
Console.WriteLine("Message sent successfully!");
// {BaseTemplatePath}/NewUserTemplate/NewUserTamplate.razor
<h1>Hello @Model.Name!</h1>
<p>We're pleased you have decided to sign up with us today...</p>
// {BaseTemplatePath}/NewUserTemplate/NewUserTamplate.text
Hello @Model.Name!
We're pleased you have decided to sign up with us today...
You may also generate the message and then send it later (example with error handling):
// Full Example with Separate Create and send email steps
try
{
var emailBuilder = new RazorEmail();
var email = emailBuilder.CreateEmail("NewUserTemplate", new { Name = "Nate Zaugg" });
// Modify the email
email.Sender = "\"Nate Zaugg\" <nate.zaugg@SomeDomain.com>";
// ...
// Send the email
emailBuilder.SendEmail(email);
}
catch (RazorEmailCoreConfigurationException rece)
{
Console.WriteLine($"Failed to generate message because of configuration error with RazorEmailCore! {rece}");
}
catch (MessageGenerationException mge)
{
Console.WriteLine($"Failed to generate email message because of a problem with the razor template! {mge}");
}
catch (SmtpException smtpEx)
{
Console.WriteLine($"Failed to send email message because of an SMTP error! {smtpEx}");
}
catch (Exception ex)
{
Console.WriteLine($"Failed to generate or send email because of an unknown error {ex}");
}
Console.WriteLine("Message sent successfully!");
You may also send emails asyncroniously:
// Async Simple Example
await new RazorEmail().CreateAndSendEmailAsync("nate.zaugg@somedomain.com", "NewUserTemplace", new { Name = "Nate Zaugg" });
This library was designed to have its main modules replaced or extended based on the needs of the user. Below is a summary of the main interfaces.
This class is used to generate the settings required to generate the message content and later send the message.
It returns a ConfigSettings
class that can be inherited and expanded.
This class must provide:
- Either the
HtmlEmailTemplate
or thePlainTextEmailTemplate
values - The
Subject
for the email - The
From
sender for the email - The
Server
in URI format (e.g.smtp://smtp.sendgrid.net:587
) - Optional login information
Username
andPassword
for the SMTP server - Optional
Cc
,Bcc
values
Note: The default option for this class is the built-in DefaultMessageSettingsProvider
class
This class is used to generate the content of the mail message from the template and the model data provided. It is given the template text and the model and returns the generated output.
Note: The default option for this class is the built-in RazorMessageGenerator
class which makes use of the RazorLight
library
This class sends the Email
object based on the config settings collected by the IMessageSettingsProvider
class.
Note: The default option for this class is the built-in SmtpSendEmailProvider
class which is a very simple SMTP client
that currently only supports basic auth. There is no support for SSL or TSL.
There is a base interface for the RazorEmail
class called IRazorEmail
which can be helpful in dependency injection scenerios.
The constructor of the RazorEmail
class provides the following prototype:
public RazorEmail(IMessageSettingsProvider settingsProvider = null, IMessageGenerator messageGenerator = null, ISendEmailProvider sendEmailProvider = null)
If you wished to replace just one of the default providers with a custom provider, you could do it like this:
var emailBuilder = new RazorEmail(sendEmailProvider: sendgridEmailProvider);
//...
This project is available under the MIT license.
Copyright (c)2016 Mindfire Technology
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
This software also depends on RazorLight
project found at https://github.com/toddams/RazorLight
for the default RazorMessageGenerator
class and is licensed under the Apache 2 License.