ABP理论学习之通知系统

返回总目录

---

本篇目录

• 介绍
• 订阅通知
• 发布通知
• 用户通知管理者
• 实时通知
• 通知存储
• 通知定义

介绍

通知（Notification）用于告知用户系统中的特定事件。ABP提供了基于实时通知基础设施的发布订阅模型（pub/sub）。

发送模型

给用户发送通知有两种方式：

• 首先用户订阅特定的通知类型，然后我们发布这种类型的通知，这种类型的通知会传递给所有已经订阅的用户。这就是发布订阅（pub/sub）模型。
• 直接给目标用户发送通知。

通知类型

通知类型也有两种：

• 一般通知：是任意类型的通知。“如果一个用户给我发送了添加好友的请求就通知我”是这种通知类型的一个例子。
• 实体通知：和特定的实体相关联。“如果一个用户在 这张图片上评论那么通知我”是基于实体的通知，因为它和特定的实体相关联。用户可能想获得某些图片的通知而不是所有的图片通知。

通知数据

一个通知一般都会包括一个通知数据。比如，“如果一个用户给我发送了添加好友的请求就通知我”，这个通知可能有两个数据属性：发送者用户名（那哪一个用户发送的这个添加好友的请求）和请求内容（该用户在这个请求中写的东西）。很明显，该通知数据类型紧耦合于通知类型。不同的通知类型有不同的数据类型。

• 通知数据是可选的。某些通知可能不需要数据。一些预定义的通知数据类型可能对于大多数情况够用了。 MessageNotificationData可以用于简单的信息， LocalizableMessageNotificationData可以用于本地化的，带参数的通知信息。

通知安全

通知的安全性有5个级别，它们定义在NotificationSeverity枚举类中，分别是 Info,Success,Warn,Error和Fatal。默认值是Info。

订阅通知

INotificationSubscriptionManager 提供了订阅通知的API。例如：

public class MyService : ITransientDependency
{
    private readonly INotificationSubscriptionManager _notificationSubscriptionManager;

    public MyService(INotificationSubscriptionManager notificationSubscriptionManager)
    {
        _notificationSubscriptionManager = notificationSubscriptionManager;
    }

    //订阅一个一般通知
    public async Task Subscribe_SentFrendshipRequest(int? tenantId, long userId)
    {
        await _notificationSubscriptionManager.SubscribeAsync(tenantId, userId, "SentFrendshipRequest");
    }

    //订阅一个实体通知
    public async Task Subscribe_CommentPhoto(int? tenantId, long userId, Guid photoId)
    {
        await _notificationSubscriptionManager.SubscribeAsync(tenantId, userId, "CommentPhoto", new EntityIdentifier(typeof(Photo), photoId));
    }
}

首先，我们注入了INotificationSubscriptionManager。第一个方法订阅了一个一般通知。当某人发送了一个添加好友的请求时，用户想得到通知。第二个方法订阅了一个和特定实体（Photo）相关的通知。如果任何人对这个特定的图片进行了评论，那么用户就会收到通知。

每一个通知应该有唯一的名字（比如例子中的SentFrendshipRequest和 CommentPhoto）。

INotificationSubscriptionManager还有很多方法来管理通知，比如UnsubscribeAsync, IsSubscribedAsync, GetSubscriptionsAsync等方法。

发布通知

INotificationPublisher用于发布通知，例如：

public class MyService : ITransientDependency
{
    private readonly INotificationPublisher _notiticationPublisher;

    public MyService(INotificationPublisher notiticationPublisher)
    {
        _notiticationPublisher = notiticationPublisher;
    }

    //给特定的用户发送一个一般通知
    public async Task Publish_SentFrendshipRequest(string senderUserName, string friendshipMessage, long targetUserId)
    {
        await _notiticationPublisher.PublishAsync("SentFrendshipRequest", new SentFrendshipRequestNotificationData(senderUserName, friendshipMessage), userIds: new[] { targetUserId });
    }

    //给特定的用户发送一个实体通知
    public async Task Publish_CommentPhoto(string commenterUserName, string comment, Guid photoId, long photoOwnerUserId)
    {
        await _notiticationPublisher.PublishAsync("CommentPhoto", new CommentPhotoNotificationData(commenterUserName, comment), new EntityIdentifier(typeof(Photo), photoId), userIds: new[] { photoOwnerUserId });
    }

