DotNetCore.CAP 8.3.0-preview-243613753

This is a prerelease version of DotNetCore.CAP.
dotnet add package DotNetCore.CAP --version 8.3.0-preview-243613753                
NuGet\Install-Package DotNetCore.CAP -Version 8.3.0-preview-243613753                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DotNetCore.CAP" Version="8.3.0-preview-243613753" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DotNetCore.CAP --version 8.3.0-preview-243613753                
#r "nuget: DotNetCore.CAP, 8.3.0-preview-243613753"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install DotNetCore.CAP as a Cake Addin
#addin nuget:?package=DotNetCore.CAP&version=8.3.0-preview-243613753&prerelease

// Install DotNetCore.CAP as a Cake Tool
#tool nuget:?package=DotNetCore.CAP&version=8.3.0-preview-243613753&prerelease                

<p align="center"> <img height="140" src="https://raw.githubusercontent.com/dotnetcore/CAP/master/docs/content/img/logo.svg"> </p>

CAP                     中文

Docs&Dashboard AppVeyor NuGet NuGet Preview Member project of .NET Core Community GitHub license

CAP is a library based on .Net standard, which is a solution to deal with distributed transactions, has the function of EventBus, it is lightweight, easy to use, and efficient.

In the process of building an SOA or MicroService system, we usually need to use the event to integrate each service. In the process, simple use of message queue does not guarantee reliability. CAP adopts local message table program integrated with the current database to solve exceptions that 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 CAP as an EventBus. CAP provides a simpler way to implement event publishing and subscriptions. You do not need to inherit or implement any interface during subscription and sending process.

Architecture overview

cap.png

CAP implements the Outbox Pattern described in the eShop ebook.

Getting Started

NuGet

CAP can be installed in your project with the following command.

PM> Install-Package DotNetCore.CAP

CAP supports most popular message queue as transport, following packages are available to install:

PM> Install-Package DotNetCore.CAP.Kafka
PM> Install-Package DotNetCore.CAP.RabbitMQ
PM> Install-Package DotNetCore.CAP.AzureServiceBus
PM> Install-Package DotNetCore.CAP.AmazonSQS
PM> Install-Package DotNetCore.CAP.NATS
PM> Install-Package DotNetCore.CAP.RedisStreams
PM> Install-Package DotNetCore.CAP.Pulsar

CAP supports most popular database as event storage, following packages are available to install:

// 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

First, you need to configure CAP in your Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    //......

    services.AddDbContext<AppDbContext>(); //Options, If you are using EF as the ORM
    services.AddSingleton<IMongoClient>(new MongoClient("")); //Options, If you are using MongoDB

    services.AddCap(x =>
    {
        // If you are using EF, you need to add the configuration:
        x.UseEntityFramework<AppDbContext>(); //Options, Notice: You don't need to config x.UseSqlServer(""") again! CAP can autodiscovery.

        // If you are using ADO.NET, choose to add configuration you needed:
        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

        // CAP support RabbitMQ,Kafka,AzureService as the MQ, choose to add configuration you needed:
        x.UseRabbitMQ("HostName");
        x.UseKafka("ConnectionString");
        x.UseAzureServiceBus("ConnectionString");
        x.UseAmazonSQS();
    });
}

Publish

Inject ICapPublisher in your Controller, then use the ICapPublisher to send messages.

The version 7.0+ supports publish delay messages.

public class PublishController : Controller
{
    private readonly ICapPublisher _capBus;

    public PublishController(ICapPublisher capPublisher)
    {
        _capBus = capPublisher;
    }

    [Route("~/adonet/transaction")]
    public IActionResult AdonetWithTransaction()
    {
        using (var connection = new MySqlConnection(ConnectionString))
        {
            using (var transaction = connection.BeginTransaction(_capBus, autoCommit: true))
            {
                //your business logic code

                _capBus.Publish("xxx.services.show.time", DateTime.Now);

                // Publish delay message
                _capBus.PublishDelayAsync(TimeSpan.FromSeconds(delaySeconds), "xxx.services.show.time", DateTime.Now);
            }
        }

        return Ok();
    }

