\n
\n Log In
\n\n \n
\n \n \n
\n \n \n
\n \n \n
\n Default credentials: bob/bob
\n\n \n
\n ![\"CAP](\"https://raw.githubusercontent.com/dotnetcore/CAP/master/docs/content/img/logo.svg\"){kind=logo}
\n\n \n
\n \n
![](\"img/logo.svg\"){kind=logo}
\n[](https://github.com/dotnetcore/CAP/actions/workflows/deploy-docs-and-dashboard.yml)\n[](https://ci.appveyor.com/project/yuleyule66/cap/branch/master)\n[](https://www.nuget.org/packages/DotNetCore.CAP/)\n[](https://www.nuget.org/packages/DotNetCore.CAP/)\n[](https://raw.githubusercontent.com/dotnetcore/CAP/master/LICENSE.txt)\n[](https://github.com/dotnetcore)\n\nCAP 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.\n\n## Introduction\n\nIn 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.\n\nYou 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.\n\n!!! 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)\"\n ![](\"img/architecture-eshop.png\")
\n\n > Atomicity when publishing events to the event bus with a worker microservice\n\n\nFor detailed instructions see the [Getting Started Guide][1].\n\n [1]: user-guide/en/getting-started/quick-start.md\n\n## Contributing\n\nOne 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.\n\nIf you have any question or problems, please report them on the CAP repository:\n\n\n\n\n## License\n\nCAP is licensed under the [MIT license](about/license.md).\n"
},
{
"path": "docs/content/user-guide/en/cap/configuration.md",
"content": "# Configuration\n\nBy default, you specify configurations when registering CAP services in the DI container for an ASP.NET Core project.\n\n```c#\nservices.AddCap(config =>\n{\n // config.XXX\n});\n```\n\n`services` is an `IServiceCollection` interface, which can be found in the `Microsoft.Extensions.DependencyInjection` package.\n\n## Minimum Configuration Required\n\nYou must configure at least one transport and one storage. If you want to get started quickly, you can use the following configuration:\n\n```C#\nservices.AddCap(capOptions => \n{\n capOptions.UseInMemoryQueue(); // Requires the Savorboard.CAP.InMemoryMessageQueue NuGet package.\n capOptions.UseInMemoryStorage();\n});\n```\n\nFor transport and storage configuration options provided by specific components, see the [Transports](../transport/general.md) and [Storage](../storage/general.md) sections.\n\n## Configuration in Subscribers\n\nSubscribers use the `[CapSubscribe]` attribute to mark themselves as subscribers. They can be located in an ASP.NET Core Controller or Service.\n\nWhen you declare `[CapSubscribe]`, you can change the behavior of the subscriber by specifying the following parameters.\n\n### Name\n\n> string, required\n\nSubscribe to messages by specifying the `Name` parameter. This corresponds to the name specified when publishing the message through `_cap.Publish(\"Name\")`.\n\nThis name corresponds to different items in different message brokers:\n\n- In RabbitMQ, it corresponds to the Routing Key.\n- In Kafka, it corresponds to the Topic.\n- In Azure Service Bus, it corresponds to the Subject.\n- In NATS, it corresponds to the Subject.\n- In Redis Streams, it corresponds to the Stream.\n\n### Group\n\n> string, optional\n\nSpecify 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.\n\nSubscribers 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.\n\nIt 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.\n\nGroup corresponds to different items in different message brokers:\n\n- In RabbitMQ, it corresponds to Queue.\n- In Kafka, it corresponds to Consumer Group.\n- In Azure Service Bus, it corresponds to Subscription Name.\n- In NATS, it corresponds to Queue Group.\n- In Redis Streams, it corresponds to Consumer Group.\n\n### GroupConcurrent\n\n> byte, optional\n\nSet 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`.\n\n!!! Note\n 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. \n This setting applies only to new messages; retried messages are not subject to the concurrency limit.\n\n## Custom Configuration\n\nThe `CapOptions` class is used to store configuration information. By default, all options have default values. Sometimes you may need to customize them.\n\n#### DefaultGroupName\n\n> Default: cap.queue.{assembly name}\n\nThe 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.\n\n!!! info \"Mapping\"\n Maps to [Queue Names](https://www.rabbitmq.com/queues.html#names) in RabbitMQ. \n Maps to [Consumer Group Id](http://kafka.apache.org/documentation/#group.id) in Apache Kafka. \n Maps to Subscription Name in Azure Service Bus. \n Maps to [Queue Group Name](https://docs.nats.io/nats-concepts/queue) in NATS.\n Maps to [Consumer Group](https://redis.io/topics/streams-intro#creating-a-consumer-group) in Redis Streams.\n\n#### GroupNamePrefix\n\n> Default: Null\n\nAdd unified prefixes to consumer group names. https://github.com/dotnetcore/CAP/pull/780\n\n#### TopicNamePrefix\n\n> Default: Null\n\nAdd unified prefixes to topic/queue names. https://github.com/dotnetcore/CAP/pull/780\n\n#### Version\n\n> Default: v1\n\nUsed 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:\n\n!!! info \"Business Iteration and Backward Compatibility\"\n 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.\n\n!!! info \"Multiple Server Versions\"\n 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.\n\n!!! info \"Different Instances Using the Same Storage Table/Collection\"\n 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.\n\n> Check out the blog to learn more about the Version feature: https://www.cnblogs.com/savorboard/p/cap-2-4.html\n\n#### FailedRetryInterval\n\n> Default: 60 sec\n\nDuring the message sending process, if message transmission fails, CAP will retry sending. This configuration option specifies the interval between each retry attempt.\n\nDuring the message consumption process, if the consumer method fails, CAP will retry execution. This configuration option specifies the interval between each retry attempt.\n\n!!! WARNING \"Retry & Interval\"\n 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. \n 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.\n\n!!! WARNING \"Multi-instance Concurrent Retries\"\n 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.\n\n#### UseStorageLock\n\n> Default: false\n\nIf 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.\n\n#### CollectorCleaningInterval\n\n> Default: 300 sec\n\nThe interval at which the collector deletes expired messages.\n\n#### SchedulerBatchSize\n\n> Default: 1000\n\nMaximum number of delayed or queued messages fetched per scheduler cycle.\n\n#### ConsumerThreadCount\n\n> Default: 1\n\nNumber of consumer threads. When this value is greater than 1, the order of message execution cannot be guaranteed.\n\n#### FailedRetryCount\n\n> Default: 50\n\nMaximum number of retries. When this count is reached, retries will stop. You can modify this parameter to set the maximum retry attempts.\n\n#### FallbackWindowLookbackSeconds\n\n> Default: 240 sec\n\nConfigures the retry processor to pick up messages with `Scheduled` or `Failed` status within the lookback time window.\n\n#### FailedThresholdCallback\n\n> Default: NULL\n\nType: `Action![](\"/img/opentelemetry.png\")
\n\n### Context Propagation\n\nCAP 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.\n\nCAP 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:\n\n```C#\nOpenTelemetry.Sdk.SetDefaultTextMapPropagator(\n new TraceContextPropagator());\n```\n\nFor 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)."
},
{
"path": "docs/content/user-guide/en/samples/eshoponcontainers.md",
"content": "# eShopOnContainers\n\neShopOnContainers is a sample application written in C# running on .NET Core that uses a microservice architecture and Domain Driven Design.\n\n> A .NET Core reference application powered by Microsoft, based on a simplified microservices architecture with Docker containers.\n\n> 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.\n\n> 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.\n\n## eShopOnContainers with CAP\n\nYou can see how to use CAP in eShopOnContainers in the GitHub repository:\n\nhttps://github.com/yang-xiaodong/eShopOnContainers"
},
{
"path": "docs/content/user-guide/en/samples/faq.md",
"content": "# FAQ\n\n!!! faq \"Is there an IM group (e.g., Tencent QQ group) to learn and chat about CAP?\"\n\n 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.\n\n!!! faq \"Does each application need a separate database for producer and consumer in CAP?\"\n\n Not necessarily. A recommendation is to use a dedicated database for each application. However, see the Q&A below for alternatives.\n\n!!! faq \"How can I use the same database for different applications?\"\n \n Define a table prefix name in the `ConfigureServices` method.\n \n Code example:\n\n ```c#\n public void ConfigureServices(IServiceCollection services)\n {\n services.AddCap(x =>\n {\n x.UseKafka(\"\");\n x.UseMySql(opt =>\n {\n opt.ConnectionString = \"connection string\";\n opt.TableNamePrefix = \"appone\"; // Use different table name prefix here\n });\n });\n }\n ```\n\n!!! faq \"Can CAP avoid using the database for event storage? I just want to send messages.\"\n\n 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.\n\n!!! faq \"If the consumer fails, can I roll back the SQL executed by the producer?\"\n\n No, you cannot roll back. CAP provides eventual consistency, not immediate rollback.\n\n 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.\n"
},
{
"path": "docs/content/user-guide/en/samples/github.md",
"content": "# GitHub Samples\n\nYou can find sample code in the GitHub repository:\n\nhttps://github.com/dotnetcore/CAP/tree/master/samples\n\nCAP + Aspire + Azure Service Bus + Azure SQL:\n\nhttps://github.com/NikiforovAll/cap-aspire"
},
{
"path": "docs/content/user-guide/en/storage/general.md",
"content": "# General\n\nCAP 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.\n\n## Persistence\n\n### Before Sent\n\nBefore 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.\n\nTo 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.\n\n### After Sent\n\nAfter 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.\n\nFor message persistence in RabbitMQ, CAP uses a consumer queue with message persistence, though exceptions may occur.\n\n!!! info \"Ready for Production?\"\n 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.\n\nSince Kafka has built-in message persistence using files, it automatically ensures that messages are properly persisted without loss once they enter Kafka.\n\n## Storage\n\n### Supported storages\n\nCAP supports the following types of transaction-enabled databases for storage:\n\n* [SQL Server](sqlserver.md)\n* [MySQL](mysql.md)\n* [PostgreSql](postgresql.md)\n* [MongoDB](mongodb.md)\n* [In-Memory Storage](in-memory-storage.md)\n\nAfter CAP is started, two tables are generated in used storage, by default the name is `Cap.Published` and `Cap.Received`.\n\n### Storage Data Structure\n\nTable structure of **Published** :\n\nNAME | DESCRIPTION | TYPE\n:---|:---|:---\nId | Message Id | int\nVersion | Message Version | string\nName | Topic Name | string\nContent | Json Content | string\nAdded | Added Time | DateTime\nExpiresAt | Expire time | DateTime\nRetries | Retry times | int\nStatusName | Status Name | string\n \nTable structure of **Received** :\n\nNAME | DESCRIPTION | TYPE\n:---|:---|:---\nId | Message Id | int\nVersion | Message Version | string\nName | Topic Name | string\nGroup | Group Name | string\nContent | Json Content | string\nAdded | Added Time | DateTime\nExpiresAt | Expire time | DateTime\nRetries | Retry times | int\nStatusName | Status Name | string\n\nTable structure of **Lock** (Optional):\n\nNAME | DESCRIPTION | TYPE\n:---|:---|:---\nKey | Lock Id | string\nInstance | Acquired instance of lock | string\nLastLockTime | Last acquired lock time | DateTime\n\n### Wapper Object\n\nWhen CAP sends a message, it will store original message object in a second package in the `Content` field. \n\nThe following is the **Wapper Object** data structure of Content field.\n\nNAME | DESCRIPTION | TYPE\n:---|:---|:---\nId\t| Message Id\t| string\nTimestamp |\tMessage created time |\tstring\nContent |\tMessage content |\tstring\nCallbackName |\tConsumer callback topic name | string\n\nThe `Id` field is generate using the mongo [objectid algorithm](https://www.mongodb.com/blog/post/generating-globally-unique-identifiers-for-use-with-mongodb).\n\n\n## Community-supported extensions\n\nThanks to the community for supporting CAP, the following is the implementation of community-supported storage\n\n* SQLite ([@colinin](https://github.com/colinin)) ：https://github.com/colinin/DotNetCore.CAP.Sqlite \n\n* LiteDB ([@maikebing](https://github.com/maikebing)) ：https://github.com/maikebing/CAP.Extensions\n\n* SQLite & Oracle ([@cocosip](https://github.com/cocosip)) ：https://github.com/cocosip/CAP-Extensions \n"
},
{
"path": "docs/content/user-guide/en/storage/in-memory-storage.md",
"content": "# In-Memory Storage\n\nIn-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.\n\n## Configuration\n\nTo use in-memory storage, you need to install the following package from NuGet:\n\n```powershell\nPM> Install-Package DotNetCore.CAP.InMemoryStorage\n```\n\nNext, add configuration items to the `ConfigureServices` method of `Startup.cs`.\n\n```csharp\n\npublic void ConfigureServices(IServiceCollection services)\n{\n // ...\n\n services.AddCap(x =>\n {\n x.UseInMemoryStorage();\n // x.UseXXX ...\n });\n}\n\n```\n\nCAP will clean successful messages from memory every 5 minutes.\n\n## Publish with transaction\n\nIn-memory storage does **not support** transactional message publishing.\n"
},
{
"path": "docs/content/user-guide/en/storage/mongodb.md",
"content": "# MongoDB\n\nMongoDB is a cross-platform, document-oriented database program. Classified as a NoSQL database, MongoDB uses JSON-like documents with dynamic schema.\n\nCAP 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.\n\nFor 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).\n\n## Configuration\n\nTo use MongoDB storage, you need to install the following package from NuGet:\n\n```powershell\nPM> Install-Package DotNetCore.CAP.MongoDB\n\n```\n\nNext, add configuration items to the `ConfigureServices` method of `Startup.cs`.\n\n```csharp\n\npublic void ConfigureServices(IServiceCollection services)\n{\n // ...\n\n services.AddCap(x =>\n {\n x.UseMongoDB(opt=>{\n //MongoDBOptions\n });\n // x.UseXXX ...\n });\n}\n\n```\n\n#### MongoDB Options\n\nNAME | DESCRIPTION | TYPE | DEFAULT\n:---|:---|---|:---\nDatabaseName | Database name | string | cap \nDatabaseConnection | Database connection string | string | mongodb://localhost:27017\nReceivedCollection | Database received message collection name | string | cap.received\nPublishedCollection | Database published message collection name | string | cap.published\n\n## Publish with transaction\n\nThe following example shows how to integrate CAP with MongoDB for local transactions:\n\n```csharp\n// NOTE: Before testing, you need to create the database and collection first.\n// MongoDB cannot automatically create databases and collections within transactions,\n// so you must create them separately. For example, insert a record to auto-create the collection.\n\n// var mycollection = _client.GetDatabase(\"test\")\n// .GetCollection"
},
{
"path": "docs/content/user-guide/zh/samples/castle.dynamicproxy.md",
"content": "# 和 Castle DynamicProxy 集成\n\nCastle DynamicProxy 是一个用于在运行时动态生成轻量级.NET代理的库。代理对象允许在不修改类代码的情况下截取对对象成员的调用。可以代理类和接口，但是只能拦截虚拟成员。\n\nCastle.DynamicProxy 可以帮助你方便的创建代理对象，代理对象可以帮助构建灵活的应用程序体系结构，因为它允许将功能透明地添加到代码中，而无需对其进行修改。例如，可以代理一个类来添加日志记录或安全检查，而无需使代码知道已添加此功能。\n\n下面可以看到如何在 CAP 中集成使用 Castle.DynamicProxy。\n\n\n## 1、安装 NuGet 包\n\n在 集成了 CAP 的项目中安装包，有关如何集成 CAP 的文档请看[这里](https://cap.dotnetcore.xyz/)。\n\n注意，`Castle.DynamicProxy` 这个包已经被废弃，请使用最新的 `Castle.Core` 包。\n\n```xml\nDefault credentials: bob/bob
\n\n /// services.AddCap(options =>\n /// {\n /// options.UseRabbitMQ(r => r.HostName = \"localhost\");\n /// options.UseSqlServer(\"connection_string\");\n /// })\n /// .AddSubscribeFilter<LoggingFilter>()\n /// .AddSubscribeFilter<ExceptionHandlingFilter>();\n /// \n /// \n /// var capAssembly = typeof(MyCapHandlers).Assembly;\n /// services.AddCap(options => { })\n /// .AddSubscriberAssembly(capAssembly);\n /// \n /// \n /// // Assuming MyCapHandlers is a class in the assembly containing subscriber implementations\n /// services.AddCap(options => { })\n /// .AddSubscriberAssembly(typeof(MyCapHandlers));\n /// \n /// \n /// services.AddCap(options =>\n /// {\n /// // Configure options\n /// options.SucceedMessageExpiredAfter = 24 * 3600;\n /// options.FailedRetryCount = 50;\n /// \n /// // Register storage backend\n /// options.UseSqlServer(\"your_connection_string\");\n /// \n /// // Register message transport\n /// options.UseRabbitMQ(rabbitMqOptions =>\n /// {\n /// rabbitMqOptions.HostName = \"localhost\";\n /// rabbitMqOptions.Port = 5672;\n /// });\n /// })\n /// .AddSubscribeFilter<LoggingFilter>()\n /// .AddSubscriberAssembly(typeof(MyCapHandlers));\n /// \n /// \n /// public void AddServices(IServiceCollection services)\n /// {\n /// services.TryAddSingleton<IDataStorage, SqlServerDataStorage>();\n /// services.TryAddSingleton<ITransport, RabbitMQTransport>();\n /// }\n /// \n /// \n/// public class OrderSubscriber : ICapSubscribe\n/// {\n/// [CapSubscribe(\"order.created\")]\n/// public async Task OnOrderCreated(OrderCreatedMessage message)\n/// {\n/// // Handle the message\n/// await ProcessOrder(message);\n/// }\n/// }\n/// \n///