Facteur 1.1.2

There is a newer version of this package available.
See the version list below for details.
dotnet add package Facteur --version 1.1.2                
NuGet\Install-Package Facteur -Version 1.1.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Facteur" Version="1.1.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Facteur --version 1.1.2                
#r "nuget: Facteur, 1.1.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Facteur as a Cake Addin
#addin nuget:?package=Facteur&version=1.1.2

// Install Facteur as a Cake Tool
#tool nuget:?package=Facteur&version=1.1.2                

<p align="center"><img src="https://raw.githubusercontent.com/dimesoftware/facteur/master/assets/facteur.svg?raw=true" width="350" alt="Logo"></p>

<h1 align="center"> Facteur </h1>

<p align="center"> <img src="https://img.shields.io/azure-devops/build/dimesoftware/utilities/177?style=flat-square" /> <img src='https://img.shields.io/azure-devops/tests/dimesoftware/utilities/177?compact_message&style=flat-square' /> <img src="https://img.shields.io/nuget/v/facteur?style=flat-square" /> <img src="https://img.shields.io/azure-devops/coverage/dimesoftware/utilities/177?style=flat-square" /> <a href="https://codeclimate.com/github/dimesoftware/facteur/maintainability"><img src="https://api.codeclimate.com/v1/badges/7d604cce096ee94210a6/maintainability" /></a> <img src="https://img.shields.io/badge/License-MIT-brightgreen.svg?style=flat-square" /> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" /> <a href="https://github.com/dimesoftware/facteur/discussions"> <img src="https://img.shields.io/badge/chat-discussions-brightgreen?style=flat-square"> </a> <a href="https://gitter.im/facteur-dotnet/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge"><img src="https://img.shields.io/badge/chat-on%20gitter-brightgreen.svg?style=flat-square" /></a>

</p>

Facteur (French for mailman) is a library for sending e-mails 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 e-mail request, which contains the e-mail variables like subject, body and the e-mail addresses to send the mail to.

Compilers are a part of the e-mail composition in that it allows to fetch a template and populate the e-mail 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. E-mails 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 e-mail. The following packages are available:

Resolvers Command
RazorEngine dotnet add package Facteur.Compilers.Razor
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 MailBodyBuilder class, which orchestrates the process of retrieving and populating the template. It is ultimately up to the instance of the IMailer to actually send the e-mail.

public async Task SendConfirmationMail(string customerMail, string customerName)
{
  EmailComposer<TestMailModel> composer = new EmailComposer<TestMailModel>();
  EmailRequest<TestMailModel> request = composer
      .SetModel(new TestMailModel { Email = customerMail, Name = customerMail })
      .SetSubject("Hello world")
      .SetFrom("info@facteur.com")
      .SetTo("guy.gadbois@facteur.com")
      .SetCc("jacques.clouseau@facteur.com")
      .SetBcc("charles.dreyfus@facteur.com")
      .Build();

  IMailBodyBuilder builder = new MailBodyBuilder(
   new ScribanCompiler(),
   new AppDirectoryTemplateProvider("Templates", ".sbnhtml"),
   new ViewModelTemplateResolver());

  EmailRequest populatedRequest = await builder.BuildAsync(request);

  SmtpCredentials credentials = new("smtp.gmail.com", "587", "false", "true", "myuser@gmail.com", "mypassword");
  IMailer mailer = new SmtpMailer(credentials);
  await mailer.SendMailAsync(populatedRequest);
}

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 IMailBodyBuilder 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 is as simple as adding one line in the Startup class:

services.AddMailer<SmtpMailer, ScribanCompiler, AppDirectoryTemplateProvider, ViewModelTemplateResolver>(
  mailerFactory: x => new SmtpMailer(credentials),
  templateProviderFactory: x => new AppDirectoryTemplateProvider("Templates", ".sbnhtml")
);
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  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 was computed.  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 was computed.  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. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETFramework 4.6.1

    • No dependencies.
  • .NETStandard 2.1

    • No dependencies.
  • net5.0

    • No dependencies.
  • net6.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
3.0.0-alpha.1 128 11/13/2024
2.1.0 2,517 7/8/2024
2.0.0 414 3/22/2024
1.2.0 6,228 8/30/2023
1.2.0-beta.1 96 8/30/2023
1.1.2 8,273 11/14/2021
1.1.1 1,538 10/22/2021
1.1.0 1,888 4/27/2021
1.0.1 1,353 4/7/2021
1.0.0 1,349 4/7/2021
1.0.0-beta.9 463 2/16/2021
1.0.0-beta.8 159 2/15/2021
1.0.0-beta.7 160 2/15/2021