    [Route("~/ef/transaction")]
    public IActionResult EntityFrameworkWithTransaction([FromServices]AppDbContext dbContext)
    {
        using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: true))
        {
            //your business logic code

            _capBus.Publish("xxx.services.show.time", DateTime.Now);
        }

        return Ok();
    }
}

Subscribe

In Controller Action

Add the Attribute [CapSubscribe()] on Action to subscribe to messages:

public class PublishController : Controller
{
    [CapSubscribe("xxx.services.show.time")]
    public void CheckReceivedMessage(DateTime datetime)
    {
        Console.WriteLine(datetime);
    }
}

In Business Logic Service

If your subscription method is not in the Controller, then your subscribe class needs to implement ICapSubscribe interface:


namespace BusinessCode.Service
{
    public interface ISubscriberService
    {
        void CheckReceivedMessage(DateTime datetime);
    }

    public class SubscriberService: ISubscriberService, ICapSubscribe
    {
        [CapSubscribe("xxx.services.show.time")]
        public void CheckReceivedMessage(DateTime datetime)
        {
        }
    }
}

Then register your class that implements ISubscriberService in Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<ISubscriberService,SubscriberService>();

    services.AddCap(x=>
    {
        //...
    });
}
Async subscription

You are able to implement async subscription. Subscription's method should return Task and receive CancellationToken as parameter.

public class AsyncSubscriber : ICapSubscribe
{
    [CapSubscribe("name")]
    public async Task ProcessAsync(Message message, CancellationToken cancellationToken)
    {
        await SomeOperationAsync(message, cancellationToken);
    }
}
Use partials for topic subscriptions

To group topic subscriptions on class level you're able to define a subscription on a method as a partial. Subscriptions on the message queue will then be a combination of the topic defined on the class and the topic defined on the method. In the following example the Create(..) function will be invoked when receiving a message on customers.create

[CapSubscribe("customers")]
public class CustomersSubscriberService : ICapSubscribe
{
    [CapSubscribe("create", isPartial: true)]
    public void Create(Customer customer)
    {
    }
}
Subscribe Group

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.

When CAP startups, it will use the current assembly name as the default group name, if multiple same group subscribers subscribe to the same topic name, there is only one subscriber that can receive the message. Conversely, if subscribers are in different groups, they will all receive messages.

In the same application, you can specify Group property to keep subscriptions in different subscribe groups:


[CapSubscribe("xxx.services.show.time", Group = "group1" )]
public void ShowTime1(DateTime datetime)
{
}

[CapSubscribe("xxx.services.show.time", Group = "group2")]
public void ShowTime2(DateTime datetime)
{
}

ShowTime1 and ShowTime2 will be called one after another because all received messages are processed linear. You can change that behaviour to set UseDispatchingPerGroup true.

BTW, You can specify the default group name in the configuration:

services.AddCap(x =>
{
    x.DefaultGroup = "default-group-name";  
});

Dashboard

CAP also provides dashboard pages, you can easily view messages that were sent and received. In addition, you can also view the message status in real time in the dashboard. Use the following command to install the Dashboard in your project.

PM> Install-Package DotNetCore.CAP.Dashboard

In the distributed environment, the dashboard built-in integrates Consul 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.

View Consul config docs

If your service is deployed in Kubernetes, please use our Kubernetes discovery package.

PM> Install-Package DotNetCore.CAP.Dashboard.K8s

View Kubernetes config docs

The dashboard default address is: http://localhost:xxx/cap , you can configure relative path /cap with x.UseDashboard(opt =>{ opt.MatchPath="/mycap"; }).

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

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (235)

Showing the top 5 NuGet packages that depend on DotNetCore.CAP:

Package Downloads
DotNetCore.CAP.RabbitMQ

Distributed transaction solution in micro-service base on eventually consistency, also an eventbus with Outbox pattern.

DotNetCore.CAP.Dashboard

Distributed transaction solution in micro-service base on eventually consistency, also an eventbus with Outbox pattern.

DotNetCore.CAP.SqlServer

Distributed transaction solution in micro-service base on eventually consistency, also an eventbus with Outbox pattern.

