Facteur 2.1.0
dotnet add package Facteur --version 2.1.0
NuGet\Install-Package Facteur -Version 2.1.0
<PackageReference Include="Facteur" Version="2.1.0" />
paket add Facteur --version 2.1.0
#r "nuget: Facteur, 2.1.0"
// Install Facteur as a Cake Addin #addin nuget:?package=Facteur&version=2.1.0 // Install Facteur as a Cake Tool #tool nuget:?package=Facteur&version=2.1.0
![alternate text is missing from this package README image](https://raw.githubusercontent.com/dimesoftware/facteur/master/assets/facteur.svg?raw=true =250)
Facteur
Facteur (French for mailman) is a library for sending emails in .NET. Its modular approach allows you to assemble a mail system rather than having to use a take-it-or-leave it service.
Check out the 📚 docs » for more info.
About the project
The entire premise of this project is to provide a flexible and modular mailing and templating kit. Applications should not be bound by one specific mailing service; like when you get blacklisted by a mailing service or when the performance is unacceptable, you should be able to swap providers without having to modify a single line of code.
This is why we created Facteur. The desire to create a flexible and vendor-independent framework is clearly reflected in the library's architecture.
There are a few moving parts:
- Composers
- Compilers
- Resolvers
- Template providers
- Endpoints
Composers enable you to create an email request, which contains the email variables like subject, body and the email addresses to send the mail to.
Compilers are a part of the email composition in that it allows to fetch a template and populate the email body with data from a custom view model.
The templates can be stored anywhere. By default they are stored in the folder where the application is hosted but it can also be retrieved from an Azure blob, FTP drive, etc. Using template providers and resolvers, you can write your own logic to fetch the right template for the job.
Lastly and obviously, there are the various mail services, also known as endpoints in Facteur. emails can be sent with good old SMTP, Microsoft Graph API, SendGrid, etc.
Installation
Use the package manager NuGet to install the base library of Facteur:
dotnet add package Facteur
Next it is up to you to decide which endpoint you want to use:
Service | Command |
---|---|
Microsoft Graph API | dotnet add package Facteur.MsGraph |
SMTP | dotnet add package Facteur.Smtp |
SendGrid | dotnet add package Facteur.SendGrid |
Next, you should decide which compiler to use to generate the body of your email. The following packages are available:
Resolvers | Command |
---|---|
Scriban | dotnet add package Facteur.Compilers.Scriban |
You also have a choice in the template providers. Templates can be stored on a regular file drive but it might as well be stored on a blob on Azure.
Providers | Command |
---|---|
IO | dotnet add package Facteur.TemplateProviders.IO |
The resolvers are the glue between the storage of templates and the runtime. Resolvers enable you to map templates to models.
Resolvers | Command |
---|---|
View | dotnet add package Facteur.Resolvers.ViewModel |
Finally, there are some ancillary packages:
Purpose | Command |
---|---|
.NET Core DI | dotnet add package Facteur.Extensions.DependencyInjection |
Usage
The power of this project is to create a dynamic mail body as you can populate any template with any type of data. This is when the compilers, providers and resolvers come in. They can be produced using the implementation of IEmailCompiler
, which orchestrates the process of retrieving and populating the template. It is ultimately up to the instance of the IMailer
to actually send the email.
public async Task SendConfirmationMail(string customerMail, string customerName)
{
EmailComposer composer = new(
new ScribanCompiler(),
new AppDirectoryTemplateProvider("Templates", ".sbnhtml"),
new ViewModelTemplateResolver());
EmailRequest request = await composer
.Subject("Hello world")
.From("info@facteur.com")
.To("guy.gadbois@facteur.com")
.Cc("jacques.clouseau@facteur.com")
.Bcc("charles.dreyfus@facteur.com")
.BuildAsync(new TestMailModel { Email = customerMail, Name = customerMail });
SmtpCredentials credentials = new("smtp.gmail.com", "587", "false", "true", "myuser@gmail.com", "mypassword");
IMailer mailer = new SmtpMailer(credentials);
await mailer.SendMailAsync(request);
}
If you use DI, you can just use IMailer
and use the overload that exposes the composer:
public async Task SendConfirmationMail(string customerMail, string customerName)
{
await mailer.SendMailAsync(x => x
.Subject("Hello world")
.From("info@facteur.com")
.To("guy.gadbois@facteur.com")
.Cc("jacques.clouseau@facteur.com")
.Bcc("charles.dreyfus@facteur.com")
.BuildAsync(new TestMailModel { Email = customerMail, Name = customerMail }));
}
This particular example uses scriban templates that are stored inside the application's directory. Inside the HTML template, you will find scriban syntax:
<p>Hi {{name}},</p>
This text template is resolved using the model that is passed to the EmailRequest
instance, which in this sample is of the TestMailModel
type:
public class TestMailModel
{
public string Name { get; set; }
public string Email { get; set; }
}
The resolver is responsible for locating the right file name. In this example, the ViewModelTemplateResolver
is used. This class essentially strips the 'MailModel' or 'ViewModel' of the name of the mail request's model. After that, the provider (AppDirectoryTemplateProvider
) will make the system to look for file in the application's Templates
directory with the .sbnhtml file and with the name 'Test' (from TestMailModel).
The IEmailComposer
brings everything together and generates a populated mail body. Then it's up to the ÃŒMailer
to merely send the mail.
With .NET's dependency injection, hooking up the mailer can be done by adding a few lines to the Startup class:
serviceCollection.AddFacteur(x =>
{
x.WithMailer(y => new SmtpMailer(credentials, y.GetService<IEmailComposer>()))
.WithCompiler<ScribanCompiler>()
.WithTemplateProvider(x => new AppDirectoryTemplateProvider("Templates", ".sbnhtml"))
.WithResolver<ViewModelTemplateResolver>()
.WithDefaultComposer();
});
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- No dependencies.
-
net7.0
- No dependencies.
-
net8.0
- No dependencies.
NuGet packages (9)
Showing the top 5 NuGet packages that depend on Facteur:
Package | Downloads |
---|---|
Facteur.TemplateProviders.IO
Store and retrieve email templates in local Windows directories |
|
Facteur.Resolvers.ViewModel
Map and resolve email templates using the view model type names |
|
Facteur.Compilers.Scriban
Create email bodies using the Scriban template engine. |
|
Facteur.SendGrid
Send emails using the SendGrid endpoint |
|
Facteur.Extensions.DependencyInjection
ASP.NET Core extensions for facteur. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.1.0 | 973 | 7/8/2024 |
2.0.0 | 344 | 3/22/2024 |
1.2.0 | 6,159 | 8/30/2023 |
1.2.0-beta.1 | 84 | 8/30/2023 |
1.1.2 | 8,154 | 11/14/2021 |
1.1.1 | 1,427 | 10/22/2021 |
1.1.0 | 1,763 | 4/27/2021 |
1.0.1 | 1,251 | 4/7/2021 |
1.0.0 | 1,237 | 4/7/2021 |
1.0.0-beta.9 | 452 | 2/16/2021 |
1.0.0-beta.8 | 147 | 2/15/2021 |
1.0.0-beta.7 | 143 | 2/15/2021 |