A sender posts a message on a named channel to one or more recipients. The posted messages are stored and regularly dispatched to a recipient through a formatter and a provider. The formatter's job is to, if needed, format the text of the message, perhaps retrieve and include content or user data. You can group several messages to reduce the number of messages sent to the recipient. The provider's job is to send a formatted message to a recipient by some means, the most common way being sending it as an email. You can have more than one provider for a channel and let the recipient decide which one is preferred.
A message is posted to the
INotifier. You can configure a message to be sent immediately or placed in a message queue periodically handled by a scheduled job. Messages to be sent are passed to the
NotificationDispatcher formats the message using a
NotificationFormatter and then sends it using a
NotificationProvider. You can create your formatters and providers.
Every message is sent on a channel (identified by a channel name), a namespace that groups messages of a certain kind. Messages in different channels are not mixed. You can create your channel by creating a name to use when creating messages and providing a formatter that supports it. You can configure whether messages for a specific channel should be sent immediately by adding an instance of
INotificationChannelOptionsRegistry specifying that messages within this channel should be processed immediately. By default, messages are processed periodically by the scheduler.
The sender has no control over how the recipient receives the message. The recipient's provider preferences for that channel determine how the message is sent (when a default preference resolver should be used).
Do not use generic names for channels, providers and formatters because they risk colliding with other names. Prefix the names with something unique.
NotificationMessage– The default message type, which handles the message at the next scheduled job or immediately depending on registered options for the channel.
ScheduledNotificationMessage– Handles the message at the next scheduled job after the provided time.
DelayedNotificationMessage– Handles the message at the next scheduled job that occurs after the provided time but provides a delay time instead of an actual time.
A user is an
INotificationUser instance with a name and a display name.
To find users, get an instance of
QueryableNotificationUserService and use the
FindAsync method to find users by part of a name or the
GetAsync method to get a specific user by name.
Use an instance of
INotificationPreferenceRegister to register a default preference resolver for a channel and a provider. The resolver takes a user's name and returns a provider-specific address (for example, email addresses for the email provider).
Get an instance of the
INotifier interface and use the
PostNotificationAsync method to post a message (for one or more recipients) to the message queue. A message with more than one recipient is stored internally as one message for each recipient. Hook into the
NotificationFiltered events to get feedback on the result of the posting (per message).
NotificationDispatcher is configured and triggered by the scheduler or called directly for immediate messages. It retrieves the messages waiting to be sent and groups them by recipient and channel. For each group, a formatter and a provider are located (if available) to format and send the messages. If there is a problem sending the messages, they are put back in the waiting queue.
When one (or more) messages are sent, they first are routed through a formatter, which can transform the messages with custom formatting or combine several messages into one. A formatter has a name to identify it and a list of names that specifies which channels the formatter supports. If the message has a channel name that matches one of the supported names, that formatter is selected to format the message.
If more than one formatter is found that matches the channel name, no message is sent and an error message is logged.
To create your formatter, implement the
INotificationFormatter interface, give it a name and a list of supported channels. The
FormatMessagesAsync method formats, takes, and returns a list of messages. In the simplest case of formatting, the method should return the incoming messages.
It can also format each message by changing
Subject) or combine several messages into one. Make sure to set the
ContainedID to match the IDs of the combined messages. Message IDs in an in-message but not in an out-message are considered completed and removed from the queue. If there is a problem formatting the messages, the formatter throws an exception, and those messages are returned to the queue and tried again at the next scheduled job.
A provider is a component for sending notifications using a specific method of communication. The built-in
EmailNotificationProvider, for example, handles the sending of emails (for configuration, see Configure your email server). A provider has a name to identify it and a format property that specifies the format the provider supports (max length and if it supports HTML).
You can write your provider by implementing the
INotificationProvider interface and optionally the
INotificationProviderStatus interface, which lets you turn a provider on and off. The
SendAsync method handles the sending of messages, and you should call
failedAction for each message.
IUserNotificationRepository interface to list notifications with the
GetUserNotificationsCountAsync methods. These methods are used in the Optimizely user interface to show notifications.
To get formatted messages, implement the
IUserNotificationFormatter for one or more channels. When calling
GetUserNotification(s)Async formatting is done depending on the
You can hook into the
UserNotificationMissing event to get a callback when a specified notification cannot be found.
You can also use the
IUserNotificationRepository interface to mark one or more notifications as read with one of the
MarkUserNotification(s)AsReadAsync methods. To listen to read notifications, hook into the
Notifications are stored in the database, and old notifications are deleted by the Notification Message Truncate scheduled job, which is set to run every night by default and removes notifications older than three months.
Updated about 1 month ago