    //给具特定严重级别程度的所有订阅用户发送一个一般通知
    public async Task Publish_LowDisk(int remainingDiskInMb)
    {
        //例如 "LowDiskWarningMessage"的英文内容 -> "Attention! Only {remainingDiskInMb} MBs left on the disk!"
        var data = new LocalizableMessageNotificationData(new LocalizableString("LowDiskWarningMessage", "MyLocalizationSourceName"));
        data["remainingDiskInMb"] = remainingDiskInMb;

        await _notiticationPublisher.PublishAsync("System.LowDisk", data, severity: NotificationSeverity.Warn);
    }
}

在第一个例子中，我们向单个用户发布了一个通知。SentFrendshipRequestNotificationData应该从 NotificationData继承，比如：

[Serializable]
public class SentFrendshipRequestNotificationData : NotificationData
{
    public string SenderUserName { get; set; }

    public string FriendshipMessage { get; set; }

    public SentFrendshipRequestNotificationData(string senderUserName, string friendshipMessage)
    {
        SenderUserName = senderUserName;
        FriendshipMessage = friendshipMessage;
    }
}

在第二个例子中，我们向特定的用户发送了一个特定实体的通知。通知数据类CommentPhotoNotificationData一般不需要serializble(因为默认使用了JSON序列化)。但是建议把它标记为serializable，因为你可能需要在应用之间移动通知，也可能在未来使用二进制的序列。此外，正如之前声明的那样，通知数据是可选的，而且对于所有的通知可能不是必须的。

注意：如果我们对特定的用户发布了一个通知，那么他们不需要订阅那些通知。

在第三个例子中，我们没有定义一个专用的通知数据类。相反，我们直接使用了内置的具有基于字典数据的LocalizableMessageNotificationData，并且以 Warn发布了通知。LocalizableMessageNotificationData可以存储基于字典的任意数据（这对于自定义的通知数据类也是成立的，因为它们也从 NotificationData类继承）。在本地化时我们使用了“ remaingDiskInMb”作为参数。本地化信息可以包含这些参数（比如例子中的"Attention! Only {remainingDiskInMb} MBs left on the disk!"）

用户通知管理者

IUserNotificationManager用于管理用户的通知，它有 get,update或delete用户通知的方法。你可以为你的应用程序准备一个通知列表页面。

实时通知

当使用IUserNotificationManager来查询通知时，我们一般想实时地将通知推送到客户端。

通知系统使用了IRealTimeNotifier向用户发送实时通知。这可以使用任何类型的实时通讯系统来实现。ABP在一个单独的包中使用了 SignalR来实现。ABP官网的起始模板已经安装了SignalR。

注意：通知系统在一个后台工作中异步调用IRealTimeNotifier。因此，通知发送时可能伴有轻微的延迟。

客户端

当接收到一个实时通知时，ABP会在客户端触发一个全局的事件（global event）。你可以像下面那样注册来获取通知：

abp.event.on('abp.notifications.received', function (userNotification) {
    console.log(userNotification);
});

abp.notifications.received事件对于每个接收到的实时通知都会触发。你可以像上面那样注册该事件来获取通知。查看javascript事件总线文档获取更多信息。对于上面的“System.LowDisk”例子，下面是接收到的通知消息的JSON数据：

{
    "userId": 2,
    "state": 0,
    "notification": {
        "notificationName": "System.LowDisk",
        "data": {
            "message": {
                "sourceName": "MyLocalizationSourceName",
                "name": "LowDiskWarningMessage"
            },
            "type": "Abp.Notifications.LocalizableMessageNotificationData",
            "properties": {
                "remainingDiskInMb": "42"
            }
        },
        "entityType": null,
        "entityTypeName": null,
        "entityId": null,
        "severity": 0,
        "creationTime": "2016-02-09T17:03:32.13",
        "id": "0263d581-3d8a-476b-8e16-4f6a6f10a632"
    },
    "id": "4a546baf-bf17-4924-b993-32e420a8d468"
}

在这个对象中，

• userId:当前的用户Id。一般来说不需要这个，因为你知道当前的用户。
• state： UserNotificationState枚举的值。0：未读，1：已读。
• notification:通知细节。
  • notificationName:通知的唯一名称。（当发布该通知时使用相同的值）
  • data:通知数据。在本例中，我们使用了**LocalizableMessageNotificationData **（正如之前的例子中发布的）。
  • message:本地的信息通知。我们可以使用 sourceName和 name来本地化UI上的信息。
  • type:通知数据类型。全类型名称，包括命名空间。当处理该通知数据时我们可以检查该类型。
  • properties：基于字典的自定义属性。
  • entityType, entityTypeName和entityId：和通知相关的实体的信息。
  • severity： NotificationSeverity枚举的值。0: Info, 1: Success, 2: Warn, 3: Error, 4: Fatal。
  • creationTime:该通知创建的时间。
  • id:通知的Id。
