You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 7 години
преди 6 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 6 години
преди 6 години
преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 7 години
преди 6 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 7 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 7 години
преди 6 години
преди 8 години
преди 6 години
преди 7 години
преди 6 години
преди 6 години
преди 6 години
преди 8 години
преди 8 години
преди 8 години
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
  1. # CAP                       [中文](https://github.com/dotnetcore/CAP/blob/develop/README.zh-cn.md)
  2. [![Travis branch](https://img.shields.io/travis/dotnetcore/CAP/develop.svg?label=travis-ci)](https://travis-ci.org/dotnetcore/CAP)
  3. [![AppVeyor](https://ci.appveyor.com/api/projects/status/v8gfh6pe2u2laqoa?svg=true)](https://ci.appveyor.com/project/yuleyule66/cap)
  4. [![NuGet](https://img.shields.io/nuget/v/DotNetCore.CAP.svg)](https://www.nuget.org/packages/DotNetCore.CAP/)
  5. [![NuGet Preview](https://img.shields.io/nuget/vpre/DotNetCore.CAP.svg?label=nuget-pre)](https://www.nuget.org/packages/DotNetCore.CAP/)
  6. [![Member project of .NET Core Community](https://img.shields.io/badge/member%20project%20of-NCC-9e20c9.svg)](https://github.com/dotnetcore)
  7. [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dotnetcore/CAP/master/LICENSE.txt)
  8. 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.
  9. ## Overview
  10. 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.
  11. 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.
  12. This is a diagram of the CAP working in the ASP.NET Core MicroService architecture:
  13. ![cap.png](http://oowr92l0m.bkt.clouddn.com/cap.png)
  14. > CAP implements the Outbox Pattern described in the [eShop ebook](https://docs.microsoft.com/en-us/dotnet/standard/microservices-architecture/multi-container-microservice-net-applications/subscribe-events#designing-atomicity-and-resiliency-when-publishing-to-the-event-bus).
  15. ## Getting Started
  16. ### NuGet
  17. You can run the following command to install the CAP in your project.
  18. ```
  19. PM> Install-Package DotNetCore.CAP
  20. ```
  21. CAP supports RabbitMQ and Kafka as message queue, select the packages you need to install:
  22. ```
  23. PM> Install-Package DotNetCore.CAP.Kafka
  24. PM> Install-Package DotNetCore.CAP.RabbitMQ
  25. ```
  26. CAP supports SqlServer, MySql, PostgreSql,MongoDB as event log storage.
  27. ```
  28. // select a database provider you are using, event log table will integrate into.
  29. PM> Install-Package DotNetCore.CAP.SqlServer
  30. PM> Install-Package DotNetCore.CAP.MySql
  31. PM> Install-Package DotNetCore.CAP.PostgreSql
  32. PM> Install-Package DotNetCore.CAP.MongoDB //need MongoDB 4.0+ cluster
  33. ```
  34. ### Configuration
  35. First,You need to config CAP in your Startup.cs:
  36. ```cs
  37. public void ConfigureServices(IServiceCollection services)
  38. {
  39. //......
  40. services.AddDbContext<AppDbContext>(); //Options, If you are using EF as the ORM
  41. services.AddSingleton<IMongoClient>(new MongoClient("")); //Options, If you are using MongoDB
  42. services.AddCap(x =>
  43. {
  44. // If you are using EF, you need to add the configuration:
  45. x.UseEntityFramework<AppDbContext>(); //Options, Notice: You don't need to config x.UseSqlServer(""") again! CAP can autodiscovery.
  46. // If you are using Dapper, you need to add the configuration:
  47. x.UseSqlServer("Your ConnectionStrings");
  48. x.UseMySql("Your ConnectionStrings");
  49. x.UsePostgreSql("Your ConnectionStrings");
  50. // If you are using MongoDB, you need to add the configuration:
  51. x.UseMongoDB("Your ConnectionStrings"); //MongoDB 4.0+ cluster
  52. // If you are using RabbitMQ, you need to add the configuration:
  53. x.UseRabbitMQ("localhost");
  54. // If you are using Kafka, you need to add the configuration:
  55. x.UseKafka("localhost");
  56. });
  57. }
  58. ```
  59. ### Publish
  60. Inject `ICapPublisher` in your Controller, then use the `ICapPublisher` to send message
  61. ```c#
  62. public class PublishController : Controller
  63. {
  64. private readonly ICapPublisher _capBus;
  65. public PublishController(ICapPublisher capPublisher)
  66. {
  67. _capBus = capPublisher;
  68. }
  69. [Route("~/adonet/transaction")]
  70. public IActionResult AdonetWithTransaction()
  71. {
  72. using (var connection = new MySqlConnection(ConnectionString))
  73. {
  74. using (var transaction = connection.BeginTransaction(_capBus, autoCommit: true))
  75. {
  76. //your business logic code
  77. _capBus.Publish("xxx.services.show.time", DateTime.Now);
  78. }
  79. }
  80. return Ok();
  81. }
  82. [Route("~/ef/transaction")]
  83. public IActionResult EntityFrameworkWithTransaction([FromServices]AppDbContext dbContext)
  84. {
  85. using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: true))
  86. {
  87. //your business logic code
  88. _capBus.Publish("xxx.services.show.time", DateTime.Now);
  89. }
  90. return Ok();
  91. }
  92. }
  93. ```
  94. ### Subscribe
  95. **In Controller Action**
  96. Add the Attribute `[CapSubscribe()]` on Action to subscribe message:
  97. ```c#
  98. public class PublishController : Controller
  99. {
  100. [CapSubscribe("xxx.services.show.time")]
  101. public void CheckReceivedMessage(DateTime datetime)
  102. {
  103. Console.WriteLine(datetime);
  104. }
  105. }
  106. ```
  107. **In Business Logic Service**
  108. If your subscribe method is not in the Controller,then your subscribe class need to Inheritance `ICapSubscribe`:
  109. ```c#
  110. namespace BusinessCode.Service
  111. {
  112. public interface ISubscriberService
  113. {
  114. public void CheckReceivedMessage(DateTime datetime);
  115. }
  116. public class SubscriberService: ISubscriberService, ICapSubscribe
  117. {
  118. [CapSubscribe("xxx.services.show.time")]
  119. public void CheckReceivedMessage(DateTime datetime)
  120. {
  121. }
  122. }
  123. }
  124. ```
  125. Then inject your `ISubscriberService` class in Startup.cs
  126. ```c#
  127. public void ConfigureServices(IServiceCollection services)
  128. {
  129. //Note: The injection of services needs before of `services.AddCap()`
  130. services.AddTransient<ISubscriberService,SubscriberService>();
  131. services.AddCap(x=>
  132. {
  133. //...
  134. });
  135. }
  136. ```
  137. #### Subscribe Group
  138. The concept of a subscription group is similar to that of a consumer group in Kafka. it is the same as the broadcast mode in the message queue, which is used to process the same message between multiple different microservice instances.
  139. When CAP startup, it will use the current assembly name as the default group name, if multiple same group subscribers subscribe the same topic name, there is only one subscriber can receive the message.
  140. Conversely, if subscribers are in different groups, they will all receive messages.
  141. In the same application, you can specify the `Group` property to keep they are in different subscribe groups:
  142. ```C#
  143. [CapSubscribe("xxx.services.show.time", Group = "group1" )]
  144. public void ShowTime1(DateTime datetime)
  145. {
  146. }
  147. [CapSubscribe("xxx.services.show.time", Group = "group2")]
  148. public void ShowTime2(DateTime datetime)
  149. {
  150. }
  151. ```
  152. `ShowTime1` and `ShowTime2` will be called at the same time.
  153. BTW, You can specify the default group name in the configuration :
  154. ```C#
  155. services.AddCap(x =>
  156. {
  157. x.DefaultGroup = "default-group-name";
  158. });
  159. ```
  160. ### Dashboard
  161. 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.
  162. 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.
  163. ```c#
  164. services.AddCap(x =>
  165. {
  166. //...
  167. // Register Dashboard
  168. x.UseDashboard();
  169. // Register to Consul
  170. x.UseDiscovery(d =>
  171. {
  172. d.DiscoveryServerHostName = "localhost";
  173. d.DiscoveryServerPort = 8500;
  174. d.CurrentNodeHostName = "localhost";
  175. d.CurrentNodePort = 5800;
  176. d.NodeId = 1;
  177. d.NodeName = "CAP No.1 Node";
  178. });
  179. });
  180. ```
  181. 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.
  182. ![dashboard](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220827302-189215107.png)
  183. ![received](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220934115-1107747665.png)
  184. ![subscibers](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004220949193-884674167.png)
  185. ![nodes](http://images2017.cnblogs.com/blog/250417/201710/250417-20171004221001880-1162918362.png)
  186. ## Contribute
  187. 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.
  188. ### License
  189. [MIT](https://github.com/dotnetcore/CAP/blob/master/LICENSE.txt)