Davasorus.Utility.DotNet.SQS 2026.2.1.2

Davasorus.Utility.DotNet.SQS

Overview

Davasorus.Utility.DotNet.SQS provides utilities for publishing messages to Amazon Simple Queue Service (SQS) from .NET applications. It handles message serialization, error deduplication, anonymization, location enrichment, and OpenTelemetry tracing out of the box.

Features

• Publish messages to AWS SQS FIFO and standard queues
• Built-in error deduplication and anonymous error reporting
• Location enrichment (city, region) via IP geolocation with configurable caching
• OpenTelemetry distributed tracing on all operations
• Secure credential management (decrypts AWS secrets at runtime)
• Fluent configuration with SqsOptionsBuilder or appsettings.json binding
• Designed for dependency injection with a single AddSqsLogging() call
• Service-oriented usage: always interact with ISqsService, not the client directly

Getting Started

1. Reference the library in your .NET 8 project.
2. Register services using the AddSqsLogging() extension method.
3. Use ISqsService in your application code to publish messages.

Dependency Injection

Register all SQS and location services with a single call:

// Default configuration (caching enabled, 1 hour location cache, 4 hour IP cache)
services.AddSqsLogging();

// Fluent configuration
services.AddSqsLogging(sqs => sqs
    .WithLocationCache(TimeSpan.FromHours(1))
    .WithIpCache(TimeSpan.FromHours(4)));

// Bind from appsettings.json
services.AddSqsLogging(configuration.GetSection("SqsOptions"));

// Hybrid: appsettings with fluent overrides
services.AddSqsLogging(
    configuration.GetSection("SqsOptions"),
    sqs => sqs.WithLocationCache(TimeSpan.FromMinutes(90)));

AddSqsLogging() registers the following services:

Only inject and use ISqsService in your application code.

Usage Example

public class MyService
{
    private readonly ISqsService _sqsService;
    public MyService(ISqsService sqsService) => _sqsService = sqsService;

    public async Task LogErrorAsync(string message)
    {
        var model = new TrelloMessageQueueModel { Message = message /*, ... */ };
        await _sqsService.SendLoggingMessage(model);
    }
}

Configuration

SqsOptions

Configure caching and error collection behavior via SqsOptions:

AWS Credentials

Access Key and Secret Key are stored securely and decrypted at runtime via the IDecrypt service from Davasorus.Utility.DotNet.Encryption.

Queue Names

Queue names are managed internally by the service:

• messageQueue.fifo -- general and logging messages
• responseQueue.fifo -- response messages
• systemMaint.fifo -- maintenance messages
• taskQueue-{hostId}.fifo -- per-host task messages
• taskQueue.fifo -- task response messages

Location Service

The package includes a location subsystem for enriching error reports with geographic data.

• LocationCache -- Singleton cache backed by IMemoryCache. Caches IP addresses and location data with configurable TTLs.
• LocationClient -- Fetches the machine's public IP via api.ipify.org and resolves location via ipinfo.io. Supports cached and uncached modes.
• LocationService -- Scoped interface for application code to request location fields.

Supported location fields: "ip", "city", "region", "loc".

var city = await locationService.GetLocationInformation("city");
var region = await locationService.GetLocationInformation("region");

Telemetry

All operations emit OpenTelemetry traces via System.Diagnostics.ActivitySource. Activity sources are created for:

• SQS.Service -- high-level publish operations
• SQS.Client -- low-level SQS API calls
• Location.Service -- location lookups
• Location.Client -- IP and geolocation fetches
• Location.Cache -- cache hits and misses

Traces include semantic messaging conventions (messaging.system, messaging.destination, messaging.message_id) for integration with observability platforms.

Error Handling

• All SQS publish operations catch exceptions internally and return "error" on failure.
• Errors are logged via ILogger.
• SendLoggingMessage performs deduplication: repeated identical errors are not re-published.
• When anonymous error reporting is enabled, usernames are stripped from messages and metadata.

API Overview

The ISqsService interface provides the following methods:

• Task<string> SendLoggingMessage(TrelloMessageQueueModel message) -- Sends a logging message with deduplication, anonymization, and location enrichment. Returns the message ID on success.

• Task<string> PublishMessage(TrelloMessageQueueModel message, string messageGroupID = null) -- Publishes a general message. Supports FIFO queue grouping via messageGroupID.

• Task<string> PublishResponseMessage(TrelloMessageQueueResponseModel message, string messageGroupID = null) -- Publishes a response message for request/response patterns. Supports FIFO grouping.

• Task<string> PublishMaintenanceMessage(TrelloMessageQueueModel message, string messageGroupID = null) -- Sends a maintenance message with optional FIFO grouping.

• Task<string> PublishTaskMessageToClient(RemoteHostTaskQueueModel message, string messageGroupID = null) -- Publishes a task message to a specific remote host's queue.

• Task<string> PublishTaskMessageResponse(RemoteHostTaskQueueModel message, string messageGroupID = null) -- Publishes a response to a previously sent task message.

• string GetUserName() -- Returns the current username, or "Anonymous" when anonymous reporting is enabled.

• string GetMachineName() -- Returns the machine name, or "Anonymous" when anonymous reporting is enabled.

• string ParseDescription(string text) -- Strips the current username from the provided text for anonymization.

Dependencies

• AWSSDK.SQS
• Davasorus.Utility.DotNet.Contracts.Types
• Davasorus.Utility.DotNet.Contracts.Collections
• Davasorus.Utility.DotNet.Encryption
• Davasorus.Utility.DotNet.Telemetry
• Microsoft.Extensions.Caching.Memory
• Microsoft.Extensions.Http
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options

License

MIT License

Contributing

Contributions are welcome! Please submit issues or pull requests for improvements.