Foundatio

Foundatio provides pluggable infrastructure abstractions. Use context7 MCP for complete documentation.

Documentation: Use context7 to fetch current Foundatio API docs and examples.

Core Abstractions

Interface	Purpose	In-Memory	Production
ICacheClient	Distributed caching	InMemoryCacheClient	Redis
IQueue<T>	Message queuing	InMemoryQueue<T>	Redis/SQS
IMessageBus	Pub/sub messaging	InMemoryMessageBus	Redis
IFileStorage	File storage	InMemoryFileStorage	S3/Azure
ILockProvider	Distributed locking	InMemoryLockProvider	Redis
IResiliencePolicyProvider	Retry/circuit breaker	N/A	Polly-based

ICacheClient

// From src/Exceptionless.Core/Services/UsageService.cs
public class UsageService
{
    private readonly ICacheClient _cache;

    public async Task<int> GetUsageAsync(string organizationId, DateTime bucketUtc)
    {
        var key = GetBucketTotalCacheKey(bucketUtc, organizationId);
        var result = await _cache.GetAsync<int>(key);
        return result.HasValue ? result.Value : 0;
    }

    public async Task IncrementUsageAsync(string organizationId, DateTime bucketUtc, int count)
    {
        var key = GetBucketTotalCacheKey(bucketUtc, organizationId);
        await _cache.IncrementAsync(key, count);

        // Track org in set for later processing
        await _cache.ListAddAsync(GetOrganizationSetKey(bucketUtc), organizationId);
    }
}

IQueue

Queue items for background processing:

// Enqueue
await _queue.EnqueueAsync(new EventPost
{
    OrganizationId = orgId,
    ProjectId = projectId,
    FilePath = path
});

IMessageBus

Pub/sub for real-time notifications:

// From src/Exceptionless.Web/Hubs/MessageBusBroker.cs
await _subscriber.SubscribeAsync<EntityChanged>(OnEntityChangedAsync, shutdownToken);
await _subscriber.SubscribeAsync<PlanChanged>(OnPlanChangedAsync, shutdownToken);

// Publishing
await _messagePublisher.PublishAsync(new EntityChanged
{
    ChangeType = ChangeType.Saved,
    Type = nameof(Organization),
    Id = organization.Id
});

Jobs

QueueJobBase - Queue Processing

// From src/Exceptionless.Core/Jobs/EventPostsJob.cs
[Job(Description = "Processes queued events.", InitialDelay = "2s")]
public class EventPostsJob : QueueJobBase<EventPost>
{
    public EventPostsJob(
        IQueue<EventPost> queue,
        TimeProvider timeProvider,
        IResiliencePolicyProvider resiliencePolicyProvider,
        ILoggerFactory loggerFactory)
        : base(queue, timeProvider, resiliencePolicyProvider, loggerFactory)
    {
        AutoComplete = false;  // Manual completion after processing
    }

    protected override async Task<JobResult> ProcessQueueEntryAsync(QueueEntryContext<EventPost> context)
    {
        var entry = context.QueueEntry;
        using var _ = _logger.BeginScope(new ExceptionlessState()
            .Organization(entry.Value.OrganizationId)
            .Project(entry.Value.ProjectId));

        // Process the event...
        await entry.CompleteAsync();
        return JobResult.Success;
    }
}

IJob - Scheduled Jobs

// From src/Exceptionless.Core/Jobs/CleanupDataJob.cs
[Job(Description = "Deletes old data.", InitialDelay = "1m", Interval = "1h")]
public class CleanupDataJob : IJob
{
    public async Task<JobResult> RunAsync(CancellationToken cancellationToken = default)
    {
        await CleanupOrganizationsAsync(cancellationToken);
        await CleanupProjectsAsync(cancellationToken);
        return JobResult.Success;
    }
}

Job Attributes

