diff --git a/docs/zh-Hans/Blob-Storing.md b/docs/zh-Hans/Blob-Storing.md index 788b104edb..43b2ebb96b 100644 --- a/docs/zh-Hans/Blob-Storing.md +++ b/docs/zh-Hans/Blob-Storing.md @@ -169,7 +169,7 @@ public class ProfileAppService : ApplicationService 如果不使用泛型参数,直接注入 `IBlobContainer` (如上所述),会得到默认容器. 注入默认容器的另一种方法是使用 `IBlobContainer`,它返回完全相同的容器. -默认容器的名称是 `Default`. +默认容器的名称是 `default`. ### 命令容器 diff --git a/docs/zh-Hans/Distributed-Event-Bus-RabbitMQ-Integration.md b/docs/zh-Hans/Distributed-Event-Bus-RabbitMQ-Integration.md new file mode 100644 index 0000000000..2a1810e309 --- /dev/null +++ b/docs/zh-Hans/Distributed-Event-Bus-RabbitMQ-Integration.md @@ -0,0 +1,134 @@ +# 分布式事件总线RabbitMQ集成 + +> 本文解释了**如何配置[RabbitMQ](https://www.rabbitmq.com/)**做为分布式总线提供程序. 参阅[分布式事件总线文档](Distributed-Event-Bus.md)了解如何使用分布式事件总线系统. + +## 安装 + +使用ABP CLI添加[Volo.Abp.EventBus.RabbitMQ[Volo.Abp.EventBus.RabbitMQ](https://www.nuget.org/packages/Volo.Abp.EventBus.RabbitMQ)NuGet包到你的项目: + +* 安装[ABP CLI](https://docs.abp.io/en/abp/latest/CLI),如果你还没有安装. +* 在你想要安装 `Volo.Abp.EventBus.RabbitMQ` 包的 `.csproj` 文件目录打开命令行(终端). +* 运行 `abp add-package Volo.Abp.EventBus.RabbitMQ` 命令. + +如果你想要手动安装,安装[Volo.Abp.EventBus.RabbitMQ](https://www.nuget.org/packages/Volo.Abp.EventBus.RabbitMQ) NuGet 包到你的项目然后添加 `[DependsOn(typeof(AbpEventBusRabbitMqModule))]` 到你的项目[模块](Module-Development-Basics.md)类. + +## 配置 + +可以使用配置使用标准的[配置系统](Configuration.md),如 `appsettings.json` 文件,或[选项](Options.md)类. + +### `appsettings.json` 文件配置 + +这是配置RabbitMQ设置最简单的方法. 它也非常强大,因为你可以使用[由AspNet Core支持的](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/)的任何其他配置源(如环境变量). + +**示例：最小化配置与默认配置连接到本地的RabbitMQ服务器** + +````json +{ + "RabbitMQ": { + "EventBus": { + "ClientName": "MyClientName", + "ExchangeName": "MyExchangeName" + } + } +} +```` + +* `ClientName` 是应用程序的名称,用于RabbitMQ的**队列名称**. +* `ExchangeName` 是 **交换机名称**. + +参阅[RabbitMQ文档](https://www.rabbitmq.com/dotnet-api-guide.html#exchanges-and-queues)更好的了解这些选项. + +#### 连接 + +如果需要连接到本地主机以外的另一台服务器,需要配置连接属性. + +**示例: 指定主机名 (如IP地址)** + +````json +{ + "RabbitMQ": { + "Connections": { + "Default": { + "HostName": "123.123.123.123" + } + }, + "EventBus": { + "ClientName": "MyClientName", + "ExchangeName": "MyExchangeName" + } + } +} +```` + +允许定义多个连接. 在这种情况下,你可以指定用于事件总线的连接. + +**示例: 声明两个连接并将其中一个用于事件总线** + +````json +{ + "RabbitMQ": { + "Connections": { + "Default": { + "HostName": "123.123.123.123" + }, + "SecondConnection": { + "HostName": "321.321.321.321" + } + }, + "EventBus": { + "ClientName": "MyClientName", + "ExchangeName": "MyExchangeName", + "ConnectionName": "SecondConnection" + } + } +} +```` + +这允许你可以在你的应用程序使用多个RabbitMQ服务器,但将其中一个做为事件总线. + +你可以使用任何[ConnectionFactry](http://rabbitmq.github.io/rabbitmq-dotnet-client/api/RabbitMQ.Client.ConnectionFactory.html#properties)属性作为连接属性. + +**示例: 指定连接端口** + +````csharp +{ + "RabbitMQ": { + "Connections": { + "Default": { + "HostName": "123.123.123.123", + "Port": "5672" + } + } + } +} +```` + +### 选项类 + +`AbpRabbitMqOptions` 和 `AbpRabbitMqEventBusOptions` 类用于配置RabbitMQ的连接字符串和事件总线选项. + +你可以在你的[模块](Module-Development-Basics.md)的 `ConfigureServices` 方法配置选项. + +**示例: 配置连接** + +````csharp +Configure(options => +{ + options.Connections.Default.UserName = "user"; + options.Connections.Default.Password = "pass"; + options.Connections.Default.HostName = "123.123.123.123"; + options.Connections.Default.Port = 5672; +}); +```` + +**示例: 配置客户端和交换机名称** + +````csharp +Configure(options => +{ + options.ClientName = "TestApp1"; + options.ExchangeName = "TestMessages"; +}); +```` + +使用这些选项类可以与 `appsettings.json` 组合在一起. 在代码中配置选项属性会覆盖配置文件中的值. \ No newline at end of file diff --git a/docs/zh-Hans/Distributed-Event-Bus.md b/docs/zh-Hans/Distributed-Event-Bus.md index 1d618440f8..8416ef953d 100644 --- a/docs/zh-Hans/Distributed-Event-Bus.md +++ b/docs/zh-Hans/Distributed-Event-Bus.md @@ -19,7 +19,7 @@ ### IDistributedEventBus -`IDistributedEventBus` can be [injected](Dependency-Injection.md) and used to publish a distributed event. +可以[注入](Dependency-Injection.md) `IDistributedEventBus` 并且使用发布分布式事件. **示例: 产品的存货数量发生变化时发布分布式事件** @@ -180,3 +180,121 @@ namespace AbpDemo 你可以在处理程序注入任何服务来执行所需的逻辑. 一个事件处理程序可以**订阅多个事件**,但是需要为每个事件实现 `IDistributedEventHandler` 接口. > 事件处理程序类必须注册到依赖注入(DI),示例中使用了 `ITransientDependency`. 参阅[DI文档](Dependency-Injection.md)了解更多选项. + +## 预定义的事件 + +如果你配置,ABP框架会为[实体](Entities.md)**自动发布创建,更新和删除**分布式事件. + +### 事件类型 + +有三种预定义的事件类型: + +* `EntityCreatedEto` 是实体 `T` 创建后发布. +* `EntityUpdatedEto` 是实体 `T` 更新后发布. +* `EntityDeletedEto` 是实体 `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>, + ITransientDependency + { + public async Task HandleEventAsync(EntityUpdatedEto eventData) + { + var productId = eventData.Entity.Id; + //TODO + } + } +} +```` + +* `MyHandler` 实现了 `IDistributedEventHandler>`. + +### 配置 + +你可以在[模块](Module-Development-Basics.md)的 `ConfigureServices` 中配置 `AbpDistributedEntityEventOptions`添加选择器. + +**示例: 配置示例** + +````csharp +Configure(options => +{ + //Enable for all entities + options.AutoEventSelectors.AddAll(); + + //Enable for a single entity + options.AutoEventSelectors.Add(); + + //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>` 订阅事件. 但是订阅这样的通用事件不是一个好方法,你可以为实体类型定义对应的ETO. + +**示例: 为 `Product` 声明使用 `ProductDto`** + +````csharp +Configure(options => +{ + options.AutoEventSelectors.Add(); + options.EtoMappings.Add(); +}); +```` + +在这个示例中; + +* 添加选择器允许发布 `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文档了解更多选项. \ No newline at end of file diff --git a/docs/zh-Hans/Local-Event-Bus.md b/docs/zh-Hans/Local-Event-Bus.md index d39074a957..b5c472734b 100644 --- a/docs/zh-Hans/Local-Event-Bus.md +++ b/docs/zh-Hans/Local-Event-Bus.md @@ -1 +1,227 @@ -TODO.... \ No newline at end of file +# 本地事件总线 + +本地事件总线允许服务发布和订阅**进程内事件**. 这意味着如果两个服务(发布者和订阅者)在同一个进程中运行,那么它是合适的. + +## 发布事件 + +以下介绍了两种发布本地事件的方法. + +### 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 + { + 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` 来处理事件. + +**示例: 处理上面定义的`StockCountChangedEvent`** + +````csharp +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.EventBus; + +namespace AbpDemo +{ + public class MyHandler + : ILocalEventHandler, + ITransientDependency + { + public async Task HandleEventAsync(StockCountChangedEvent eventData) + { + //TODO: your code that does somthing on the event + } + } +} +```` + +这就是全部,`MyHandler` 由ABP框架**自动发现**,并在发生 `StockCountChangedEvent` 事件时调用 `HandleEventAsync`. + +* 事件可以由**0个或多个处理程序**订阅. +* 一个事件处理程序可以**订阅多个事件**,但是需要为每个事件实现 `ILocalEventHandler` 接口. + +> 事件处理程序类必须注册到依赖注入(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>, + ITransientDependency + { + public async Task HandleEventAsync( + EntityCreatedEventData eventData) + { + var userName = eventData.Entity.UserName; + var email = eventData.Entity.Email; + //... + } + } +} +```` + +这个类订阅 `EntityCreatedEventData`,它在用户创建后发布. 你可能需要向新用户发送一封"欢迎"电子邮件. + +这些事件有两种类型:过去时态的事件和进行时态的事件. + +### 用过去时态事件 + +当相关工作单元完成且实体更改成功保存到数据库时,将发布带有过去时态的事件. 如果在这些事件处理程序上抛出异常,则**无法回滚**事务,因为事务已经提交. + +事件类型; + +* `EntityCreatedEventData` 当实体创建创建成功后发布. +* `EntityUpdatedEventData` 当实体创建更新成功后发布. +* `EntityDeletedEventData` 当实体创建删除成功后发布. +* `EntityChangedEventData` 当实体创建,更新,删除后发布. 如果你需要监听任何类型的更改,它是一种快捷方式 - 而不是订阅单个事件. + +### 用于进行时态事件 + +带有进行时态的事件在完成事务之前发布(如果数据库事务由所使用的数据库提供程序支持). 如果在这些事件处理程序上抛出异常,它**会回滚**事务,因为事务还没有完成,更改也没有保存到数据库中. + +事件类型; + +* `EntityCreatingEventData` 当新实体保存到数据库前发布. +* `EntityUpdatingEventData` 当已存在实体更新到数据库前发布. +* `EntityDeletingEventData` 删除实体前发布. +* `EntityChangingEventData` 当实体创建,更新,删除前发布. 如果你需要监听任何类型的更改,它是一种快捷方式 - 而不是订阅单个事件. + +#### 它是如何实现的? + +在将更改保存到数据库时发布预构建事件; + +* 对于 EF Core, 他们在 `DbContext.SaveChanges` 发布. +* 对于 MongoDB, 在你调用仓储的 `InsertAsync`, `UpdateAsync` 或 `DeleteAsync` 方法发布(因为MongoDB没有更改追踪系统). \ No newline at end of file diff --git a/docs/zh-Hans/UI/Angular/Permission-Management.md b/docs/zh-Hans/UI/Angular/Permission-Management.md index 3a50da9591..5c1ba5b4fb 100644 --- a/docs/zh-Hans/UI/Angular/Permission-Management.md +++ b/docs/zh-Hans/UI/Angular/Permission-Management.md @@ -8,7 +8,7 @@ ```js import { Store } from '@ngxs/store'; -import { ConfigState } from '../states'; +import { ConfigState } from '@abp/ng.core'; export class YourComponent { constructor(private store: Store) {} @@ -24,7 +24,7 @@ export class YourComponent { 或者你可以通过 `ConfigStateService` 获取它: ```js -import { ConfigStateService } from '../services/config-state.service'; +import { ConfigStateService } from '@abp/ng.core'; export class YourComponent { constructor(private configStateService: ConfigStateService) {} @@ -42,7 +42,7 @@ export class YourComponent { 你可以使用 `PermissionDirective` 来根据用户的权限控制DOM元素是否可见. ```html -
+
仅当用户具有`AbpIdentity.Roles`权限时,此内容才可见.
``` @@ -58,6 +58,8 @@ export class YourComponent { 将 `requiredPolicy` 添加到路由模块中的 `routes`属性. ```js +import { PermissionGuard } from '@abp/ng.core'; +// ... const routes: Routes = [ { path: 'path',