CAP (DotNetCore.CAP) Skill Skill

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

Messages not being processed: Check consumer group configuration and ensure subscribers are registered
Duplicate messages: Verify idempotency handling in subscribers
Connection issues: Validate message queue and database connection strings
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:

Agent Skills: CAP (DotNetCore.CAP) Skill

Install this agent skill to your local

Skill Files