• id:用户的通知id。

当然，你不仅可以记录该通知。你还可以使用通知数据将通知信息展示给该用户。例如：

abp.event.on('abp.notifications.received', function (userNotification) {
    if (userNotification.notification.data.type === 'Abp.Notifications.LocalizableMessageNotificationData') {
        var localizedText = abp.localization.localize(
            userNotification.notification.data.message.name,
            userNotification.notification.data.message.sourceName
        );

        $.each(userNotification.notification.data.properties, function (key, value) {
            localizedText = localizedText.replace('{' + key + '}', value);
        });

        alert('New localized notification: ' + localizedText);
    } else if (userNotification.notification.data.type === 'Abp.Notifications.MessageNotificationData') {
        alert('New simple notification: ' + userNotification.notification.data.message);
    }
});

要处理通知数据，我们应该检查该数据类型。这个例子简单地从通知数据中获得信息。对于本地化的信息（LocalizableMessageNotificationData），我们要本地化该信息并替换参数。对于简单的信息（MessageNotificationData），我们直接获得该信息。当然，在一个真实项目中，我们不使用alert函数。我们可以使用abp.notifyapi来展示漂亮的UI通知。

如果你要实现这么上面的逻辑，那么有一种更简单且可伸缩的方式。当接收到一个push通知时，你可以只使用一句代码来显示UI通知：

abp.event.on('abp.notifications.received', function (userNotification) {
    abp.notifications.showUiNotifyForUserNotification(userNotification);
});

这句代码会展示一个UI通知如下所示（上面System.LowDisk通知的例子）：

对于内置的通知数据类型（LocalizableMessageNotificationData和 MessageNotificationData）是有效的。如果你有自定义的通知数据类型，那么你应该注册数据格式化器，如下所示：

abp.notifications.messageFormatters['MyProject.MyNotificationDataType'] = function(userNotification) {
    return ...; //format and return message here
};

这样，showUiNotifyForUserNotification就可以对你的数据类型创建要显示的信息了。如果你只需要格式化信息，那么你可以直接使用 abp.notifications.getFormattedMessageFromUserNotification(userNotification)，它内部还是使用了showUiNotifyForUserNotification。

当接收到一个push通知时，启动模板包含了展示UI通知的代码。

通知存储

通知系统使用了INotificationStore来持久化通知。为了使通知系统合适地工作，应该实现这个接口。你可以自己实现或者使用module-zero（它已经实现了该接口）。

通知定义

在使用之前你不必定义一个通知。你无需定义任何类型的通知名就可以使用它们。但是，定义通知名可能会给你带来额外的好处。比如，你以后要研究应用程序中所有的通知，在这种情况下，我们可以给我们的模块定义一个通知提供器（notification provider ），如下所示：

public class MyAppNotificationProvider : NotificationProvider
{
    public override void SetNotifications(INotificationDefinitionContext context)
    {
        context.Manager.Add(
            new NotificationDefinition(
                "App.NewUserRegistered",
                displayName: new LocalizableString("NewUserRegisteredNotificationDefinition", "MyLocalizationSourceName"),
                permissionDependency: new SimplePermissionDependency("App.Pages.UserManagement")
                )
            );
    }
}

"App.NewUserRegistered"是该通知的唯一名称。我们定义了一个本地的 displayName（然后当在UI上订阅了该通知时，我们可以显示该通知）。最后，我们声明了只有拥有了"App.Pages.UserManagement"权限的用户才可以使用该通知。

也有一些其他的参数，你可以在代码中研究。对于一个通知定义，只有通知名称是必须的。

当定义了这么一个通知提供器之后，我们应该在模块的PreInitialize事件中进行注册，如下所示：

public class AbpZeroTemplateCoreModule : AbpModule
{
    public override void PreInitialize()
    {
        Configuration.Notifications.Providers.Add<MyAppNotificationProvider>();
    }

    //...
}

最后，要获得通知定义，在应用程序中注入并使用INotificationDefinitionManager。