mirror of https://github.com/abpframework/abp
Merge branch 'dev' of https://github.com/abpframework/abp into refactor/nav-items
mehmet-erim
5 years ago
commit
40d5950b4c
@ -1,8 +1,8 @@
|
||||
<Project>
|
||||
<ItemGroup>
|
||||
<PackageReference Include="ConfigureAwait.Fody" Version="3.3.1" />
|
||||
<PackageReference Include="Fody" Version="6.0.6">
|
||||
<PrivateAssets>all</PrivateAssets>
|
||||
<PackageReference Include="ConfigureAwait.Fody" Version="3.3.1" PrivateAssets="All" />
|
||||
<PackageReference Include="Fody" Version="6.2.0">
|
||||
<PrivateAssets>All</PrivateAssets>
|
||||
<IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
|
||||
</PackageReference>
|
||||
</ItemGroup>
|
||||
|
||||
@ -1,3 +1,134 @@
|
||||
# Distributed Event Bus RabbitMQ Integration
|
||||
|
||||
TODO
|
||||
> This document explains **how to configure the [RabbitMQ](https://www.rabbitmq.com/)** as the distributed event bus provider. See the [distributed event bus document](Distributed-Event-Bus.md) to learn how to use the distributed event bus system
|
||||
|
||||
## Installation
|
||||
|
||||
Use the ABP CLI to add [Volo.Abp.EventBus.RabbitMQ](https://www.nuget.org/packages/Volo.Abp.EventBus.RabbitMQ) NuGet package to your project:
|
||||
|
||||
* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before.
|
||||
* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.EventBus.RabbitMQ` package.
|
||||
* Run `abp add-package Volo.Abp.EventBus.RabbitMQ` command.
|
||||
|
||||
If you want to do it manually, install the [Volo.Abp.EventBus.RabbitMQ](https://www.nuget.org/packages/Volo.Abp.EventBus.RabbitMQ) NuGet package to your project and add `[DependsOn(typeof(AbpEventBusRabbitMqModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project.
|
||||
|
||||
## Configuration
|
||||
|
||||
You can configure using the standard [configuration system](Configuration.md), like using the `appsettings.json` file, or using the [options](Options.md) classes.
|
||||
|
||||
### `appsettings.json` file configuration
|
||||
|
||||
This is the simplest way to configure the RabbitMQ settings. It is also very strong since you can use any other configuration source (like environment variables) that is [supported by the AspNet Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/).
|
||||
|
||||
**Example: The minimal configuration to connect to a local RabbitMQ server with default configurations**
|
||||
|
||||
````json
|
||||
{
|
||||
"RabbitMQ": {
|
||||
"EventBus": {
|
||||
"ClientName": "MyClientName",
|
||||
"ExchangeName": "MyExchangeName"
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
* `ClientName` is the name of this application, which is used as the **queue name** on the RabbitMQ.
|
||||
* `ExchangeName` is the **exchange name**.
|
||||
|
||||
See [the RabbitMQ document](https://www.rabbitmq.com/dotnet-api-guide.html#exchanges-and-queues) to understand these options better.
|
||||
|
||||
#### Connections
|
||||
|
||||
If you need to connect to another server than the localhost, you need to configure the connection properties.
|
||||
|
||||
**Example: Specify the host name (as an IP address)**
|
||||
|
||||
````json
|
||||
{
|
||||
"RabbitMQ": {
|
||||
"Connections": {
|
||||
"Default": {
|
||||
"HostName": "123.123.123.123"
|
||||
}
|
||||
},
|
||||
"EventBus": {
|
||||
"ClientName": "MyClientName",
|
||||
"ExchangeName": "MyExchangeName"
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
Defining multiple connections is allowed. In this case, you can specify the connection that is used for the event bus.
|
||||
|
||||
**Example: Declare two connections and use one of them for the event bus**
|
||||
|
||||
````json
|
||||
{
|
||||
"RabbitMQ": {
|
||||
"Connections": {
|
||||
"Default": {
|
||||
"HostName": "123.123.123.123"
|
||||
},
|
||||
"SecondConnection": {
|
||||
"HostName": "321.321.321.321"
|
||||
}
|
||||
},
|
||||
"EventBus": {
|
||||
"ClientName": "MyClientName",
|
||||
"ExchangeName": "MyExchangeName",
|
||||
"ConnectionName": "SecondConnection"
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
This allows you to use multiple RabbitMQ server in your application, but select one of them for the event bus.
|
||||
|
||||
You can use any of the [ConnectionFactry](http://rabbitmq.github.io/rabbitmq-dotnet-client/api/RabbitMQ.Client.ConnectionFactory.html#properties) properties as the connection properties.
|
||||
|
||||
**Example: Specify the connection port**
|
||||
|
||||
````csharp
|
||||
{
|
||||
"RabbitMQ": {
|
||||
"Connections": {
|
||||
"Default": {
|
||||
"HostName": "123.123.123.123",
|
||||
"Port": "5672"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
### The Options Classes
|
||||
|
||||
`AbpRabbitMqOptions` and `AbpRabbitMqEventBusOptions` classes can be used to configure the connection strings and event bus options for the RabbitMQ.
|
||||
|
||||
You can configure this options inside the `ConfigureServices` of your [module](Module-Development-Basics.md).
|
||||
|
||||
**Example: Configure the connection**
|
||||
|
||||
````csharp
|
||||
Configure<AbpRabbitMqOptions>(options =>
|
||||
{
|
||||
options.Connections.Default.UserName = "user";
|
||||
options.Connections.Default.Password = "pass";
|
||||
options.Connections.Default.HostName = "123.123.123.123";
|
||||
options.Connections.Default.Port = 5672;
|
||||
});
|
||||
````
|
||||
|
||||
**Example: Configure the client and exchange names**
|
||||
|
||||
````csharp
|
||||
Configure<AbpRabbitMqEventBusOptions>(options =>
|
||||
{
|
||||
options.ClientName = "TestApp1";
|
||||
options.ExchangeName = "TestMessages";
|
||||
});
|
||||
````
|
||||
|
||||
Using these options classes can be combined with the `appsettings.json` way. Configuring an option property in the code overrides the value in the configuration file.
|
||||
@ -0,0 +1,3 @@
|
||||
# RabbitMQ
|
||||
|
||||
TODO!
|
||||
@ -0,0 +1,300 @@
|
||||
# 分布式事件总线
|
||||
|
||||
分布式事件总线系统允许**发布**和**订阅跨应用/服务边界**传输的事件. 你可以使用分布式事件总线在**微服务**或**应用程序**之间异步发送和接收消息.
|
||||
|
||||
## 提供程序
|
||||
|
||||
分布式事件总线系统提供了一个可以被任何提供程序实现的**抽象**. 有两种开箱即用的提供程序:
|
||||
|
||||
* `LocalDistributedEventBus` 是默认实现,实现作为进程内工作的分布式事件总线. 是的!如果没有配置真正的分布式提供程序,**默认实现的工作方式与[本地事件总线](Local-Event-Bus.md)一样**.
|
||||
* `RabbitMqDistributedEventBus` 通过[RabbitMQ](https://www.rabbitmq.com/)实现分布式事件总线. 请参阅[RabbitMQ集成文档](Distributed-Event-Bus-RabbitMQ-Integration.md)了解如何配置它.
|
||||
|
||||
使用本地事件总线作为默认具有一些重要的优点. 最重要的是:它允许你编写与分布式体系结构兼容的代码. 您现在可以编写一个整体应用程序,以后可以拆分成微服务. 最好通过分布式事件而不是本地事件在边界上下文之间(或在应用程序模块之间)进行通信.
|
||||
|
||||
例如,[预构建的应用模块](Modules/Index.md)被设计成在分布式系统中作为服务工作,同时它们也可以在独立应用程序中作为模块工作,而不依赖于外部消息代理.
|
||||
|
||||
## 发布事件
|
||||
|
||||
以下介绍了两种发布分布式事件的方法.
|
||||
|
||||
### IDistributedEventBus
|
||||
|
||||
可以[注入](Dependency-Injection.md) `IDistributedEventBus` 并且使用发布分布式事件.
|
||||
|
||||
**示例: 产品的存货数量发生变化时发布分布式事件**
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
using System.Threading.Tasks;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.EventBus.Distributed;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyService : ITransientDependency
|
||||
{
|
||||
private readonly IDistributedEventBus _distributedEventBus;
|
||||
|
||||
public MyService(IDistributedEventBus distributedEventBus)
|
||||
{
|
||||
_distributedEventBus = distributedEventBus;
|
||||
}
|
||||
|
||||
public virtual async Task ChangeStockCountAsync(Guid productId, int newCount)
|
||||
{
|
||||
await _distributedEventBus.PublishAsync(
|
||||
new StockCountChangedEvent
|
||||
{
|
||||
ProductId = productId,
|
||||
NewCount = newCount
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
`PublishAsync` 方法需要一个参数:事件对象,它负责保持与事件相关的数据,是一个简单的普通类:
|
||||
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
[EventName("MyApp.Product.StockChange")]
|
||||
public class StockCountChangedEto
|
||||
{
|
||||
public Guid ProductId { get; set; }
|
||||
|
||||
public int NewCount { get; set; }
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
即使你不需要传输任何数据也需要创建一个类(在这种情况下为空类).
|
||||
|
||||
> `Eto` 是我们按照约定使用的**E**vent **T**ransfer **O**bjects(事件传输对象)的后缀. s虽然这不是必需的,但我们发现识别这样的事件类很有用(就像应用层上的[DTO](Data-Transfer-Objects.md) 一样).
|
||||
|
||||
#### 事件名称
|
||||
|
||||
`EventName`attribute是可选的,但建议使用. 如果不声明,事件名将事件名称将是事件类的全名. 这里是 `AbpDemo.StockCountChangedEto`.
|
||||
|
||||
#### 关于序列化的事件对象
|
||||
|
||||
事件传输对象**必须是可序列化**的,因为将其传输到流程外时，它们将被序列化/反序列化为JSON或其他格式.
|
||||
|
||||
避免循环引用,多态,私有setter,并提供默认(空)构造函数,如果你有其他的构造函数.(虽然某些序列化器可能会正常工作),就像DTO一样.
|
||||
|
||||
### 实体/聚合根类
|
||||
|
||||
[实体](Entities.md)不能通过依赖注入注入服务,但是在实体/聚合根类中发布分布式事件是非常常见的.
|
||||
|
||||
**示例: 在聚合根方法内发布分布式事件**
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
using Volo.Abp.Domain.Entities;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class Product : AggregateRoot<Guid>
|
||||
{
|
||||
public string Name { get; set; }
|
||||
|
||||
public int StockCount { get; private set; }
|
||||
|
||||
private Product() { }
|
||||
|
||||
public Product(Guid id, string name)
|
||||
: base(id)
|
||||
{
|
||||
Name = name;
|
||||
}
|
||||
|
||||
public void ChangeStockCount(int newCount)
|
||||
{
|
||||
StockCount = newCount;
|
||||
|
||||
//ADD an EVENT TO BE PUBLISHED
|
||||
AddDistributedEvent(
|
||||
new StockCountChangedEto
|
||||
{
|
||||
ProductId = Id,
|
||||
NewCount = newCount
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
`AggregateRoot` 类定义了 `AddDistributedEvent` 来添加一个新的分布式事件,事件在聚合根对象保存(创建,更新或删除)到数据库时发布.
|
||||
|
||||
> 如果实体发布这样的事件,以可控的方式更改相关属性是一个好的实践,就像上面的示例一样 - `StockCount`只能由保证发布事件的 `ChangeStockCount` 方法来更改.
|
||||
|
||||
#### IGeneratesDomainEvents 接口
|
||||
|
||||
实际上添加分布式事件并不是 `AggregateRoot` 类独有的. 你可以为任何实体类实现 `IGeneratesDomainEvents`. 但是 `AggregateRoot` 默认实现了它简化你的工作.
|
||||
|
||||
> 不建议为不是聚合根的实体实现此接口,因为它可能不适用于此类实体的某些数据库提供程序. 例如它适用于EF Core,但不适用于MongoDB.
|
||||
|
||||
#### 它是如何实现的?
|
||||
|
||||
调用 `AddDistributedEvent` 不会立即发布事件. 当你将更改保存到数据库时发布该事件;
|
||||
|
||||
* 对于 EF Core, 它在 `DbContext.SaveChanges` 中发布.
|
||||
* 对于 MongoDB, 它在你调用仓储的 `InsertAsync`, `UpdateAsync` 或 `DeleteAsync` 方法时发由 (因为MongoDB没有更改跟踪系统).
|
||||
|
||||
## 订阅事件
|
||||
|
||||
一个服务可以实现 `IDistributedEventHandler<TEvent>` 来处理事件.
|
||||
|
||||
**示例: 处理上面定义的`StockCountChangedEto`**
|
||||
|
||||
````csharp
|
||||
using System.Threading.Tasks;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.EventBus.Distributed;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyHandler
|
||||
: IDistributedEventHandler<StockCountChangedEto>,
|
||||
ITransientDependency
|
||||
{
|
||||
public async Task HandleEventAsync(StockCountChangedEto eventData)
|
||||
{
|
||||
var productId = eventData.ProductId;
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
这就是全部.
|
||||
|
||||
* `MyHandler` 由ABP框架**自动发现**,并在发生 `StockCountChangedEto` 事件时调用 `HandleEventAsync`.
|
||||
* 如果你使用的是分布式消息代理,比如RabbitMQ,ABP会自动**订阅消息代理上的事件**,获取消息执行处理程序.
|
||||
* 如果事件处理程序成功执行(没有抛出任何异常),它将向消息代理发送**确认(ACK)**.
|
||||
|
||||
你可以在处理程序注入任何服务来执行所需的逻辑. 一个事件处理程序可以**订阅多个事件**,但是需要为每个事件实现 `IDistributedEventHandler<TEvent>` 接口.
|
||||
|
||||
> 事件处理程序类必须注册到依赖注入(DI),示例中使用了 `ITransientDependency`. 参阅[DI文档](Dependency-Injection.md)了解更多选项.
|
||||
|
||||
## 预定义的事件
|
||||
|
||||
如果你配置,ABP框架会为[实体](Entities.md)**自动发布创建,更新和删除**分布式事件.
|
||||
|
||||
### 事件类型
|
||||
|
||||
有三种预定义的事件类型:
|
||||
|
||||
* `EntityCreatedEto<T>` 是实体 `T` 创建后发布.
|
||||
* `EntityUpdatedEto<T>` 是实体 `T` 更新后发布.
|
||||
* `EntityDeletedEto<T>` 是实体 `T` 删除后发布.
|
||||
|
||||
这些都是泛型的, `T` 实际上是**E**vent **T**ransfer **O**bject (ETO)的类型,而不是实体的类型,因为实体对象不能做为事件数据传输,所以通常会为实体类定义一个ETO类,如为 `Product` 实体定义 `ProductEto`.
|
||||
|
||||
### 订阅事件
|
||||
|
||||
订阅自动事件与订阅常规分布式事件相同.
|
||||
|
||||
**示例: 产品更新后获取通知**
|
||||
|
||||
````csharp
|
||||
using System.Threading.Tasks;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.Domain.Entities.Events.Distributed;
|
||||
using Volo.Abp.EventBus.Distributed;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyHandler :
|
||||
IDistributedEventHandler<EntityUpdatedEto<ProductEto>>,
|
||||
ITransientDependency
|
||||
{
|
||||
public async Task HandleEventAsync(EntityUpdatedEto<ProductEto> eventData)
|
||||
{
|
||||
var productId = eventData.Entity.Id;
|
||||
//TODO
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
* `MyHandler` 实现了 `IDistributedEventHandler<EntityUpdatedEto<ProductEto>>`.
|
||||
|
||||
### 配置
|
||||
|
||||
你可以在[模块](Module-Development-Basics.md)的 `ConfigureServices` 中配置 `AbpDistributedEntityEventOptions`添加选择器.
|
||||
|
||||
**示例: 配置示例**
|
||||
|
||||
````csharp
|
||||
Configure<AbpDistributedEntityEventOptions>(options =>
|
||||
{
|
||||
//Enable for all entities
|
||||
options.AutoEventSelectors.AddAll();
|
||||
|
||||
//Enable for a single entity
|
||||
options.AutoEventSelectors.Add<IdentityUser>();
|
||||
|
||||
//Enable for all entities in a namespace (and child namespaces)
|
||||
options.AutoEventSelectors.AddNamespace("Volo.Abp.Identity");
|
||||
|
||||
//Custom predicate expression that should return true to select a type
|
||||
options.AutoEventSelectors.Add(
|
||||
type => type.Namespace.StartsWith("MyProject.")
|
||||
);
|
||||
});
|
||||
````
|
||||
|
||||
* 最后一个提供了灵活性来决定是否应该针对给定的实体类型发布事件. 返回 `true` 代表为该 `Type` 发布事件.
|
||||
|
||||
你可以添加多个选择器. 如果选择器之一与实体类型匹配,则将其选中.
|
||||
|
||||
### 事件传输对象
|
||||
|
||||
一旦你为一个实体启用了**自动事件**,ABP框架就会为实体上的更改发布事件. 如果你没有为实体指定对应的**E**vent **T**ransfer **O**bject(ETO), ABP框架会使用一个标准类型 `EntityEto`,它只有两个属性:
|
||||
|
||||
* `EntityType` (`string`): 实体类的全名(包括命令空间).
|
||||
* `KeysAsString` (`string`): 已更改实体的主键.如果它只有一个主键,这个属性将是主键值. 对于复合键,它包含所有用`,`(逗号)分隔的键.
|
||||
|
||||
因此可以实现 `IDistributedEventHandler<EntityUpdatedEto<EntityEto>>` 订阅事件. 但是订阅这样的通用事件不是一个好方法,你可以为实体类型定义对应的ETO.
|
||||
|
||||
**示例: 为 `Product` 声明使用 `ProductDto`**
|
||||
|
||||
````csharp
|
||||
Configure<AbpDistributedEntityEventOptions>(options =>
|
||||
{
|
||||
options.AutoEventSelectors.Add<Product>();
|
||||
options.EtoMappings.Add<Product, ProductEto>();
|
||||
});
|
||||
````
|
||||
|
||||
在这个示例中;
|
||||
|
||||
* 添加选择器允许发布 `Product` 实体的创建,更新和删除事件.
|
||||
* 配置为使用 `ProductEto` 作为事件传输对象来发布与 `Product` 相关的事件.
|
||||
|
||||
分布式事件系统使用[对象到对象的映射](Object-To-Object-Mapping.md)系统来映射 `Product` 对象到 `ProductEto` 对象,你需要配置映射. 请参阅可以对象到对象映射文档了解所有选项,下面的示例展示了如何使用[AutoMapper](https://automapper.org/)库配置它.
|
||||
|
||||
**示例: 使用AutoMapper配置 `Product` 到 `ProductEto` 映射**
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
using AutoMapper;
|
||||
using Volo.Abp.Domain.Entities.Events.Distributed;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
[AutoMap(typeof(Product))]
|
||||
public class ProductEto : EntityEto
|
||||
{
|
||||
public Guid Id { get; set; }
|
||||
public string Name { get; set; }
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
此示例使用AutoMapper的 `AutoMap` 属性配置的映射. 你可以创建一个配置文件类代替. 请参阅AutoMapper文档了解更多选项.
|
||||
@ -1,3 +1,10 @@
|
||||
# Event Bus
|
||||
# 事件总线
|
||||
|
||||
TODO
|
||||
事件总线是将消息从发送方传输到接收方的中介. 它在对象,服务和应用程序之间提供了一种松散耦合的通信方式.
|
||||
|
||||
## 事件总线类型
|
||||
|
||||
ABP框架提供了两种事件总线类型;
|
||||
|
||||
* **[本地事件总线](Local-Event-Bus.md)** 适合进程内消息传递.
|
||||
* **[分布式事件总线](Distributed-Event-Bus.md)** 适合进程间消息传递,如微服务发布和订阅分布式事件.
|
||||
@ -0,0 +1,227 @@
|
||||
# 本地事件总线
|
||||
|
||||
本地事件总线允许服务发布和订阅**进程内事件**. 这意味着如果两个服务(发布者和订阅者)在同一个进程中运行,那么它是合适的.
|
||||
|
||||
## 发布事件
|
||||
|
||||
以下介绍了两种发布本地事件的方法.
|
||||
|
||||
### ILocalEventBus
|
||||
|
||||
可以[注入](Dependency-Injection.md) `ILocalEventBus` 并且使用发布本地事件.
|
||||
|
||||
**示例: 产品的存货数量发生变化时发布本地事件**
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
using System.Threading.Tasks;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.EventBus.Local;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyService : ITransientDependency
|
||||
{
|
||||
private readonly ILocalEventBus _localEventBus;
|
||||
|
||||
public MyService(ILocalEventBus localEventBus)
|
||||
{
|
||||
_localEventBus = localEventBus;
|
||||
}
|
||||
|
||||
public virtual async Task ChangeStockCountAsync(Guid productId, int newCount)
|
||||
{
|
||||
//TODO: IMPLEMENT YOUR LOGIC...
|
||||
|
||||
//PUBLISH THE EVENT
|
||||
await _localEventBus.PublishAsync(
|
||||
new StockCountChangedEvent
|
||||
{
|
||||
ProductId = productId,
|
||||
NewCount = newCount
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
`PublishAsync` 方法需要一个参数:事件对象,它负责保持与事件相关的数据,是一个简单的普通类:
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class StockCountChangedEvent
|
||||
{
|
||||
public Guid ProductId { get; set; }
|
||||
|
||||
public int NewCount { get; set; }
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
即使你不需要传输任何数据也需要创建一个类(在这种情况下为空类).
|
||||
|
||||
### 实体/聚合根类
|
||||
|
||||
[实体](Entities.md)不能通过依赖注入注入服务,但是在实体/聚合根类中发布本地事件是非常常见的.
|
||||
|
||||
**示例: 在聚合根方法内发布本地事件**
|
||||
|
||||
````csharp
|
||||
using System;
|
||||
using Volo.Abp.Domain.Entities;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class Product : AggregateRoot<Guid>
|
||||
{
|
||||
public string Name { get; set; }
|
||||
|
||||
public int StockCount { get; private set; }
|
||||
|
||||
private Product() { }
|
||||
|
||||
public Product(Guid id, string name)
|
||||
: base(id)
|
||||
{
|
||||
Name = name;
|
||||
}
|
||||
|
||||
public void ChangeStockCount(int newCount)
|
||||
{
|
||||
StockCount = newCount;
|
||||
|
||||
//ADD an EVENT TO BE PUBLISHED
|
||||
AddLocalEvent(
|
||||
new StockCountChangedEvent
|
||||
{
|
||||
ProductId = Id,
|
||||
NewCount = newCount
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
`AggregateRoot` 类定义了 `AddLocalEvent` 来添加一个新的本地事件,事件在聚合根对象保存(创建,更新或删除)到数据库时发布.
|
||||
|
||||
> 如果实体发布这样的事件,以可控的方式更改相关属性是一个好的实践,就像上面的示例一样 - `StockCount`只能由保证发布事件的 `ChangeStockCount` 方法来更改.
|
||||
|
||||
#### IGeneratesDomainEvents 接口
|
||||
|
||||
实际上添加本地事件并不是 `AggregateRoot` 类独有的. 你可以为任何实体类实现 `IGeneratesDomainEvents`. 但是 `AggregateRoot` 默认实现了它简化你的工作.
|
||||
|
||||
> 不建议为不是聚合根的实体实现此接口,因为它可能不适用于此类实体的某些数据库提供程序. 例如它适用于EF Core,但不适用于MongoDB.
|
||||
|
||||
#### 它是如何实现的?
|
||||
|
||||
调用 `AddLocalEvent` 不会立即发布事件. 当你将更改保存到数据库时发布该事件;
|
||||
|
||||
* 对于 EF Core, 它在 `DbContext.SaveChanges` 中发布.
|
||||
* 对于 MongoDB, 它在你调用仓储的 `InsertAsync`, `UpdateAsync` 或 `DeleteAsync` 方法时发由 (因为MongoDB没有更改跟踪系统).
|
||||
|
||||
## 订阅事件
|
||||
|
||||
一个服务可以实现 `ILocalEventHandler<TEvent>` 来处理事件.
|
||||
|
||||
**示例: 处理上面定义的`StockCountChangedEvent`**
|
||||
|
||||
````csharp
|
||||
using System.Threading.Tasks;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.EventBus;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyHandler
|
||||
: ILocalEventHandler<StockCountChangedEvent>,
|
||||
ITransientDependency
|
||||
{
|
||||
public async Task HandleEventAsync(StockCountChangedEvent eventData)
|
||||
{
|
||||
//TODO: your code that does somthing on the event
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
这就是全部,`MyHandler` 由ABP框架**自动发现**,并在发生 `StockCountChangedEvent` 事件时调用 `HandleEventAsync`.
|
||||
|
||||
* 事件可以由**0个或多个处理程序**订阅.
|
||||
* 一个事件处理程序可以**订阅多个事件**,但是需要为每个事件实现 `ILocalEventHandler<TEvent>` 接口.
|
||||
|
||||
> 事件处理程序类必须注册到依赖注入(DI),示例中使用了 `ITransientDependency`. 参阅[DI文档](Dependency-Injection.md)了解更多选项.
|
||||
|
||||
## 事务和异常行为
|
||||
|
||||
当一个事件发布,订阅的事件处理程序将立即执行.所以;
|
||||
|
||||
* 如果处理程序**抛出一个异常**,它会影响发布该事件的代码. 这意味着它在 `PublishAsync` 调用上获得异常. 因此如果你想隐藏错误,在事件处理程序中**使用try-catch**.
|
||||
*如果在一个[工作单元](Unit-Of-Work.md)范围内执行的事件发布的代码,该事件处理程序也由工作单元覆盖. 这意味着,如果你的UOW是事务和处理程序抛出一个异常,事务会回滚.
|
||||
|
||||
## 预定义的事件
|
||||
|
||||
**发布实体创建,更新,删除事件**是常见的操作. ABP框架为所有的实体**自动**发布这些事件. 你只需要订阅相关的事件.
|
||||
|
||||
**示例: 订阅用户创建事件**
|
||||
|
||||
````csharp
|
||||
using System.Threading.Tasks;
|
||||
using Microsoft.AspNetCore.Identity;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
using Volo.Abp.Domain.Entities.Events;
|
||||
using Volo.Abp.EventBus;
|
||||
|
||||
namespace AbpDemo
|
||||
{
|
||||
public class MyHandler
|
||||
: ILocalEventHandler<EntityCreatedEventData<IdentityUser>>,
|
||||
ITransientDependency
|
||||
{
|
||||
public async Task HandleEventAsync(
|
||||
EntityCreatedEventData<IdentityUser> eventData)
|
||||
{
|
||||
var userName = eventData.Entity.UserName;
|
||||
var email = eventData.Entity.Email;
|
||||
//...
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
这个类订阅 `EntityCreatedEventData<IdentityUser>`,它在用户创建后发布. 你可能需要向新用户发送一封"欢迎"电子邮件.
|
||||
|
||||
这些事件有两种类型:过去时态的事件和进行时态的事件.
|
||||
|
||||
### 用过去时态事件
|
||||
|
||||
当相关工作单元完成且实体更改成功保存到数据库时,将发布带有过去时态的事件. 如果在这些事件处理程序上抛出异常,则**无法回滚**事务,因为事务已经提交.
|
||||
|
||||
事件类型;
|
||||
|
||||
* `EntityCreatedEventData<T>` 当实体创建创建成功后发布.
|
||||
* `EntityUpdatedEventData<T>` 当实体创建更新成功后发布.
|
||||
* `EntityDeletedEventData<T>` 当实体创建删除成功后发布.
|
||||
* `EntityChangedEventData<T>` 当实体创建,更新,删除后发布. 如果你需要监听任何类型的更改,它是一种快捷方式 - 而不是订阅单个事件.
|
||||
|
||||
### 用于进行时态事件
|
||||
|
||||
带有进行时态的事件在完成事务之前发布(如果数据库事务由所使用的数据库提供程序支持). 如果在这些事件处理程序上抛出异常,它**会回滚**事务,因为事务还没有完成,更改也没有保存到数据库中.
|
||||
|
||||
事件类型;
|
||||
|
||||
* `EntityCreatingEventData<T>` 当新实体保存到数据库前发布.
|
||||
* `EntityUpdatingEventData<T>` 当已存在实体更新到数据库前发布.
|
||||
* `EntityDeletingEventData<T>` 删除实体前发布.
|
||||
* `EntityChangingEventData<T>` 当实体创建,更新,删除前发布. 如果你需要监听任何类型的更改,它是一种快捷方式 - 而不是订阅单个事件.
|
||||
|
||||
#### 它是如何实现的?
|
||||
|
||||
在将更改保存到数据库时发布预构建事件;
|
||||
|
||||
* 对于 EF Core, 他们在 `DbContext.SaveChanges` 发布.
|
||||
* 对于 MongoDB, 在你调用仓储的 `InsertAsync`, `UpdateAsync` 或 `DeleteAsync` 方法发布(因为MongoDB没有更改追踪系统).
|
||||
@ -0,0 +1,6 @@
|
||||
{
|
||||
"culture": "tr",
|
||||
"texts": {
|
||||
"hello": "Merhaba"
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue