arisng/cap

CAP (DotNetCore.CAP) Skill

This skill provides comprehensive guidance for using the DotNetCore.CAP library to implement distributed transactions and event bus patterns in .NET microservices. Home page: https://cap.dotnetcore.xyz/

Overview

CAP is a .NET library that provides a lightweight solution for distributed transactions and event bus integration in microservices. It uses the Outbox Pattern to ensure message reliability and consistency.

What is EventBus?

An EventBus is a mechanism that allows different components to communicate with each other without knowing each other. A component can send an Event to the EventBus without knowing who will pick it up or how many others will. Components can also listen to Events on an EventBus without knowing who sent them. This way, components can communicate without depending on each other. Also, it's very easy to substitute a component – as long as the new component understands the events being sent and received, other components will never know about the substitution.

Key Capabilities

Setup and Configuration

• Installing CAP packages for different transports and storage providers
• Configuring CAP in ASP.NET Core applications
• Setting up message queues (RabbitMQ, Kafka, Azure Service Bus, etc.)
• Configuring databases (SQL Server, PostgreSQL, MySQL, MongoDB)

Publishing Messages

• Publishing events within transactions
• Delayed message publishing
• Message headers and metadata

Subscribing to Messages

• Controller-based subscriptions
• Service-based subscriptions with ICapSubscribe
• Consumer groups and load balancing
• Asynchronous message processing

Advanced Features

• Partial topic subscriptions
• Custom serialization
• Monitoring with dashboard
• Service discovery integration

Quick Start

1. Installation

Install the main CAP package:

dotnet add package DotNetCore.CAP

Choose your transport (message queue):

# RabbitMQ
dotnet add package DotNetCore.CAP.RabbitMQ

# Kafka
dotnet add package DotNetCore.CAP.Kafka

# Azure Service Bus
dotnet add package DotNetCore.CAP.AzureServiceBus

Choose your storage provider:

# SQL Server
dotnet add package DotNetCore.CAP.SqlServer

# PostgreSQL
dotnet add package DotNetCore.CAP.PostgreSql

# MongoDB
dotnet add package DotNetCore.CAP.MongoDB

2. Basic Configuration

In Program.cs:

builder.Services.AddCap(x =>
{
    // Configure storage
    x.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"));
    
    // Configure transport
    x.UseRabbitMQ("localhost");
    
    // Optional: Configure dashboard
    x.UseDashboard();
});

3. Publishing Messages

public class OrderService
{
    private readonly ICapPublisher _capPublisher;

    public OrderService(ICapPublisher capPublisher)
    {
        _capPublisher = capPublisher;
    }

    public async Task CreateOrder(Order order)
    {
        // Publish event
        await _capPublisher.PublishAsync("order.created", order);
    }
}

4. Subscribing to Messages

public class OrderEventHandler : ICapSubscribe
{
    [CapSubscribe("order.created")]
    public async Task HandleOrderCreated(Order order)
    {
        // Process the order created event
        await ProcessOrderAsync(order);
    }
}

Common Patterns

Transactional Publishing

using (var transaction = dbContext.Database.BeginTransaction(_capPublisher, autoCommit: true))
{
    // Business logic
    await dbContext.Orders.AddAsync(order);
    await dbContext.SaveChangesAsync();
    
    // Publish event within transaction
    await _capPublisher.PublishAsync("order.created", order);
}

Consumer Groups

[CapSubscribe("order.created", Group = "order-processing-group")]
public async Task ProcessOrder(Order order)
{
    // Only one instance in the group will process this message
}

Delayed Messages

await _capPublisher.PublishDelayAsync(
    TimeSpan.FromMinutes(5), 
    "order.reminder", 
    orderId
);

Troubleshooting

Common Issues

1. Messages not being processed: Check consumer group configuration and ensure subscribers are registered
2. Duplicate messages: Verify idempotency handling in subscribers
3. Connection issues: Validate message queue and database connection strings
4. Performance problems: Consider consumer group sizing and parallel processing settings

Monitoring

Use the CAP dashboard to monitor message status:

• Access at /cap by default
• View published and received messages
• Manually retry failed messages
• Monitor system health

References

See references/ for detailed documentation on:

• Configuration options
• Message patterns
• Troubleshooting guide
• API reference