DotNetCore.CAP 8.3.2-preview-248100009

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 at the same time.

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

Showing the top 20 packages that depend on DotNetCore.CAP.

Packages Downloads
ZhonTai.Admin
中台Admin权限管理接口库
91
ZhonTai.Admin
中台Admin权限管理接口库
92
ZhonTai.Admin
中台Admin权限管理接口库
94
ZhonTai.Admin
中台Admin权限管理接口库
96
ZhonTai.Admin
中台Admin权限管理接口库
97
ZhonTai.Admin
中台Admin权限管理接口库
99
ZhonTai.Admin
中台Admin权限管理接口库
100
ZhonTai.Admin
中台Admin权限管理接口库
101
ZhonTai.Admin
中台Admin权限管理接口库
107
ZhonTai.Admin
中台Admin权限管理接口库
108
ZhonTai.Admin
中台Admin权限管理接口库
109
ZhonTai.Admin
中台Admin权限管理接口库
112
ZhonTai.Admin
中台Admin权限管理接口库
113
ZhonTai.Admin
中台Admin权限管理接口库
119
ZhonTai.Admin
中台Admin权限管理接口库
120
ZhonTai.Admin.Core
中台Admin权限管理核心库
92
ZhonTai.Admin.Core
中台Admin权限管理核心库
94