[Job(
    Description = "Job description",
    InitialDelay = "2s",           // Delay before first run
    Interval = "5m",               // Run every 5 minutes
    IterationLimit = 1,            // Run once then stop
    IsContinuous = true            // Keep running
)]

Resilience with IResiliencePolicyProvider

IResiliencePolicyProvider provides retry policies for Foundatio components:

// Registration in Bootstrapper
services.AddSingleton<IResiliencePolicyProvider, ResiliencePolicyProvider>();

All queue jobs inherit resilience via base class:

// From src/Exceptionless.Core/Jobs/EventPostsJob.cs
public class EventPostsJob : QueueJobBase<EventPost>
{
    public EventPostsJob(
        IQueue<EventPost> queue,
        TimeProvider timeProvider,
        IResiliencePolicyProvider resiliencePolicyProvider,
        ILoggerFactory loggerFactory)
        : base(queue, timeProvider, resiliencePolicyProvider, loggerFactory)
    {
        AutoComplete = false;  // Manual completion for control
    }

    protected override async Task<JobResult> ProcessQueueEntryAsync(QueueEntryContext<EventPost> context)
    {
        var entry = context.QueueEntry;
        try
        {
            // Process...
            await entry.CompleteAsync();
            return JobResult.Success;
        }
        catch (Exception ex) when (ex is ValidationException or MiniValidatorException)
        {
            // Don't retry validation errors
            await entry.CompleteAsync();
            return JobResult.Success;
        }
    }
}

Components configured with resilience:

// From src/Exceptionless.Core/Bootstrapper.cs
services.AddSingleton<CacheLockProvider>(s => new CacheLockProvider(
    s.GetRequiredService<ICacheClient>(),
    s.GetRequiredService<IMessageBus>(),
    s.GetRequiredService<TimeProvider>(),
    s.GetRequiredService<IResiliencePolicyProvider>(),
    s.GetRequiredService<ILoggerFactory>()
));

Queue entries can be retried via AbandonAsync() or completed via CompleteAsync().

Repositories

Foundatio.Repositories provides Elasticsearch integration:

// From src/Exceptionless.Core/Repositories/Base/RepositoryBase.cs
public abstract class RepositoryBase<T> : ElasticRepositoryBase<T>
{
    // Automatic change notifications via IMessageBus
    protected override Task PublishChangeTypeMessageAsync(
        ChangeType changeType,
        T? document,
        IDictionary<string, object>? data = null)
    {
        return PublishMessageAsync(CreateEntityChanged(changeType, document));
    }
}

Repository options:

// Cache results
await _repository.GetByIdAsync(id, o => o.Cache());

// Immediate consistency (for tests)
await _repository.AddAsync(entity, o => o.ImmediateConsistency());

Testing

Use in-memory implementations for tests:

services.AddSingleton<ICacheClient, InMemoryCacheClient>();
services.AddSingleton<IMessageBus, InMemoryMessageBus>();
services.AddSingleton(typeof(IQueue<>), typeof(InMemoryQueue<>));

See backend-testing for ProxyTimeProvider patterns.

Resilience & Reliability

Build resilient systems that handle failures gracefully:

• Expect failures: Network calls fail, resources exhaust, concurrent access races
• Timeouts everywhere: Never wait indefinitely; use cancellation tokens
• Retry with backoff: Use exponential backoff with jitter for transient failures
• Graceful degradation: Return cached data, default values, or partial results when appropriate
• Idempotency: Design operations to be safely retryable
• Resource limits: Bound queues, caches, and buffers to prevent memory exhaustion

Retry Pattern

// Queue entries support automatic retry
await entry.AbandonAsync();  // Return to queue for retry
await entry.CompleteAsync(); // Mark as successfully processed

// Don't retry validation errors - they'll never succeed
catch (Exception ex) when (ex is ValidationException or MiniValidatorException)
{
    await entry.CompleteAsync();  // Don't retry
    return JobResult.Success;
}