From a654f53d4f599c136d8f157aff6356518410adf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Tue, 18 Aug 2020 21:04:21 +0300 Subject: [PATCH 1/4] Initial Emailing document. --- docs/en/Emailing.md | 118 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) diff --git a/docs/en/Emailing.md b/docs/en/Emailing.md index 75069aacbe..e588f1ddf7 100644 --- a/docs/en/Emailing.md +++ b/docs/en/Emailing.md @@ -1,3 +1,119 @@ # Emailing -TODO! \ No newline at end of file +ABP Framework provides various services, settings and integrations for email sending; + +* Provides `IEmailSender` service that is used to send emails. +* Defines [settings](Settings.md) to configure email sending. +* Integrates to the [background job system](Background-Jobs.md) to send emails via background jobs. +* Provides [MailKit](https://github.com/jstedfast/MailKit) integration package. + +## Installation + +> This package is already installed if you are using the [application startup template](Startup-Templates/Application.md). + +It is suggested to use the [ABP CLI](CLI.md) to install this package. Open a command line window in the folder of the project (.csproj file) and type the following command: + +````bash +abp add-package Volo.Abp.Emailing +```` + +If you haven't done it yet, you first need to install the ABP CLI. For other installation options, see [the package description page](https://abp.io/package-detail/Volo.Abp.Emailing). + +## Sending Emails + +### IEmailSender + +[Inject](Dependency-Injection.md) the `IEmailSender` into any service and use the `SendAsync` method to send emails. + +**Example** + +````csharp +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Emailing; + +namespace MyProject +{ + public class MyService : ITransientDependency + { + private readonly IEmailSender _emailSender; + + public MyService(IEmailSender emailSender) + { + _emailSender = emailSender; + } + + public async Task DoItAsync() + { + await _emailSender.SendAsync( + "target@domain.com", // target email address + "Email subject", // subject + "This is email body..." // email body + ); + } + } +} +```` + +`SendAsync` method has overloads to supply more parameters like; + +* **from**: You can set this as the first argument to set a sender email address. If not provided, the default sender address is used (see the email settings below). +* **isBodyHtml**: Indicates whether the email body may contain HTML tags. **Default: true**. + +#### MailMessage + +In addition to primitive parameters, you can pass a **standard `MailMessage` object** ([see](https://docs.microsoft.com/en-us/dotnet/api/system.net.mail.mailmessage)) to the `SendAsync` method to set more options, like adding attachments. + +### ISmtpEmailSender + +Sending emails is implemented by the standard `SmtpClient` class ([see](https://docs.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclient)) by default. The implementation class is the `SmtpEmailSender`. This class also expose the `ISmtpEmailSender` service (in addition to the `IEmailSender`). + +Most of the time you want to directly use the `ISmtpEmailSender` to make your code provider independent. However, if you want to create an `SmtpClient` easily with the same email settings, you can inject the `ISmtpEmailSender` and use its `BuildClientAsync` method to obtain a `SmtpClient` object and send the email yourself. + +## Queueing Emails / Background Jobs + +`IEmailSender` has a `QueueAsync` method that can be used to add emails to the background job queue to send them in a background thread. In this way, you don't take time of the user by waiting to send the email. `QueueAsync` method gets the same arguments with the `SendAsync` method. + +Queueing emails tolerates errors since the background job system has re-try mechanism to overcome temporary network/server problems. + +See the [background jobs document](Background-Jobs.md) for more about the background job system. + +## Email Settings + +Email sending uses the [setting system](Settings.md) to define settings and get the values of these settings on the runtime. `Volo.Abp.Emailing.EmailSettingNames` defines constants for the setting names, just listed below: + +* **Abp.Mailing.DefaultFromAddress**: Used as the sender's email address when you don't specify a sender when sending emails (just like in the example above). +* **Abp.Mailing.DefaultFromDisplayName**: Used as the sender's display name when you don't specify a sender when sending emails (just like in the example above). +* **Abp.Mailing.Smtp.Host**: The IP/Domain of the SMTP server (default: 127.0.0.1). +* **Abp.Mailing.Smtp.Port**: The Port of the SMTP server (default: 25). +* **Abp.Mailing.Smtp.UserName**: Username, if the SMTP server requires authentication. +* **Abp.Mailing.Smtp.Password**: Password, if the SMTP server requires authentication. +* **Abp.Mailing.Smtp.Domain**: Domain for the username, if the SMTP server requires authentication. +* **Abp.Mailing.Smtp.EnableSsl**: A value that indicates if the SMTP server uses SSL or not ("true" or "false". Default: "false"). +* **Abp.Mailing.Smtp.UseDefaultCredentials**: If true, uses default credentials instead of the provided username and password ("true" or "false". Default: "true"). + +The easiest way to define these settings it to add them to the `appsettings.json` file. The [application startup template](Startup-Templates/Application.md) already has these settings in the `appsettings.json`: + +````json +"Settings": { + "Abp.Mailing.Smtp.Host": "127.0.0.1", + "Abp.Mailing.Smtp.Port": "25", + "Abp.Mailing.Smtp.UserName": "", + "Abp.Mailing.Smtp.Password": "", + "Abp.Mailing.Smtp.Domain": "", + "Abp.Mailing.Smtp.EnableSsl": "false", + "Abp.Mailing.Smtp.UseDefaultCredentials": "true", + "Abp.Mailing.DefaultFromAddress": "noreply@abp.io", + "Abp.Mailing.DefaultFromDisplayName": "ABP application" +} +```` + +See the [setting system document](Settings.md) to understand the setting system better. + +## MailKit Integration + +TODO + +## NullEmailSender + +TODO \ No newline at end of file From c1200a845eba19e0bb36bd3e085f7cbc551c1908 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Tue, 18 Aug 2020 21:07:25 +0300 Subject: [PATCH 2/4] Added Email Sending to the document navigation menu. --- docs/en/Emailing.md | 4 ++-- docs/en/docs-nav.json | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/en/Emailing.md b/docs/en/Emailing.md index e588f1ddf7..48bddb06ac 100644 --- a/docs/en/Emailing.md +++ b/docs/en/Emailing.md @@ -1,6 +1,6 @@ -# Emailing +# Email Sending -ABP Framework provides various services, settings and integrations for email sending; +ABP Framework provides various services, settings and integrations for sending emails; * Provides `IEmailSender` service that is used to send emails. * Defines [settings](Settings.md) to configure email sending. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 03e9c7470b..c2517a208d 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -210,6 +210,10 @@ "text": "Object to object mapping", "path": "Object-To-Object-Mapping.md" }, + { + "text": "Email Sending", + "path": "Emailing.md" + }, { "text": "BLOB Storing", "items": [ From 9915fe4eae70fee6479a47a338809690eb3be667 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Tue, 18 Aug 2020 21:43:39 +0300 Subject: [PATCH 3/4] Added Text Template Integration section --- docs/en/Emailing.md | 109 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/docs/en/Emailing.md b/docs/en/Emailing.md index 48bddb06ac..2b1ae1b698 100644 --- a/docs/en/Emailing.md +++ b/docs/en/Emailing.md @@ -110,6 +110,115 @@ The easiest way to define these settings it to add them to the `appsettings.json See the [setting system document](Settings.md) to understand the setting system better. +## Text Template Integration + +ABP Framework provides a strong and flexible [text templating system](Text-Templating.md). You can use the text templating system to create dynamic email contents. Inject the `ITemplateRenderer` and use the `RenderAsync` to render a template. Then use the result as the email body. + +While you can define and use your own text templates, email sending system provides two simple built-in text templates. + +**Example: Use the standard and simple message template to send emails** + +````csharp +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Emailing; +using Volo.Abp.Emailing.Templates; +using Volo.Abp.TextTemplating; + +namespace Acme.BookStore.Web +{ + public class MyService : ITransientDependency + { + private readonly IEmailSender _emailSender; + private readonly ITemplateRenderer _templateRenderer; + + public MyService( + IEmailSender emailSender, + ITemplateRenderer templateRenderer) + { + _emailSender = emailSender; + _templateRenderer = templateRenderer; + } + + public async Task DoItAsync() + { + var body = await _templateRenderer.RenderAsync( + StandardEmailTemplates.Message, + new + { + message = "This is email body..." + } + ); + + await _emailSender.SendAsync( + "target-address@domain.com", + "Email subject", + body + ); + } + } +} +```` + +The resulting email body will be shown below: + +````html + + + + + + + This is email body... + + +```` + +Emailing system defines the built-in text templates with the given names: + +"**Abp.StandardEmailTemplates.Message**" is simplest template that has a text message: + +````html +{{model.message}} +```` + +This template uses the "Abp.StandardEmailTemplates.Layout" as its layout. + +"**Abp.StandardEmailTemplates.Layout**" is a simple template to provide an HTML document layout: + +````html + + + + + + + {{content}} + + +```` + +The final rendered message was shown above. + +> These template names are contants defined in the `Volo.Abp.Emailing.Templates.StandardEmailTemplates` class. + +### Overriding/Replacing the Standard Templates + +You typically want to replace the standard templates with your own ones, so you can prepare a branded email messages. To do that, you can use the power of the [virtual file system](Virtual-File-System.md) (VFS) or replace them in your own template definition provider. + +Pathes of the templates in the virtual file system are shown below: + +* `/Volo/Abp/Emailing/Templates/Layout.tpl` +* `/Volo/Abp/Emailing/Templates/Message.tpl` + +If you add files to the same localization in the virtual file system, your files will override them. + +Templates are inline localized, that means you can take the power of the [localization system](Localization.md) to make your templates multi-cultural. + +See the [text templating system](Text-Templating.md) document for details. + +> Notice that you can define and use your own templates for your application, rather than using the standard simple templates. These standard templates are mostly for reusable modules where they don't define their own templates but rely on the built-in ones. This makes easy to customize emails sent by the used modules, by just overriding the standard email layout template. + ## MailKit Integration TODO From d5475dce93c624db4c2770ea1a7dd83455c7da7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Tue, 18 Aug 2020 21:52:26 +0300 Subject: [PATCH 4/4] Finalize the emailing document --- docs/en/Emailing.md | 20 +++++++++++++++----- docs/en/MailKit.md | 3 +++ docs/en/docs-nav.json | 11 ++++++++++- 3 files changed, 28 insertions(+), 6 deletions(-) create mode 100644 docs/en/MailKit.md diff --git a/docs/en/Emailing.md b/docs/en/Emailing.md index 2b1ae1b698..d0eee20bb1 100644 --- a/docs/en/Emailing.md +++ b/docs/en/Emailing.md @@ -5,7 +5,7 @@ ABP Framework provides various services, settings and integrations for sending e * Provides `IEmailSender` service that is used to send emails. * Defines [settings](Settings.md) to configure email sending. * Integrates to the [background job system](Background-Jobs.md) to send emails via background jobs. -* Provides [MailKit](https://github.com/jstedfast/MailKit) integration package. +* Provides [MailKit integration](MailKit.md) package. ## Installation @@ -219,10 +219,20 @@ See the [text templating system](Text-Templating.md) document for details. > Notice that you can define and use your own templates for your application, rather than using the standard simple templates. These standard templates are mostly for reusable modules where they don't define their own templates but rely on the built-in ones. This makes easy to customize emails sent by the used modules, by just overriding the standard email layout template. -## MailKit Integration +## NullEmailSender -TODO +`NullEmailSender` is a built-in class that implements the `IEmailSender`, but writes email contents to the [standard log system](Logging.md), rathen than actually sending the emails. -## NullEmailSender +This class can be useful especially in development time where you generally don't want to send real emails. The [application startup template](Startup-Templates/Application.md) already uses this class in the **DEBUG mode** with the following configuration in the domain layer: + +````csharp +#if DEBUG + context.Services.Replace(ServiceDescriptor.Singleton()); +#endif +```` + +So, don't confuse if you don't receive emails on DEBUG mode. Emails will be sent as expected on production (RELEASE mode). Remove these lines if you want to send real emails on DEBUG too. + +## See Also -TODO \ No newline at end of file +* [MailKit integration for sending emails](MailKit.md) \ No newline at end of file diff --git a/docs/en/MailKit.md b/docs/en/MailKit.md new file mode 100644 index 0000000000..e98a81454f --- /dev/null +++ b/docs/en/MailKit.md @@ -0,0 +1,3 @@ +# MailKit Integration + +TODO! \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index c2517a208d..5e0313bf1e 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -212,7 +212,16 @@ }, { "text": "Email Sending", - "path": "Emailing.md" + "items": [ + { + "text": "Email Sending System", + "path": "Emailing.md", + }, + { + "text": "MailKit Integration", + "path": "MailKit.md", + } + ] }, { "text": "BLOB Storing",