Developing Your Custom Notification
Overview
This guide describes how to define notificationss and notification predefinitions, and how to send them.
Registering Your Own Notification
To register a new notification, do the following:
-
Create a notification and give it a name (e.g.,
SampleEmailNotification
), basing it on theEmailNotification
class (there is also another standard class,SmsNotification
):public class SampleEmailNotification : EmailNotification { public SampleEmailNotification() : base(nameof(SampleEmailNotification)) {} }
You can find some code samples here.
-
Get the
INotificationRegistrar
service in thePostInitialize
method of theModule.cs
file:var registrar = appBuilder.ApplicationServices.GetService<INotificationRegistrar>();
-
Call the
RegisterNotification
method and set the generic type parameter toSampleEmailNotification
:registrar.RegisterNotification<SampleEmailNotification>();
You can find some code samples here
Setting Default Notification Templates and Sample Data
There are two ways to declare and distribute predefined notification templates and sample data:
- Using the files included into the module bundle
- Through inline definition in the source code
Using Module Bundle
This is the main way to distribute defaults. Commerce bundled VC-modules store notification predifinitions this way. To do the same for your custom module, do the following:
- For every notification type, create a subject template of the email, a body template, and sample data in three different files, according to the
[NotificationName]_[PartPostfixe]
file name convention, wherePartPostfixe
means:
PartPostfixe | Description |
---|---|
subject.txt | UTF-8 text file with the subject rendering template |
body.html | Body rendering template |
sample.json | Sample object JSON file |
- Put the files to a folder inside the
*.Web
project of your module (for example,Templates
). - Modify the
*.Web.csproj
file to allow the predifinition file to be copied upon publishing. Technically, you need to add the following lines:
<ItemGroup>
<NotificationTemplates Include="Templates/**" />
</ItemGroup>
<Target Name="CopyCustomContentOnPublish" AfterTargets="Publish">
<Copy SourceFiles="@(NotificationTemplates)" DestinationFiles="$(PublishDir)\..\%(Identity)" />
</Target>
- Use the
WithTemplatesFromPath
extension to attach predifinitions from the folder while registering the notification type inModule.cs
:
var moduleTemplatesPath = Path.Combine(ModuleInfo.FullPhysicalPath, "Templates");
registrar.RegisterNotification<SampleEmailNotification>().WithTemplatesFromPath(Path.Combine(moduleTemplatesPath, "Custom"), Path.Combine(moduleTemplatesPath, "Default"));
You can find the full sample here. Also, we encourage you to view how it works in a real commerce-bundle module here.
Hardcode as Inline Definition:
There is a less useful but still possible way to define predifinitions directly in the source code:
registrar.RegisterNotification<SampleEmailNotification>().WithTemplates(new EmailNotificationTemplate()
{
Subject = "Sample subject",
Body = "<p>Sample text</p>",
});
You can also do so from an assembly embedded resource:
var assembly = Assembly.GetExecutingAssembly();
registrar.RegisterNotification<SampleEmailNotification>().WithTemplates(new EmailNotificationTemplate()
{
Subject = assembly.GetManifestResourceStream("VirtoCommerce.NotificationsSampleModule.Web.Templates.SampleEmailNotification_subject.txt").ReadToString(),
Body = assembly.GetManifestResourceStream("VirtoCommerce.NotificationsSampleModule.Web.Templates.SampleEmailNotification_body.html").ReadToString()
});
You can find some code samples here.
Sending Notification from Code
- After registering your notification, you need to call two services:
INotificationSearchService
andINotificationSender
. -
Assuming we have 'SampleService' as a sample, we need to add the services to the constructor this way:
public class SampleService { private readonly INotificationSearchService _notificationSearchService; private readonly INotificationSender _notificationSender; public SampleService(INotificationSender notificationSender, INotificationSearchService notificationSearchService) { _notificationSender = notificationSender; _notificationSearchService = notificationSearchService; } }
-
Get the notification via
INotificationSearchService
through the method you need:var notification = await _notificationSearchService.GetNotificationAsync<SampleEmailNotification>();
-
Set all notification parameters for the notification, like this:
notification.LanguageCode = 'en-US'; notification.SetFromToMembers("[email protected]", "[email protected]");
-
Send the notification instantly:
await _notificationSender.SendNotificationAsync(notification);
Or schedule it like this:
_notificationSender.ScheduleSendNotification(notification);
You can find our demo code samples here.
Extending Existing Notification Type and Template
If you want to extend an existing notification, you need to:
-
Create a notification based on the derived notification:
public class ExtendedSampleEmailNotification : SampleEmailNotification { public ExtendedSampleEmailNotification() : base(nameof(ExtendedSampleEmailNotification)) { } }
We have some sample code here.
-
Override the notification type through
INotificationRegistrar
:registrar.OverrideNotificationType<SampleEmailNotification, ExtendedSampleEmailNotification>();
Feel free to use sample code here.
-
Add templates for the extended notification, if required:
registrar.OverrideNotificationType<SampleEmailNotification, ExtendedSampleEmailNotification>().WithTemplates(new EmailNotificationTemplate() { Subject = "Extended SampleEmailNotification subject", Body = "Extended SampleEmailNotification body test" });
You can find some sample code here.
- Define the derived notifications with their own types and convert the types to the based type, e.g.,
SampleEmailNotification
. This can be defined through migration:- Create a clean migration in your project.
- Add an SQL-script that will be updating your notifications.
You can find a notification example here
You can find all our notification samples here.