Log In
Default credentials: bob/bob
[](https://github.com/dotnetcore/CAP/actions/workflows/deploy-docs-and-dashboard.yml)
[](https://ci.appveyor.com/project/yuleyule66/cap/branch/master)
[](https://www.nuget.org/packages/DotNetCore.CAP/)
[](https://www.nuget.org/packages/DotNetCore.CAP/)
[](https://raw.githubusercontent.com/dotnetcore/CAP/master/LICENSE.txt)
[](https://github.com/dotnetcore)
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 efficient.
## Introduction
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.
!!! Tip "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)"
> Atomicity when publishing events to the event bus with a worker microservice
For detailed instructions see the [Getting Started Guide][1].
[1]: user-guide/en/getting-started/quick-start.md
## Contributing
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.
If you have any question or problems, please report them on the CAP repository:
## License
CAP is licensed under the [MIT license](about/license.md).
================================================
FILE: docs/content/user-guide/en/cap/configuration.md
================================================
# Configuration
By default, you specify configurations when registering CAP services in the DI container for an ASP.NET Core project.
```c#
services.AddCap(config =>
{
// config.XXX
});
```
`services` is an `IServiceCollection` interface, which can be found in the `Microsoft.Extensions.DependencyInjection` package.
## Minimum Configuration Required
You must configure at least one transport and one storage. If you want to get started quickly, you can use the following configuration:
```C#
services.AddCap(capOptions =>
{
capOptions.UseInMemoryQueue(); // Requires the Savorboard.CAP.InMemoryMessageQueue NuGet package.
capOptions.UseInMemoryStorage();
});
```
For transport and storage configuration options provided by specific components, see the [Transports](../transport/general.md) and [Storage](../storage/general.md) sections.
## Configuration in Subscribers
Subscribers use the `[CapSubscribe]` attribute to mark themselves as subscribers. They can be located in an ASP.NET Core Controller or Service.
When you declare `[CapSubscribe]`, you can change the behavior of the subscriber by specifying the following parameters.
### Name
> string, required
Subscribe to messages by specifying the `Name` parameter. This corresponds to the name specified when publishing the message through `_cap.Publish("Name")`.
This name corresponds to different items in different message brokers:
- In RabbitMQ, it corresponds to the Routing Key.
- In Kafka, it corresponds to the Topic.
- In Azure Service Bus, it corresponds to the Subject.
- In NATS, it corresponds to the Subject.
- In Redis Streams, it corresponds to the Stream.
### Group
> string, optional
Specify the `Group` parameter to place subscribers within a separate consumer group, a concept similar to consumer groups in Kafka. If this parameter is not specified, the current assembly name (`DefaultGroupName`) is used as the default.
Subscribers with the same `Name` but set to **different** groups will all receive messages. Conversely, if subscribers with the same `Name` are set to the **same** group, only one will receive the message.
It also makes sense for subscribers with different `Names` to be set to **different** groups; they can have independent threads for execution. Conversely, if subscribers with different `Names` are set to the **same** group, they will share consumption threads.
Group corresponds to different items in different message brokers:
- In RabbitMQ, it corresponds to Queue.
- In Kafka, it corresponds to Consumer Group.
- In Azure Service Bus, it corresponds to Subscription Name.
- In NATS, it corresponds to Queue Group.
- In Redis Streams, it corresponds to Consumer Group.
### GroupConcurrent
> byte, optional
Set the parallelism of concurrent execution for subscribers by specifying the value of the `GroupConcurrent` parameter. Concurrent execution means that it needs to run on an independent thread, so if you do not specify the `Group` parameter, CAP will automatically create a Group using the value of `Name`.
!!! Note
If you have multiple subscribers configured with the same Group and have also set the `GroupConcurrent` value for them, the degree of parallelism is the sum of the values in the group.
This setting applies only to new messages; retried messages are not subject to the concurrency limit.
## Custom Configuration
The `CapOptions` class is used to store configuration information. By default, all options have default values. Sometimes you may need to customize them.
#### DefaultGroupName
> Default: cap.queue.{assembly name}
The default consumer group name. It corresponds to different names in different transports. You can customize this value to customize the names in different transports for easy viewing.
!!! info "Mapping"
Maps to [Queue Names](https://www.rabbitmq.com/queues.html#names) in RabbitMQ.
Maps to [Consumer Group Id](http://kafka.apache.org/documentation/#group.id) in Apache Kafka.
Maps to Subscription Name in Azure Service Bus.
Maps to [Queue Group Name](https://docs.nats.io/nats-concepts/queue) in NATS.
Maps to [Consumer Group](https://redis.io/topics/streams-intro#creating-a-consumer-group) in Redis Streams.
#### GroupNamePrefix
> Default: Null
Add unified prefixes to consumer group names. https://github.com/dotnetcore/CAP/pull/780
#### TopicNamePrefix
> Default: Null
Add unified prefixes to topic/queue names. https://github.com/dotnetcore/CAP/pull/780
#### Version
> Default: v1
Used to specify a version for a message to isolate messages of different versions across services. This is useful for A/B testing or multi-service version scenarios. The following are application scenarios that require versioning:
!!! info "Business Iteration and Backward Compatibility"
Due to rapid iteration of business logic, the message data structure may change during service integration. Sometimes we add or modify data structures to accommodate new requirements. If you have a brand new system, this is not a problem. However, if your system is already deployed to production and serving customers, new features can become incompatible with old data structures when released online, which can cause serious issues. To work around this problem, you would need to clear all message queues and persistent messages before restarting the application, which is obviously unacceptable for production environments.
!!! info "Multiple Server Versions"
Sometimes, the server needs to provide multiple sets of interfaces to support different versions of the client application. The data structures for the same interface interactions between different app versions and the server may differ, so the server typically provides different routing addresses to accommodate different client versions.
!!! info "Different Instances Using the Same Storage Table/Collection"
If you want multiple service instances to share the same database, you can isolate database tables for different instances by specifying different table names. This can be achieved through CAP configuration by setting different table name prefixes.
> Check out the blog to learn more about the Version feature: https://www.cnblogs.com/savorboard/p/cap-2-4.html
#### FailedRetryInterval
> Default: 60 sec
During the message sending process, if message transmission fails, CAP will retry sending. This configuration option specifies the interval between each retry attempt.
During the message consumption process, if the consumer method fails, CAP will retry execution. This configuration option specifies the interval between each retry attempt.
!!! WARNING "Retry & Interval"
By default, if a failure occurs during send or consume operations, retry will begin after **4 minutes** (FallbackWindowLookbackSeconds) to avoid potential issues caused by message state delays.
Send and consume failures are retried 3 times immediately. After the initial 3 attempts, retries follow a polling schedule, at which point the FailedRetryInterval configuration takes effect.
!!! WARNING "Multi-instance Concurrent Retries"
Version 7.1.0 introduced database-based distributed locks to solve the problem of concurrent database fetches during retry operations across multiple instances. You must explicitly set `UseStorageLock` to true to enable this.
#### UseStorageLock
> Default: false
If set to true, we will use a database-based distributed lock to handle concurrent data fetches by retry processes across multiple instances. This will generate the cap.lock table in the database.
#### CollectorCleaningInterval
> Default: 300 sec
The interval at which the collector deletes expired messages.
#### SchedulerBatchSize
> Default: 1000
Maximum number of delayed or queued messages fetched per scheduler cycle.
#### ConsumerThreadCount
> Default: 1
Number of consumer threads. When this value is greater than 1, the order of message execution cannot be guaranteed.
#### FailedRetryCount
> Default: 50
Maximum number of retries. When this count is reached, retries will stop. You can modify this parameter to set the maximum retry attempts.
#### FallbackWindowLookbackSeconds
> Default: 240 sec
Configures the retry processor to pick up messages with `Scheduled` or `Failed` status within the lookback time window.
#### FailedThresholdCallback
> Default: NULL
Type: `Action
### Context Propagation
CAP supports [Context Propagation](https://opentelemetry.io/docs/instrumentation/js/propagation/) by injecting `traceparent` and `baggage` headers when sending messages and restoring the context from those headers when receiving messages.
CAP uses the configured `Propagators.DefaultTextMapPropagator` propagator, which is usually set to both `TraceContextPropagator` and `BaggagePropagator` by the [dotnet OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/Sdk.cs#L21), but can be configured in your client program. For example, to opt out of Baggage propagation, you can call:
```C#
OpenTelemetry.Sdk.SetDefaultTextMapPropagator(
new TraceContextPropagator());
```
For more details, see the [dotnet OpenTelemetry.Api README](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Api/README.md?plain=1#L455).
================================================
FILE: docs/content/user-guide/en/samples/eshoponcontainers.md
================================================
# eShopOnContainers
eShopOnContainers is a sample application written in C# running on .NET Core that uses a microservice architecture and Domain Driven Design.
> A .NET Core reference application powered by Microsoft, based on a simplified microservices architecture with Docker containers.
> This reference application is cross-platform on both server and client sides, thanks to .NET Core services that can run on Linux or Windows containers depending on your Docker host, and Xamarin for mobile apps running on Android, iOS, or Windows/UWP, plus any browser for client web apps.
> The architecture demonstrates a microservice-oriented implementation with multiple autonomous microservices (each owning its own data/database) and implementing different approaches within each microservice (simple CRUD vs. DDD/CQRS patterns). It uses HTTP as the communication protocol between client apps and microservices, and supports asynchronous communication for data propagation across services based on Integration Events and an Event Bus (a lightweight message broker that you can choose between RabbitMQ or Azure Service Bus) plus other features in the roadmap.
## eShopOnContainers with CAP
You can see how to use CAP in eShopOnContainers in the GitHub repository:
https://github.com/yang-xiaodong/eShopOnContainers
================================================
FILE: docs/content/user-guide/en/samples/faq.md
================================================
# FAQ
!!! faq "Is there an IM group (e.g., Tencent QQ group) to learn and chat about CAP?"
There is not. Instead of spending time in IM groups, I encourage developers to develop independent thinking skills and solve problems using the documentation. You can also create issues or send emails if problems persist.
!!! faq "Does each application need a separate database for producer and consumer in CAP?"
Not necessarily. A recommendation is to use a dedicated database for each application. However, see the Q&A below for alternatives.
!!! faq "How can I use the same database for different applications?"
Define a table prefix name in the `ConfigureServices` method.
Code example:
```c#
public void ConfigureServices(IServiceCollection services)
{
services.AddCap(x =>
{
x.UseKafka("");
x.UseMySql(opt =>
{
opt.ConnectionString = "connection string";
opt.TableNamePrefix = "appone"; // Use different table name prefix here
});
});
}
```
!!! faq "Can CAP avoid using the database for event storage? I just want to send messages."
Not yet. CAP's purpose is to ensure consistency in microservice or SOA architectures. The solution is based on ACID features of the database. There's no point in a simple message queue wrapper without database support.
!!! faq "If the consumer fails, can I roll back the SQL executed by the producer?"
No, you cannot roll back. CAP provides eventual consistency, not immediate rollback.
Consider a scenario where you call a third-party payment service. If you successfully call Alipay's interface but your own code fails afterward, will Alipay roll back? If not, what should you do? The same principle applies here.
================================================
FILE: docs/content/user-guide/en/samples/github.md
================================================
# GitHub Samples
You can find sample code in the GitHub repository:
https://github.com/dotnetcore/CAP/tree/master/samples
CAP + Aspire + Azure Service Bus + Azure SQL:
https://github.com/NikiforovAll/cap-aspire
================================================
FILE: docs/content/user-guide/en/storage/general.md
================================================
# General
CAP requires a storage medium with persistence capabilities to store event messages in databases or other NoSQL facilities. CAP uses this approach to protect against message loss in any environment or network issues. Reliability of messages is the cornerstone of distributed transactions, so messages must never be lost.
## Persistence
### Before Sent
Before the message enters the message queue, CAP persists the message in a local database table. This ensures that the message is not lost when the message queue is unavailable or a network error occurs.
To ensure the reliability of this mechanism, CAP uses the same database transactions as the business code to ensure that business operations and CAP messages are consistent during persistence. If any exception occurs during message persistence, the database will roll back.
### After Sent
After the message enters the message queue, CAP starts the persistence function of the message queue. Here's how CAP messages are persisted in RabbitMQ and Kafka.
For message persistence in RabbitMQ, CAP uses a consumer queue with message persistence, though exceptions may occur.
!!! info "Ready for Production?"
By default, queues registered by CAP in RabbitMQ are persistent. For production use, we recommend that you start all consumers once to create persistent queues. This ensures all queues are created before messages are sent.
Since Kafka has built-in message persistence using files, it automatically ensures that messages are properly persisted without loss once they enter Kafka.
## Storage
### Supported storages
CAP supports the following types of transaction-enabled databases for storage:
* [SQL Server](sqlserver.md)
* [MySQL](mysql.md)
* [PostgreSql](postgresql.md)
* [MongoDB](mongodb.md)
* [In-Memory Storage](in-memory-storage.md)
After CAP is started, two tables are generated in used storage, by default the name is `Cap.Published` and `Cap.Received`.
### Storage Data Structure
Table structure of **Published** :
NAME | DESCRIPTION | TYPE
:---|:---|:---
Id | Message Id | int
Version | Message Version | string
Name | Topic Name | string
Content | Json Content | string
Added | Added Time | DateTime
ExpiresAt | Expire time | DateTime
Retries | Retry times | int
StatusName | Status Name | string
Table structure of **Received** :
NAME | DESCRIPTION | TYPE
:---|:---|:---
Id | Message Id | int
Version | Message Version | string
Name | Topic Name | string
Group | Group Name | string
Content | Json Content | string
Added | Added Time | DateTime
ExpiresAt | Expire time | DateTime
Retries | Retry times | int
StatusName | Status Name | string
Table structure of **Lock** (Optional):
NAME | DESCRIPTION | TYPE
:---|:---|:---
Key | Lock Id | string
Instance | Acquired instance of lock | string
LastLockTime | Last acquired lock time | DateTime
### Wapper Object
When CAP sends a message, it will store original message object in a second package in the `Content` field.
The following is the **Wapper Object** data structure of Content field.
NAME | DESCRIPTION | TYPE
:---|:---|:---
Id | Message Id | string
Timestamp | Message created time | string
Content | Message content | string
CallbackName | Consumer callback topic name | string
The `Id` field is generate using the mongo [objectid algorithm](https://www.mongodb.com/blog/post/generating-globally-unique-identifiers-for-use-with-mongodb).
## Community-supported extensions
Thanks to the community for supporting CAP, the following is the implementation of community-supported storage
* SQLite ([@colinin](https://github.com/colinin)) ：https://github.com/colinin/DotNetCore.CAP.Sqlite
* LiteDB ([@maikebing](https://github.com/maikebing)) ：https://github.com/maikebing/CAP.Extensions
* SQLite & Oracle ([@cocosip](https://github.com/cocosip)) ：https://github.com/cocosip/CAP-Extensions
================================================
FILE: docs/content/user-guide/en/storage/in-memory-storage.md
================================================
# In-Memory Storage
In-memory storage is commonly used in development and test environments. However, if you use memory-based storage, you lose the reliability guarantee of local transaction messages.
## Configuration
To use in-memory storage, you need to install the following package from NuGet:
```powershell
PM> Install-Package DotNetCore.CAP.InMemoryStorage
```
Next, add configuration items to the `ConfigureServices` method of `Startup.cs`.
```csharp
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddCap(x =>
{
x.UseInMemoryStorage();
// x.UseXXX ...
});
}
```
CAP will clean successful messages from memory every 5 minutes.
## Publish with transaction
In-memory storage does **not support** transactional message publishing.
================================================
FILE: docs/content/user-guide/en/storage/mongodb.md
================================================
# MongoDB
MongoDB is a cross-platform, document-oriented database program. Classified as a NoSQL database, MongoDB uses JSON-like documents with dynamic schema.
CAP has supported MongoDB since version 2.3. MongoDB supports ACID transactions starting from version 4.0, so CAP requires MongoDB 4.0 or higher. Additionally, MongoDB must be deployed as a cluster because ACID transactions require a replica set.
For a quick development of the MongoDB 4.0+ cluster for the development environment, you can refer to [this article](https://www.cnblogs.com/savorboard/p/mongodb-4-cluster-install.html).
## Configuration
To use MongoDB storage, you need to install the following package from NuGet:
```powershell
PM> Install-Package DotNetCore.CAP.MongoDB
```
Next, add configuration items to the `ConfigureServices` method of `Startup.cs`.
```csharp
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddCap(x =>
{
x.UseMongoDB(opt=>{
//MongoDBOptions
});
// x.UseXXX ...
});
}
```
#### MongoDB Options
NAME | DESCRIPTION | TYPE | DEFAULT
:---|:---|---|:---
DatabaseName | Database name | string | cap
DatabaseConnection | Database connection string | string | mongodb://localhost:27017
ReceivedCollection | Database received message collection name | string | cap.received
PublishedCollection | Database published message collection name | string | cap.published
## Publish with transaction
The following example shows how to integrate CAP with MongoDB for local transactions:
```csharp
// NOTE: Before testing, you need to create the database and collection first.
// MongoDB cannot automatically create databases and collections within transactions,
// so you must create them separately. For example, insert a record to auto-create the collection.
// var mycollection = _client.GetDatabase("test")
// .GetCollection
================================================
FILE: docs/content/user-guide/zh/samples/castle.dynamicproxy.md
================================================
# 和 Castle DynamicProxy 集成
Castle DynamicProxy 是一个用于在运行时动态生成轻量级.NET代理的库。代理对象允许在不修改类代码的情况下截取对对象成员的调用。可以代理类和接口，但是只能拦截虚拟成员。
Castle.DynamicProxy 可以帮助你方便的创建代理对象，代理对象可以帮助构建灵活的应用程序体系结构，因为它允许将功能透明地添加到代码中，而无需对其进行修改。例如，可以代理一个类来添加日志记录或安全检查，而无需使代码知道已添加此功能。
下面可以看到如何在 CAP 中集成使用 Castle.DynamicProxy。
## 1、安装 NuGet 包
在 集成了 CAP 的项目中安装包，有关如何集成 CAP 的文档请看[这里](https://cap.dotnetcore.xyz/)。
注意，`Castle.DynamicProxy` 这个包已经被废弃，请使用最新的 `Castle.Core` 包。
```xml
Default credentials: bob/bob
/// services.AddCap(options =>
/// {
/// options.UseRabbitMQ(r => r.HostName = "localhost");
/// options.UseSqlServer("connection_string");
/// })
/// .AddSubscribeFilter<LoggingFilter>()
/// .AddSubscribeFilter<ExceptionHandlingFilter>();
///
///
/// var capAssembly = typeof(MyCapHandlers).Assembly;
/// services.AddCap(options => { })
/// .AddSubscriberAssembly(capAssembly);
///
///
/// // Assuming MyCapHandlers is a class in the assembly containing subscriber implementations
/// services.AddCap(options => { })
/// .AddSubscriberAssembly(typeof(MyCapHandlers));
///
///
/// services.AddCap(options =>
/// {
/// // Configure options
/// options.SucceedMessageExpiredAfter = 24 * 3600;
/// options.FailedRetryCount = 50;
///
/// // Register storage backend
/// options.UseSqlServer("your_connection_string");
///
/// // Register message transport
/// options.UseRabbitMQ(rabbitMqOptions =>
/// {
/// rabbitMqOptions.HostName = "localhost";
/// rabbitMqOptions.Port = 5672;
/// });
/// })
/// .AddSubscribeFilter<LoggingFilter>()
/// .AddSubscriberAssembly(typeof(MyCapHandlers));
///
///
/// public void AddServices(IServiceCollection services)
/// {
/// services.TryAddSingleton<IDataStorage, SqlServerDataStorage>();
/// services.TryAddSingleton<ITransport, RabbitMQTransport>();
/// }
///
///
/// public class OrderSubscriber : ICapSubscribe
/// {
/// [CapSubscribe("order.created")]
/// public async Task OnOrderCreated(OrderCreatedMessage message)
/// {
/// // Handle the message
/// await ProcessOrder(message);
/// }
/// }
///
///