Dhanman.Shared.Contracts 2.3.3

Dhanman.Shared.Contracts

This project contains shared data transfer objects (DTOs), events, and message contracts used across multiple Dhanman microservices.

Purpose

• Define common event and command contracts for inter-service communication.
• Keep shared message schemas consistent and centralized.
• Avoid tight coupling by sharing only contract definitions, not implementations.

Usage

1. Reference this package from any microservice that needs to publish or consume these contracts.

2. Use the DTOs, event classes, and commands here for MassTransit message serialization and deserialization.

3. Keep contracts immutable and versioned carefully to maintain backward compatibility.

Example Contract

public class UserCreatedEvent : IEvent
{
    public Guid UserId { get; set; }
    public Guid CompanyId { get; set; }
    public string FirstName { get; set; } = string.Empty;
    public string LastName { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public string PhoneNumber { get; set; } = string.Empty;
}

MassTransit Integration

This library is designed to work seamlessly with MassTransit. Events defined here can be published and consumed using MassTransit's type-based routing.

Publishing Events with MassTransit

public class MyService
{
    private readonly IPublishEndpoint _publishEndpoint;
    
    public MyService(IPublishEndpoint publishEndpoint)
    {
        _publishEndpoint = publishEndpoint;
    }
    
    public async Task CreateUser(...)
    {
        // Business logic...
        
        await _publishEndpoint.Publish(new UserCreatedEvent
        {
            UserId = user.Id,
            CompanyId = user.CompanyId,
            // ... other properties
        });
    }
}

Consuming Events with MassTransit

public class UserCreatedEventConsumer : IConsumer<UserCreatedEvent>
{
    private readonly ILogger<UserCreatedEventConsumer> _logger;
    
    public UserCreatedEventConsumer(ILogger<UserCreatedEventConsumer> logger)
    {
        _logger = logger;
    }
    
    public async Task Consume(ConsumeContext<UserCreatedEvent> context)
    {
        var message = context.Message;
        
        // Use structured logging (not string interpolation)
        _logger.LogInformation(
            "[MESSAGE] Consuming UserCreatedEvent for UserId {UserId}",
            message.UserId);
        
        // Handle the event...
    }
}

Logging Best Practices

When implementing message handlers:

• Use structured logging with placeholders like {PropertyName}, not string interpolation $"{value}"
• Tag message logs with [MESSAGE] prefix to distinguish from general application logs
• Include key identifiers: UserId, CompanyId, MessageId, CorrelationId
• Use appropriate log levels: Information for normal flow, Warning for retries, Error for failures

See MIGRATION_GUIDE.md for comprehensive logging guidelines.

Caching (Dhanman.Shared.Contracts.Caching)

Extracted from the Purchase service's proven hybrid L1 (memory) + L2 (Redis) cache — see dhanman-purchase's Cache-Review-Report.md / CACHE-~2.MD for the full design rationale.

Adopt it with one call in Program.cs:

builder.Services.AddAppCaching("yourservice", builder.Configuration);

This registers IAppCache, ICacheAdminService, and ICacheDiagnosticsService, backed by Redis if AppCache:UseRedis=true and ConnectionStrings:Redis is set (falls back to an in-process DistributedMemoryCache otherwise — safe for local dev). Register a real ICacheMetrics implementation (e.g. Prometheus-backed) after AddAppCaching to override the no-op default.

Key points:

• Policies are configured by dictionary, not a hardcoded switch — set AppCache:Policies:{PolicyName}:{Local,Distributed}ExpirationMinutes per cached query shape. An unconfigured policy name falls back to a 5m/10m default and logs a warning instead of throwing at request time (this is the structural fix for the class of bug where a declared policy was missing from a switch statement and 500'd in production despite 100% mocked test coverage).
• Every cached read must go through IAppCache.GetOrCreateAsync — never call IDistributedCache/IDatabase directly from a handler.
• CacheDiagnosticsHeadersMiddleware / CacheModeMiddleware (in Caching.AspNetCore) add X-Cache* response headers and X-Cache-Mode override support — register both for Development/QA only; there's no permission check in the middleware to gate X-Cache-Mode for Production, so don't register it there until a service wires one up.
• See dhanman-purchase/docs/caching-standards.md for the full rule set and PR checklist.

Legacy Routing Keys

The RoutingKeys class is marked as obsolete. MassTransit uses type-based routing automatically, so explicit routing keys are no longer needed. The class is kept for backward compatibility during the migration period.