DotNetCore.CAP.InMemoryStorage

Distributed transaction solution in micro-service base on eventually consistency, also an eventbus with Outbox pattern.

DotNetCore.CAP.PostgreSql

Distributed transaction solution in micro-service base on eventually consistency, also an eventbus with Outbox pattern.

GitHub repositories (21)

Showing the top 5 popular GitHub repositories that depend on DotNetCore.CAP:

Repository Stars
SkyAPM/SkyAPM-dotnet
The .NET/.NET Core instrument agent for Apache SkyWalking
AlphaYu/adnc
.NET微服务/分布式开发框架,同时也适用于单体架构系统的开发。
bing-framework/Bing.NetCore
Bing是基于 .net core 3.1 的框架,旨在提升团队的开发输出能力,由常用公共操作类(工具类、帮助类)、分层架构基类,第三方组件封装,第三方业务接口封装等组成。
colinin/abp-next-admin
这是基于vue-vben-admin 模板适用于abp Vnext的前端管理项目
91270/Meiam.System
.NET 8 / .NET 5 WebAPI + Vue 2.0 + RBAC 企业级前后端分离权限框架
Version Downloads Last updated
8.3.0-preview-243613753 415 9/20/2024
8.2.0 78,377 6/23/2024
8.2.0-preview-234883029 6,529 6/11/2024
8.2.0-preview-233720681 398 5/29/2024
8.1.2 100,744 5/7/2024
8.1.1 29,801 4/21/2024
8.1.1-preview-230008876 388 4/16/2024
8.1.0 39,910 3/19/2024
8.1.0-preview-226548602 734 3/7/2024
8.1.0-preview-225165712 47,454 2/20/2024
8.0.1 131,906 1/25/2024
8.0.0 187,974 12/14/2023
8.0.0-preview-218723843 1,800 12/7/2023
8.0.0-preview-218688659 1,573 12/7/2023
7.2.3-preview-217562936 4,447 11/24/2023
7.2.3-preview-217174309 1,612 11/19/2023
7.2.3-preview-216527974 4,998 11/12/2023
7.2.2 91,426 11/1/2023
7.2.1 158,558 9/8/2023
7.2.0 111,260 7/30/2023
7.2.0-preview-207226127 2,252 7/27/2023
7.2.0-preview-207205557 2,241 7/27/2023
7.2.0-preview-204044155 7,347 6/20/2023
7.1.4 72,111 6/17/2023
7.1.3 70,541 5/17/2023
7.1.3-preview-200912175 2,320 5/15/2023
7.1.3-preview-200730887 2,218 5/13/2023
7.1.2 43,632 4/25/2023
7.1.2-preview-198398083 2,266 4/16/2023
7.1.1 60,899 4/7/2023
7.1.1-preview-197551401 2,315 4/6/2023
7.1.1-preview-196764828 5,241 3/28/2023
7.1.1-preview-196761499 2,264 3/28/2023
7.1.0 193,703 3/5/2023
7.1.0-preview-194230942 2,817 2/27/2023
7.1.0-preview-193202380 2,551 2/15/2023
7.0.3 64,745 2/2/2023
7.0.2 60,732 1/9/2023
7.0.2-preview-189692844 2,370 1/9/2023
7.0.1 52,357 12/16/2022
7.0.0 332,507 11/27/2022
7.0.0-preview-186133345 2,308 11/25/2022
7.0.0-preview-185881699 2,346 11/22/2022
7.0.0-preview-185533510 2,241 11/18/2022
7.0.0-preview-185469232 2,216 11/18/2022
7.0.0-preview-185451687 2,266 11/17/2022
6.2.1 566,571 10/15/2022
6.2.1-preview-180716003 3,715 9/23/2022
6.2.0 95,309 9/19/2022
6.1.1 6,346 9/19/2022
6.1.1-preview-176300030 3,109 8/3/2022
6.1.1-preview-175769056 2,804 7/28/2022
6.1.0 608,706 6/10/2022
6.1.0-preview-165373954 3,459 3/30/2022
6.1.0-preview-163077268 3,814 3/3/2022
6.1.0-preview-162971117 2,779 3/2/2022
6.0.1 504,665 2/15/2022
6.0.0 266,539 1/6/2022
6.0.0-preview-153999281 5,494 11/18/2021
5.2.0 319,334 11/12/2021
5.2.0-preview-152861792 3,455 11/5/2021
5.2.0-preview-150458135 3,996 10/8/2021
5.1.4 190,160 9/29/2021
5.1.4-preview-147174683 15,400 8/31/2021
5.1.3 127,846 8/18/2021
5.1.3-preview-144669387 8,746 8/2/2021
5.1.3-preview-144222698 3,564 7/28/2021
5.1.2 149,127 7/26/2021
5.1.2-preview-143176668 3,784 7/16/2021
5.1.1 126,440 7/9/2021
5.1.1-preview-141622241 3,483 6/29/2021
5.1.1-preview-140603701 3,346 6/16/2021
5.1.0 91,136 6/7/2021
5.1.0-preview-138879827 3,396 5/27/2021
5.0.3 98,271 5/14/2021
5.0.2 60,711 4/28/2021
5.0.2-preview-136262472 3,229 4/27/2021
5.0.2-preview-136113481 3,323 4/25/2021
5.0.2-preview-135224594 3,324 4/15/2021
5.0.2-preview-134636747 3,155 4/8/2021
5.0.1 109,330 4/7/2021
5.0.1-preview-133783177 3,181 3/29/2021
5.0.0 30,271 3/23/2021
5.0.0-preview-132888327 3,303 3/19/2021
5.0.0-preview-132124922 4,438 3/10/2021
5.0.0-preview-131679580 4,525 3/5/2021
5.0.0-preview-126609691 9,980 1/5/2021
3.1.2 643,971 12/3/2020
3.1.2-preview-121943182 4,069 11/12/2020
3.1.2-preview-120665033 3,981 10/29/2020
3.1.2-preview-120490779 3,928 10/26/2020
3.1.2-preview-119453473 4,097 10/14/2020
3.1.1 384,281 9/23/2020
3.1.1-preview-115802637 3,922 9/2/2020
3.1.0 471,775 8/15/2020
3.1.0-preview-114160390 3,958 8/14/2020
3.1.0-preview-112969177 7,251 7/31/2020
3.1.0-preview-112250362 4,096 7/23/2020
3.1.0-preview-111117527 4,871 7/10/2020
3.1.0-preview-108719052 4,523 6/12/2020
3.0.4 195,338 5/27/2020
3.0.4-preview-106413158 3,687 5/16/2020
3.0.4-preview-103991021 4,737 4/18/2020
3.0.4-preview-102596937 8,028 4/2/2020
3.0.4-preview-102593320 3,781 4/2/2020
3.0.3 104,732 4/1/2020
3.0.3-preview-98619331 14,864 2/16/2020
3.0.2 71,817 2/5/2020
3.0.2-preview-97503759 3,958 2/3/2020
3.0.1 26,616 1/19/2020
3.0.1-preview-95233114 3,937 1/8/2020
3.0.1-preview-94915444 4,266 1/4/2020
3.0.0 89,922 12/30/2019
3.0.0-preview-93361469 4,860 12/17/2019
3.0.0-preview-92995853 4,111 12/13/2019
3.0.0-preview-92907246 3,938 12/12/2019
2.6.0 206,051 8/29/2019
2.6.0-preview-82454970 6,148 8/14/2019
2.6.0-preview-82001197 5,739 8/8/2019
2.6.0-preview-80821564 4,655 7/25/2019
2.6.0-preview-79432176 6,239 7/9/2019
2.5.1 122,332 6/21/2019
2.5.1-preview-75824665 12,010 5/28/2019
2.5.1-preview-73792921 4,781 5/5/2019
2.5.1-preview-73031417 4,421 4/26/2019
2.5.0 187,956 3/30/2019
2.5.0-preview-69219007 6,898 3/14/2019
2.5.0-preview-69210974 4,352 3/13/2019
2.5.0-preview-68640186 21,019 3/6/2019
2.5.0-preview-67093158 4,361 2/16/2019
2.4.2 48,671 1/8/2019
2.4.2-preview-62147279 4,509 12/21/2018
2.4.1 5,829 12/19/2018
2.4.0 6,710 12/8/2018
2.4.0-preview-58415569 4,640 11/8/2018
2.4.0-preview-58238865 4,418 11/6/2018
2.3.1 34,364 10/29/2018
2.3.1-preview-57307518 4,426 10/26/2018
2.3.1-preview-53660607 4,295 9/25/2018
2.3.1-preview-53320926 4,477 9/10/2018
2.3.0 36,410 8/30/2018
2.2.6-preview-50057154 4,541 8/3/2018
2.2.6-preview-50053657 4,460 8/3/2018
2.2.6-preview-49112414 4,343 7/23/2018
2.2.5 9,460 7/19/2018
2.2.5-preview-45566217 4,372 6/12/2018
2.2.5-preview-45139132 4,549 6/7/2018
2.2.4 15,500 6/5/2018
2.2.3-preview-43309801 4,654 5/17/2018
2.2.2 24,499 4/28/2018
2.2.2-preview-40816597 4,597 4/18/2018
2.2.1 7,888 4/18/2018
2.2.0 6,381 4/17/2018
2.2.0-preview-40294348 4,312 4/12/2018
2.2.0-preview-38490295 4,556 3/23/2018
2.2.0-preview-37969809 5,299 3/16/2018
2.2.0-preview-37943663 4,158 3/16/2018
2.1.4 6,217 3/16/2018
2.1.4-preview-34848409 5,997 2/8/2018
2.1.4-preview-34825232 4,379 2/8/2018
2.1.4-preview-33704197 4,369 1/26/2018
2.1.3 11,443 1/24/2018
2.1.3-preview-33358922 4,292 1/22/2018
2.1.3-preview-33191223 4,286 1/20/2018
2.1.3-preview-31198104 5,565 12/28/2017
2.1.2 6,983 12/18/2017
2.1.2-preview-30288174 4,500 12/17/2017
2.1.2-preview-30286136 4,312 12/17/2017
2.1.2-preview-29226626 4,371 12/5/2017
2.1.2-preview-28879945 4,327 12/1/2017
2.1.2-preview-28782089 4,142 12/1/2017
2.1.1 5,429 11/28/2017
2.1.1-preview-28628301 4,349 11/28/2017
2.1.1-preview-28414190 4,328 11/26/2017
2.1.0 5,753 11/17/2017
2.1.0-preview-26231671 4,797 10/31/2017
2.1.0-preview-25885614 4,142 10/30/2017
2.0.2 5,326 9/29/2017
2.0.1 5,498 9/16/2017
2.0.1-preview-21560113 4,196 9/7/2017
2.0.1-preview-21392243 4,217 9/5/2017
2.0.0 5,576 9/1/2017
2.0.0-preview-20091963 4,234 8/21/2017
2.0.0-preview-19793485 4,106 8/18/2017
1.2.0-preview-00019208119 4,109 8/11/2017
1.1.1-preview-00018720262 3,979 8/5/2017
1.1.0 5,830 8/4/2017
1.1.0-preview-00018359725 4,152 8/1/2017
1.1.0-preview-00018287510 4,098 8/1/2017
1.1.0-preview-00018199934 4,184 7/30/2017
1.1.0-preview-00017833331 4,226 7/27/2017
1.1.0-preview-00017748473 4,094 7/25/2017
1.0.1 5,042 7/24/2017
1.0.1-preview-00017636063 4,083 7/24/2017
1.0.1-preview-00017490435 4,010 7/22/2017
1.0.1-preview-00017285652 3,940 7/20/2017
1.0.0 8,565 7/19/2017
0.1.0-ci-00016390477 3,826 7/9/2017
0.1.0-ci-00016261636 3,967 7/8/2017
0.1.0-ci-00016020116 4,017 7/5/2017
0.1.0-ci-00016011622 4,039 7/5/2017
0.1.0-ci-00015583876 4,179 6/30/2017