Sprint.Shared.Notification 1.1.3

🚀 Shared.Notification (Microsoft Teams)

High-performance Microsoft Teams notification library designed for the Sprint ecosystem. This library delivers rapid, resilient, and non-blocking notifications, ensuring that critical alerts do not interfere with your application's core business logic performance.

🏗️ Key Features

• ⚡ Non-blocking Architecture: Leverages System.Threading.Channels (Producer-Consumer) to move message delivery to background threads 100% asynchronously.
• 🛡️ Multi-Framework Support: Full compatibility with .NET 6.0, 8.0 (LTS), and 10.0.
• 🔒 RAM Protection (Bounded Channels): Memory-safe design with a capacity of 1,000 notifications. Implements DropWrite mode when the queue is full to prevent memory leaks and protect application uptime.
• 🔄 Smart Retry & Reliability: Built-in Exponential Backoff for handling Rate Limits (HTTP 429) and Service Unavailable (HTTP 503) automatically.
• 📦 Automatic Content Truncation: Smartly adjusts Title and Message length if they exceed Teams' payload limits (prevents HTTP 400 Bad Request errors).
• 🎨 Adaptive Cards (v1.5): Modern, beautiful notification layout featuring a "View Full Stack Trace" toggle (via ShowCard) for error details.

⚙️ Installation & Setup

1. Register Services in Program.cs

Flexible registration options (Configuration-based, Action-based, or Options-based):

using Shared.Notification.Teams;

// Option 1: Automatic from Configuration (Section "Notifications:...")
builder.Services.AddTeamsNotification(builder.Configuration);

// Option 2: Manual Setup via Action
builder.Services.AddTeamsNotification(options => {
    options.TeamsWebhookUrl = "https://your-webhook-url...";
    options.ApplicationName = "Order-Core-API";
    options.EnableNotification = true;
});

// Option 3: Manual Setup via Options Object
var teamsOptions = new TeamsNotificationOptions {
    TeamsWebhookUrl = "https://your-webhook-url...",
    ApplicationName = "Order-Core-API"
};
builder.Services.AddTeamsNotification(teamsOptions);

2. Global Exception Monitoring (Middleware)

To automatically catch and send all unhandled exceptions from your API to MS Teams, add the middleware in Program.cs (after app.Run() or after your routing configuration):

var app = builder.Build();

// ... other middlewares ...

// 🚨 Enable Global Teams Alert Middleware
app.UseTeamsAlert();

app.Run();

3. Configuration Template (appsettings.json)

{
  "Notifications": {
    "TeamsWebhookUrl": "https://m365.webhook...",
    "ApplicationName": "Sprint-OMS-Order-API",
    "EnableNotification": true
  }
}

💡 Usage Examples

1. Sending Regular Messages (SendMessageAsync)

Important: Execution returns immediately (non-blocking). The main thread continues while the message is sent in the background.

public class OrderEndpoint : Endpoint<OrderRequest>
{
    private readonly INotificationService _notificationService;

    public OrderEndpoint(INotificationService notificationService)
    {
        _notificationService = notificationService;
    }

    public override async Task HandleAsync(OrderRequest req, CancellationToken ct)
    {
        // ... Business Logic ...

        // Send notification (Fire-and-forget to background queue)
        await _notificationService.SendMessageAsync(
            title: "📦 New Order Received", 
            message: $"Order ID: {req.OrderId} processed successfully."
        );
        
        // Main thread continues immediately!
        await SendOkAsync(ct);
    }
}

2. Creative Custom Message Formatting

Unlock the full power of notifications by customizing the message body. You can inject HTTP context details, environment information, or even data from other services:

builder.Services.AddTeamsNotification(options => {
    options.ApplicationName = "Sprint";
    
    // 🎨 Powerful Custom Formatter
    options.CustomMessageFormatter = (httpContext, exception) => {
        var request = httpContext?.Request;
        return $"🌐 Request: {request?.Method} {request?.Path}\n" +
               $"❌ Error: {exception?.Message}";
    };
});

🛡️ Resilience & Reliability Design

This library is engineered for mission-critical stability:

1. Bounded Channel Queue: Limits memory usage to 1,000 pending notifications. If the system is overwhelmed, new notifications are safely dropped to ensure application stability.
2. Retry Mechanism: Implements 3 retry cycles for HTTP 429/503 errors, with increasing delays (2s, 4s, 6s).
3. Payload Safety: If the first attempt fails due to size limits (HTTP 400), the library automatically truncates the content (Title < 500 characters, Message < 15,000 characters) and retries once more.

© 2026 Sprint-OMS Development Team