Version Downloads Last updated
10.0.0 58 11/30/2025
10.0.0-preview-280318356 41 11/23/2025
8.4.1 39 10/24/2025
8.4.0 48 09/15/2025
8.4.0-preview-271338004 39 08/15/2025
8.4.0-preview-270476069 44 08/01/2025
8.4.0-preview-270285676 47 08/02/2025
8.3.5 51 05/28/2025
8.3.5-preview-262164550 48 04/26/2025
8.3.4 49 04/27/2025
8.3.3 57 03/05/2025
8.3.3-preview-255432523 52 02/09/2025
8.3.3-preview-254219859 58 01/22/2025
8.3.2 58 01/02/2025
8.3.2-preview-248100009 57 11/14/2024
8.3.1 58 11/14/2024
8.3.1-preview-247022046 55 12/10/2024
8.3.0 52 11/14/2024
8.3.0-preview-243613753 56 11/14/2024
8.2.0 55 11/14/2024
8.2.0-preview-234883029 57 11/14/2024
8.2.0-preview-233720681 54 11/28/2024
8.1.2 60 11/14/2024
8.1.1 63 04/27/2024
8.1.1-preview-230008876 53 11/14/2024
8.1.0 57 11/14/2024
8.1.0-preview-226548602 64 11/14/2024
8.1.0-preview-225165712 63 11/14/2024
8.0.1 58 02/04/2024
8.0.0 56 11/14/2024
8.0.0-preview-218723843 56 11/14/2024
8.0.0-preview-218688659 64 11/14/2024
7.2.3-preview-217562936 53 11/14/2024
7.2.3-preview-217174309 63 11/28/2024
7.2.3-preview-216527974 50 11/14/2024
7.2.2 62 11/14/2024
7.2.1 72 11/13/2024
7.2.0 64 11/14/2024
7.2.0-preview-207226127 61 11/14/2024
7.2.0-preview-207205557 52 11/14/2024
7.2.0-preview-204044155 65 11/14/2024
7.1.4 64 11/14/2024
7.1.3 68 06/16/2023
7.1.3-preview-200912175 59 11/14/2024
7.1.3-preview-200730887 53 11/14/2024
7.1.2 56 11/14/2024
7.1.2-preview-198398083 56 11/14/2024
7.1.1 62 11/14/2024
7.1.1-preview-197551401 60 11/14/2024
7.1.1-preview-196764828 59 11/14/2024
7.1.1-preview-196761499 57 11/28/2024
7.1.0 60 11/14/2024
7.1.0-preview-194230942 55 11/14/2024
7.1.0-preview-193202380 56 11/14/2024
7.0.3 52 11/27/2024
7.0.2 62 11/14/2024
7.0.2-preview-189692844 55 11/14/2024
7.0.1 58 11/14/2024
7.0.0 70 06/16/2023
7.0.0-preview-186133345 55 11/14/2024
7.0.0-preview-185881699 63 11/14/2024
7.0.0-preview-185533510 56 11/14/2024
7.0.0-preview-185469232 52 11/14/2024
7.0.0-preview-185451687 55 11/14/2024
6.2.1 62 11/14/2024
6.2.1-preview-180716003 52 11/14/2024
6.2.0 66 11/14/2024
6.1.1 51 11/14/2024
6.1.1-preview-176300030 61 11/14/2024
6.1.1-preview-175769056 55 12/02/2024
6.1.0 75 09/05/2022
6.1.0-preview-165373954 54 11/14/2024
6.1.0-preview-163077268 51 11/14/2024
6.1.0-preview-162971117 56 11/14/2024
6.0.1 58 11/14/2024
6.0.0 56 11/14/2024
6.0.0-preview-153999281 59 11/14/2024
5.2.0 56 11/14/2024
5.2.0-preview-152861792 57 11/14/2024
5.2.0-preview-150458135 62 11/14/2024
5.1.4 62 11/14/2024
5.1.4-preview-147174683 58 11/14/2024
5.1.3 58 11/14/2024
5.1.3-preview-144669387 67 11/14/2024
5.1.3-preview-144222698 61 11/14/2024
5.1.2 63 12/02/2024
5.1.2-preview-143176668 62 11/27/2024
5.1.1 54 12/07/2024
5.1.1-preview-141622241 57 11/14/2024
5.1.1-preview-140603701 64 11/26/2024
5.1.0 62 11/14/2024
5.1.0-preview-138879827 56 11/14/2024
5.0.3 66 11/14/2024
5.0.2 55 11/14/2024
5.0.2-preview-136262472 49 11/14/2024
5.0.2-preview-136113481 61 11/14/2024
5.0.2-preview-135224594 62 12/02/2024
5.0.2-preview-134636747 56 11/14/2024
5.0.1 54 11/14/2024
5.0.1-preview-133783177 53 11/27/2024
5.0.0 63 11/14/2024
5.0.0-preview-132888327 55 11/14/2024
5.0.0-preview-132124922 61 11/30/2024
5.0.0-preview-131679580 58 06/02/2024
5.0.0-preview-126609691 65 06/02/2024
3.1.2 62 11/14/2024
3.1.2-preview-121943182 60 06/02/2024
3.1.2-preview-120665033 57 06/02/2024
3.1.2-preview-120490779 63 06/02/2024
3.1.2-preview-119453473 56 06/02/2024
3.1.1 68 11/14/2024
3.1.1-preview-115802637 54 06/02/2024
3.1.0 63 11/14/2024
3.1.0-preview-114160390 58 06/02/2024
3.1.0-preview-112969177 57 06/02/2024
3.1.0-preview-112250362 63 06/02/2024
3.1.0-preview-111117527 56 06/02/2024
3.1.0-preview-108719052 59 06/02/2024
3.0.4 57 11/14/2024
3.0.4-preview-106413158 57 06/02/2024
3.0.4-preview-103991021 63 06/02/2024
3.0.4-preview-102596937 60 06/02/2024
3.0.4-preview-102593320 67 06/02/2024
3.0.3 66 11/14/2024
3.0.3-preview-98619331 58 06/02/2024
3.0.2 61 11/14/2024
3.0.2-preview-97503759 66 06/02/2024
3.0.1 57 11/14/2024
3.0.1-preview-95233114 59 06/02/2024
3.0.1-preview-94915444 64 11/14/2024
3.0.0 59 11/14/2024
3.0.0-preview-93361469 67 06/02/2024
3.0.0-preview-92995853 52 06/02/2024
3.0.0-preview-92907246 52 06/02/2024
2.6.0 55 11/14/2024
2.6.0-preview-82454970 60 06/02/2024
2.6.0-preview-82001197 62 06/02/2024
2.6.0-preview-80821564 60 06/02/2024
2.6.0-preview-79432176 66 06/02/2024
2.5.1 62 11/14/2024
2.5.1-preview-75824665 55 06/02/2024
2.5.1-preview-73792921 56 06/02/2024
2.5.1-preview-73031417 60 06/02/2024
2.5.0 61 11/14/2024
2.5.0-preview-69219007 59 06/02/2024
2.5.0-preview-69210974 63 06/02/2024
2.5.0-preview-68640186 60 06/02/2024
2.5.0-preview-67093158 54 06/02/2024
2.4.2 65 11/14/2024
2.4.2-preview-62147279 59 06/02/2024
2.4.1 64 11/27/2024
2.4.0 68 11/14/2024
2.4.0-preview-58415569 71 06/02/2024
2.4.0-preview-58238865 71 06/02/2024
2.3.1 61 11/14/2024
2.3.1-preview-57307518 62 06/02/2024
2.3.1-preview-53660607 64 06/02/2024
2.3.1-preview-53320926 67 06/02/2024
2.3.0 61 11/14/2024
2.2.6-preview-50057154 58 06/02/2024
2.2.6-preview-50053657 68 06/02/2024
2.2.6-preview-49112414 66 06/02/2024
2.2.5 63 11/14/2024
2.2.5-preview-45566217 70 06/02/2024
2.2.5-preview-45139132 60 06/02/2024
2.2.4 64 11/14/2024
2.2.3-preview-43309801 65 11/14/2024
2.2.2 65 11/14/2024
2.2.2-preview-40816597 60 06/02/2024
2.2.1 67 11/14/2024
2.2.0 73 11/14/2024
2.2.0-preview-40294348 62 06/02/2024
2.2.0-preview-38490295 69 06/02/2024
2.2.0-preview-37969809 64 06/02/2024
2.2.0-preview-37943663 59 06/02/2024
2.1.4 61 11/03/2024
2.1.4-preview-34848409 66 06/02/2024
2.1.4-preview-34825232 59 06/02/2024
2.1.4-preview-33704197 66 06/02/2024
2.1.3 66 11/14/2024
2.1.3-preview-33358922 74 06/02/2024
2.1.3-preview-33191223 73 06/02/2024
2.1.3-preview-31198104 62 06/02/2024
2.1.2 65 11/14/2024
2.1.2-preview-30288174 59 06/02/2024
2.1.2-preview-30286136 63 06/02/2024
2.1.2-preview-29226626 59 06/02/2024
2.1.2-preview-28879945 66 06/02/2024
2.1.2-preview-28782089 70 06/02/2024
2.1.1 60 11/14/2024
2.1.1-preview-28628301 71 06/02/2024
2.1.1-preview-28414190 66 06/02/2024
2.1.0 61 11/14/2024
2.1.0-preview-26231671 66 06/02/2024
2.1.0-preview-25885614 57 06/02/2024
2.0.2 66 11/14/2024
2.0.1 63 11/14/2024
2.0.1-preview-21560113 67 06/02/2024
2.0.1-preview-21392243 63 06/02/2024
2.0.0 62 11/14/2024
2.0.0-preview-20091963 58 06/02/2024
2.0.0-preview-19793485 94 06/02/2024
1.2.0-preview-00019208119 63 05/28/2024
1.1.1-preview-00018720262 63 05/28/2024
1.1.0 64 12/03/2024
1.1.0-preview-00018359725 61 05/28/2024
1.1.0-preview-00018287510 64 05/28/2024
1.1.0-preview-00018199934 64 05/28/2024
1.1.0-preview-00017833331 63 05/28/2024
1.1.0-preview-00017748473 58 05/28/2024
1.0.1 66 11/14/2024
1.0.1-preview-00017636063 63 05/28/2024
1.0.1-preview-00017490435 61 05/28/2024
1.0.1-preview-00017285652 62 05/28/2024
1.0.0 62 11/14/2024
0.1.0-ci-00016390477 58 11/14/2024
0.1.0-ci-00016261636 61 11/14/2024
0.1.0-ci-00016020116 55 11/14/2024
0.1.0-ci-00016011622 55 11/14/2024
0.1.0-ci-00015583876 62 11/14/2024