From 414cf26b97d97ba0437e8addee26da14d2a2ee05 Mon Sep 17 00:00:00 2001 From: Savorboard Date: Thu, 30 Aug 2018 11:28:57 +0800 Subject: [PATCH] update reamdme for v2.3 --- README.2.2.md | 241 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 93 +++++++++---------- 2 files changed, 281 insertions(+), 53 deletions(-) create mode 100644 README.2.2.md diff --git a/README.2.2.md b/README.2.2.md new file mode 100644 index 0000000..4dbadde --- /dev/null +++ b/README.2.2.md @@ -0,0 +1,241 @@ +# CAP 　　　　　　　　　　　　　　　　　　　　　　[中文](https://github.com/dotnetcore/CAP/blob/develop/README.zh-cn.md) +[![Travis branch](https://img.shields.io/travis/dotnetcore/CAP/develop.svg?label=travis-ci)](https://travis-ci.org/dotnetcore/CAP) +[![AppVeyor](https://ci.appveyor.com/api/projects/status/4mpe0tbu7n126vyw?svg=true)](https://ci.appveyor.com/project/yuleyule66/cap) +[![NuGet](https://img.shields.io/nuget/v/DotNetCore.CAP.svg)](https://www.nuget.org/packages/DotNetCore.CAP/) +[![NuGet Preview](https://img.shields.io/nuget/vpre/DotNetCore.CAP.svg?label=nuget-pre)](https://www.nuget.org/packages/DotNetCore.CAP/) +[![Member project of .NET Core Community](https://img.shields.io/badge/member%20project%20of-NCC-9e20c9.svg)](https://github.com/dotnetcore) +[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dotnetcore/CAP/master/LICENSE.txt) + +CAP is a library based on .Net standard, which is a solution to deal with distributed transactions, also has the function of EventBus, it is lightweight, easy to use, and efficiently. + +## OverView + +In the process of building an SOA or MicroService system, we usually need to use the event to integrate each services. In the process, the simple use of message queue does not guarantee the reliability. CAP is adopted the local message table program integrated with the current database to solve the exception may occur in the process of the distributed system calling each other. It can ensure that the event messages are not lost in any case. + +You can also use the CAP as an EventBus. The CAP provides a simpler way to implement event publishing and subscriptions. You do not need to inherit or implement any interface during the process of subscription and sending. + +This is a diagram of the CAP working in the ASP.NET Core MicroService architecture: + +![](http://images2015.cnblogs.com/blog/250417/201707/250417-20170705175827128-1203291469.png) + +> The solid line in the figure represents the user code, and the dotted line represents the internal implementation of the CAP. + +## Getting Started + +### NuGet + +You can run the following command to install the CAP in your project. + +``` +PM> Install-Package DotNetCore.CAP +``` + +If you want use Kafka to send integrating event, installing by: + +``` +PM> Install-Package DotNetCore.CAP.Kafka +``` + +If you want use RabbitMQ to send integrating event, installing by: + +``` +PM> Install-Package DotNetCore.CAP.RabbitMQ +``` + +CAP supports SqlServer, MySql, PostgreSql as event log storage. + +``` + +// select a database provider you are using, event log table will integrate into. + +PM> Install-Package DotNetCore.CAP.SqlServer +PM> Install-Package DotNetCore.CAP.MySql +PM> Install-Package DotNetCore.CAP.PostgreSql +``` + +### Configuration + +First,You need to config CAP in your Startup.cs： + +```cs +public void ConfigureServices(IServiceCollection services) +{ + //...... + + services.AddDbContext(); + + services.AddCap(x => + { + // If you are using EF, you need to add the following configuration： + // Notice: You don't need to config x.UseSqlServer(""") again! CAP can autodiscovery. + x.UseEntityFramework(); + + // If you are using ado.net,you need to add the configuration： + x.UseSqlServer("Your ConnectionStrings"); + x.UseMySql("Your ConnectionStrings"); + x.UsePostgreSql("Your ConnectionStrings"); + + // If you are using RabbitMQ, you need to add the configuration： + x.UseRabbitMQ("localhost"); + + // If you are using Kafka, you need to add the configuration： + x.UseKafka("localhost"); + }); +} + +public void Configure(IApplicationBuilder app) +{ + //..... + + app.UseCap(); +} + +``` + +### Publish + +Inject `ICapPublisher` in your Controller, then use the `ICapPublisher` to send message + +```c# +public class PublishController : Controller +{ + [Route("~/publishWithTransactionUsingEF")] + public async Task PublishMessageWithTransactionUsingEF([FromServices]AppDbContext dbContext, [FromServices]ICapPublisher publisher) + { + using (var trans = dbContext.Database.BeginTransaction()) + { + // your business code + + //If you are using EF, CAP will automatic discovery current environment transaction, so you do not need to explicit pass parameters. + //Achieving atomicity between original database operation and the publish event log thanks to a local transaction. + await publisher.PublishAsync("xxx.services.account.check", new Person { Name = "Foo", Age = 11 }); + + trans.Commit(); + } + return Ok(); + } + + [Route("~/publishWithTransactionUsingAdonet")] + public async Task PublishMessageWithTransactionUsingAdonet([FromServices]ICapPublisher publisher) + { + var connectionString = ""; + using (var sqlConnection = new SqlConnection(connectionString)) + { + sqlConnection.Open(); + using (var sqlTransaction = sqlConnection.BeginTransaction()) + { + // your business code + + publisher.Publish("xxx.services.account.check", new Person { Name = "Foo", Age = 11 }, sqlTransaction); + + sqlTransaction.Commit(); + } + } + return Ok(); + } +} + +``` + +### Subscribe + +**Action Method** + +Add the Attribute `[CapSubscribe()]` on Action to subscribe message: + +```c# +public class PublishController : Controller +{ + [CapSubscribe("xxx.services.account.check")] + public async Task CheckReceivedMessage(Person person) + { + Console.WriteLine(person.Name); + Console.WriteLine(person.Age); + return Task.CompletedTask; + } +} + +``` + +**Service Method** + +If your subscribe method is not in the Controller,then your subscribe class need to Inheritance `ICapSubscribe`: + +```c# + +namespace xxx.Service +{ + public interface ISubscriberService + { + public void CheckReceivedMessage(Person person); + } + + + public class SubscriberService: ISubscriberService, ICapSubscribe + { + [CapSubscribe("xxx.services.account.check")] + public void CheckReceivedMessage(Person person) + { + } + } +} + +``` + +Then inject your `ISubscriberService` class in Startup.cs + +```c# +public void ConfigureServices(IServiceCollection services) +{ + //Note: The injection of services needs before of `services.AddCap()` + services.AddTransient(); + + services.AddCap(x=>{}); +} +``` + +### Dashboard + +CAP 2.1 and above provides the dashboard pages, you can easily view the sent and received messages. In addition, you can also view the message status in real time on the dashboard. + +In the distributed environment, the dashboard built-in integrated [Consul](http://consul.io) as a node discovery, while the realization of the gateway agent function, you can also easily view the node or other node data, It's like you are visiting local resources. + +```c# +services.AddCap(x => +{ + //... + + // Register Dashboard + x.UseDashboard(); + + // Register to Consul + x.UseDiscovery(d => + { + d.DiscoveryServerHostName = "localhost"; + d.DiscoveryServerPort = 8500; + d.CurrentNodeHostName = "localhost"; + d.CurrentNodePort = 5800; + d.NodeId = 1; + d.NodeName = "CAP No.1 Node"; + }); +}); +``` + +The default dashboard address is :[http://localhost:xxx/cap](http://localhost:xxx/cap) , you can also change the `cap` suffix to others with `d.MatchPath` configuration options. + +![dashboard](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220827302-189215107.png) + +![received](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220934115-1107747665.png) + +![subscibers](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220949193-884674167.png) + +![nodes](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004221001880-1162918362.png) + + +## Contribute + +One of the easiest ways to contribute is to participate in discussions and discuss issues. You can also contribute by submitting pull requests with code changes. + +### License + +[MIT](https://github.com/dotnetcore/CAP/blob/master/LICENSE.txt) diff --git a/README.md b/README.md index 4dbadde..c8bffb8 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,7 @@ You can also use the CAP as an EventBus. The CAP provides a simpler way to imple This is a diagram of the CAP working in the ASP.NET Core MicroService architecture: -![](http://images2015.cnblogs.com/blog/250417/201707/250417-20170705175827128-1203291469.png) - -> The solid line in the figure represents the user code, and the dotted line represents the internal implementation of the CAP. +![cap.png](http://oowr92l0m.bkt.clouddn.com/cap.png) ## Getting Started @@ -30,27 +28,22 @@ You can run the following command to install the CAP in your project. PM> Install-Package DotNetCore.CAP ``` -If you want use Kafka to send integrating event, installing by: +CAP supports RabbitMQ and Kafka as message queue, select the packages you need to install: ``` PM> Install-Package DotNetCore.CAP.Kafka -``` - -If you want use RabbitMQ to send integrating event, installing by: - -``` PM> Install-Package DotNetCore.CAP.RabbitMQ ``` -CAP supports SqlServer, MySql, PostgreSql as event log storage. +CAP supports SqlServer, MySql, PostgreSql，MongoDB as event log storage. ``` - // select a database provider you are using, event log table will integrate into. PM> Install-Package DotNetCore.CAP.SqlServer PM> Install-Package DotNetCore.CAP.MySql PM> Install-Package DotNetCore.CAP.PostgreSql +PM> Install-Package DotNetCore.CAP.MongoDB //need MongoDB 4.0+ cluster ``` ### Configuration @@ -62,18 +55,21 @@ public void ConfigureServices(IServiceCollection services) { //...... - services.AddDbContext(); + services.AddDbContext(); //Options, If you are using EF as the ORM + services.AddSingleton(new MongoClient("")); //Options, If you are using MongoDB services.AddCap(x => { - // If you are using EF, you need to add the following configuration： - // Notice: You don't need to config x.UseSqlServer(""") again! CAP can autodiscovery. - x.UseEntityFramework(); + // If you are using EF, you need to add the configuration： + x.UseEntityFramework(); //Options, Notice: You don't need to config x.UseSqlServer(""") again! CAP can autodiscovery. - // If you are using ado.net,you need to add the configuration： + // If you are using Ado.Net, you need to add the configuration： x.UseSqlServer("Your ConnectionStrings"); x.UseMySql("Your ConnectionStrings"); x.UsePostgreSql("Your ConnectionStrings"); + + // If you are using MongoDB, you need to add the configuration： + x.UseMongoDB("Your ConnectionStrings"); //MongoDB 4.0+ cluster // If you are using RabbitMQ, you need to add the configuration： x.UseRabbitMQ("localhost"); @@ -83,13 +79,6 @@ public void ConfigureServices(IServiceCollection services) }); } -public void Configure(IApplicationBuilder app) -{ - //..... - - app.UseCap(); -} - ``` ### Publish @@ -99,38 +88,39 @@ Inject `ICapPublisher` in your Controller, then use the `ICapPublisher` to send ```c# public class PublishController : Controller { - [Route("~/publishWithTransactionUsingEF")] - public async Task PublishMessageWithTransactionUsingEF([FromServices]AppDbContext dbContext, [FromServices]ICapPublisher publisher) + private readonly ICapPublisher _capBus; + + public PublishController(ICapPublisher capPublisher) { - using (var trans = dbContext.Database.BeginTransaction()) - { - // your business code + _capBus = capPublisher; + } - //If you are using EF, CAP will automatic discovery current environment transaction, so you do not need to explicit pass parameters. - //Achieving atomicity between original database operation and the publish event log thanks to a local transaction. - await publisher.PublishAsync("xxx.services.account.check", new Person { Name = "Foo", Age = 11 }); + [Route("~/adonet/transaction")] + public IActionResult AdonetWithTransaction() + { + using (var connection = new MySqlConnection(ConnectionString)) + { + using (var transaction = connection.BeginTransaction(_capBus, autoCommit: true)) + { + //your business code - trans.Commit(); + _capBus.Publish("xxx.services.show.time", DateTime.Now); + } } + return Ok(); } - [Route("~/publishWithTransactionUsingAdonet")] - public async Task PublishMessageWithTransactionUsingAdonet([FromServices]ICapPublisher publisher) + [Route("~/ef/transaction")] + public IActionResult EntityFrameworkWithTransaction([FromServices]AppDbContext dbContext) { - var connectionString = ""; - using (var sqlConnection = new SqlConnection(connectionString)) + using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: true)) { - sqlConnection.Open(); - using (var sqlTransaction = sqlConnection.BeginTransaction()) - { - // your business code - - publisher.Publish("xxx.services.account.check", new Person { Name = "Foo", Age = 11 }, sqlTransaction); + //your business code - sqlTransaction.Commit(); - } + _capBus.Publish(""xxx.services.show.time", DateTime.Now); } + return Ok(); } } @@ -146,12 +136,10 @@ Add the Attribute `[CapSubscribe()]` on Action to subscribe message: ```c# public class PublishController : Controller { - [CapSubscribe("xxx.services.account.check")] - public async Task CheckReceivedMessage(Person person) + [CapSubscribe("xxx.services.show.time")] + public void CheckReceivedMessage(DateTime datetime) { - Console.WriteLine(person.Name); - Console.WriteLine(person.Age); - return Task.CompletedTask; + Console.WriteLine(datetime); } } @@ -170,11 +158,10 @@ namespace xxx.Service public void CheckReceivedMessage(Person person); } - public class SubscriberService: ISubscriberService, ICapSubscribe { - [CapSubscribe("xxx.services.account.check")] - public void CheckReceivedMessage(Person person) + [CapSubscribe("xxx.services.show.time")] + public void CheckReceivedMessage(DateTime datetime) { } } @@ -196,7 +183,7 @@ public void ConfigureServices(IServiceCollection services) ### Dashboard -CAP 2.1 and above provides the dashboard pages, you can easily view the sent and received messages. In addition, you can also view the message status in real time on the dashboard. +CAP v2.1+ provides the dashboard pages, you can easily view the sent and received messages. In addition, you can also view the message status in real time on the dashboard. In the distributed environment, the dashboard built-in integrated [Consul](http://consul.io) as a node discovery, while the realization of the gateway agent function, you can also easily view the node or other node data, It's like you are visiting local resources.