What Are DSMs?

DSM (Dynamic Stability Modules) is a proprietary technology framework designed to enhance reliability and performance of enterprise systems. At its core, DSM provides a generic wrapper DSMEnvelope<T> around data and execution metadata that enables:

How DSM Envelopes Work

The DSM lifecycle follows a simple, consistent pattern:

1. Initialize

Create an envelope using InitWithCaller() (recommended for async) or Init(). The envelope captures caller information and starts timing immediately.

var envelope = DSMEnvelope<PersonDto>
    .InitWithCaller(nameof(PersonController))
    .CaptureAndSetHeaders(HttpContext);

2. Capture Headers

Automatically capture HTTP headers for distributed tracing:

• Api-Trace-Id: Tracks requests across services
• Idempotency-Key-Id: Ensures operation idempotency

3. Execute

Perform your business logic, then mark the operation as successful or capture exceptions:

// Success
envelope.Success(result);

// Error
catch (Exception ex) {
    envelope.CaptureException(ex);
}

4. Freeze (Optional)

Lock parent envelopes in a failure state when inner operations fail, preventing status changes and ensuring error propagation through the stack.

What Gets Captured

Each DSMEnvelope captures comprehensive metadata about the operation:

Error Handling & Validation

DSM includes a comprehensive error code system and structured validation handling:

Standardized Error Codes

DSMEnvelopeCodeEnum defines codes for different error categories:

• GEN_COMMON_00000: Success
• API_COMMON_010XX: Security errors
• API_APPVLD_020XX: Application validation errors (HTTP 400)
• API_DATABASE_030XX: Database errors

Validation Error Collection

The ValidationErrorCollector provides fluent API for collecting field-level errors:

var validator = new ValidationErrorCollector()
    .ValidateRequired(request.Email, "email")
    .ValidateEmail(request.Email, "email")
    .ValidateLength(request.Name, "name", 2, 100);

if (validator.HasErrors()) {
    return envelope.ValidationFailed(validator);
}

Validation errors are structured as a dictionary mapping field names to error message lists, perfect for API responses.

Distributed Tracing & Nested Operations

DSM provides powerful capabilities for tracking operations across service boundaries:

DSMEnvelopeManager

A singleton stack-based manager for handling nested envelopes with automatic parent-child relationships:

// Initialize and push onto stack
var envelope = DSMEnvelopeManager.Instance
    .InitEnvelopeWithCaller<PersonDto>(
        nameof(PersonController), 
        httpContext: HttpContext
    );

// Headers automatically propagate to child operations
var childResult = await _service.GetData();

// Pop when done
DSMEnvelopeManager.Instance.PopEnvelope();

Freeze Stack on Error

When an error occurs in a nested operation, freeze the entire stack to prevent inconsistent states:

catch (Exception ex) {
    envelope.CaptureException(ex);
    DSMEnvelopeManager.Instance.FreezeStackWith(envelope);
}

Use Cases

Quick Start Example

Here's a complete example of using DSM in an ASP.NET Core controller:

[HttpGet("{id}")]
public async Task<ActionResult<DSMEnvelope<PersonDto>>> GetPerson(int id)
{
    var envelope = DSMEnvelope<PersonDto>
        .InitWithCaller(nameof(PersonController))
        .CaptureAndSetHeaders(HttpContext);
    
    try
    {
        var person = await _service.GetByIdAsync(id);
        if (person == null)
        {
            envelope.SetState(
                DSMEnvelopeCodeManager.Manager
                    .Find(DSMEnvelopeCodeEnum.API_APPVLD_02001),
                $"Person {id} not found"
            );
            return NotFound(envelope);
        }
        
        envelope.Success(person);
        return Ok(envelope);
    }
    catch (Exception ex)
    {
        envelope.CaptureException(ex);
        return StatusCode(500, envelope);
    }
}

Integration Options

Output Formats

DSM provides multiple output formats for different use cases:

Console Output

Color-coded console output with comprehensive details for development and debugging. Yellow for initialized state, green for success, red for errors.

JSON Serialization

Call ToRawJson() to get JSON output perfect for logging pipelines, analytics systems, and AI/MCP integration.