CAP Documentation

CAP is an EventBus and a distributed transaction solution designed for microservices and SOA (Service-Oriented Architecture) systems. It enables scalable, reliable, and easily modifiable microservices by providing a mechanism for components to communicate via events without direct dependencies.

Key characteristics include:

• High Flexibility: Unlike many service buses, CAP does not require users to implement or inherit specific interfaces for sending or processing messages.
• Modular Design: It is highly scalable and allows for custom implementations of message queues, storage, and serialization.
• Lightweight: Follows a 'convention over configuration' philosophy, making it beginner-friendly.

CAP is a .NET Standard library designed to solve distributed transaction problems in SOA or Microservice architectures. It functions as both a distributed transaction solution and an EventBus.

Key capabilities include:

• Reliable Messaging: Uses the Outbox Pattern by integrating a local message table with your current database. This ensures that event messages are not lost during service-to-service communication, even if exceptions occur.
• Simplified EventBus: Provides a lightweight way to implement event publishing and subscriptions without requiring you to inherit or implement specific interfaces.
• Eventual Consistency: Manages distributed transactions through an eventually consistent model.

CAP provides an At Least Once delivery guarantee. Because CAP does not use distributed transactions (like MS DTC or 2PC) to coordinate between the message broker and your database, it is impossible to guarantee 'Exactly Once' delivery.

In an At Least Once model, a message is only removed from the queue after your 'work transaction' (e.g., a database commit) has successfully completed. If the consumer fails or the system crashes before the message is deleted from the queue, the message will be redelivered. Therefore, your message handlers must be designed to handle the same message multiple times without causing unintended side effects.

CAP uses Transports to move data between message producers and brokers, brokers and the entity database, and brokers and external systems.

Official supported transports include:

• RabbitMQ
• Kafka
• Azure Service Bus
• Amazon SQS
• NATS
• In-Memory Queue
• Redis Streams
• Apache Pulsar

Community-supported extensions include:

• ActiveMQ
• RedisMQ
• ZeroMQ
• MQTT

CAP ensures message reliability by using a local storage medium (database or NoSQL) to protect against message loss during network issues or message queue unavailability.

Persistence Workflow

1. Before Sent: Before a message reaches the message queue, CAP persists it in a local database table. CAP uses the same database transactions as your business code to ensure atomicity. If message persistence fails, the business transaction rolls back.
2. After Sent: Once the message enters the queue, CAP relies on the queue's persistence capabilities:
   • RabbitMQ: CAP uses consumer queues with message persistence. Production Tip: For RabbitMQ, it is recommended to start all consumers at least once before sending messages to ensure all persistent queues are created.
   • Kafka: Uses built-in file-based persistence to ensure messages are not lost once they enter Kafka.

Since version 5.2+, CAP features are implemented based on NATS JetStream. You must explicitly enable JetStream on your NATS server to use CAP properly.

When starting the NATS server, you must specify the --jetstream parameter.

To use CAP in your project, install the core package via NuGet Package Manager.

PM> Install-Package DotNetCore.CAP

CAP 7.0+ supports EventSource for reporting metrics. You can monitor these metrics in real-time using the dotnet-counters tool. The counter name is DotNetCore.CAP.EventCounter.

Metrics provided:

• Publish rate per second
• Consume rate per second
• Invoke Subscriber rate per second
• Subscriber elapsed time mean per second

To use SQL Server as the storage backend for CAP, install the DotNetCore.CAP.SqlServer NuGet package.

Note: CAP uses Microsoft.Data.SqlClient as the database driver. The use of System.Data.SqlClient is deprecated.

Register the storage in your Startup.cs within the ConfigureServices method using x.UseSqlServer().

PM> Install-Package DotNetCore.CAP.SqlServer

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

    services.AddCap(x =>
    {
        x.UseSqlServer(opt => {
            // SqlServerOptions configuration
        }); 
        // x.UseXXX ...
    });
}

Configure CAP in your Startup.cs or Program.cs using services.AddCap. You must specify both a storage provider (to implement the Outbox pattern) and a message transport.

Supported storage methods include UseEntityFramework, UseSqlServer, UseMySql, UsePostgreSql, and UseMongoDB.

Supported transport methods include UseRabbitMQ, UseKafka, UseAzureServiceBus, UseAmazonSQS, UseNATS, UsePulsar, and UseRedisStreams.

services.AddCap(x =>
{
    // Storage configuration
    x.UseEntityFramework<AppDbContext>();
    // OR
    x.UseSqlServer("Your ConnectionString");

    // Transport configuration
    x.UseRabbitMQ("HostName");
    // OR
    x.UseKafka("ConnectionString");
});