InMemory Scheduler

The InMemory Scheduler is a lightweight, timer-based scheduling implementation provided by Brighter for testing, development, and demonstration purposes. It requires no external dependencies and stores scheduled jobs in memory using timers.

Important Warning

The InMemory Scheduler is NOT durable and is NOT recommended for production use.

No Persistence: All scheduled jobs are lost if the application crashes or restarts
No Distribution: Cannot be shared across multiple application instances
No Recovery: Failed jobs are not automatically retried after restart
Memory Bound: All scheduled jobs are held in memory

Use this scheduler for:

Unit and integration tests
Local development
Demos and proof-of-concepts
Production scenarios where losing scheduled work is acceptable

What is the InMemory Scheduler?

The InMemory Scheduler uses .NET's ITimerProvider internally to schedule delayed execution of messages. When you schedule a message:

Brighter creates an in-memory timer for the specified delay
The timer fires at the scheduled time
Brighter dispatches your message to the appropriate handler
The timer is removed from memory

This simple approach makes it perfect for testing but unsuitable for production systems that require durability.

Architecture

Your Code
    ↓
CommandProcessor.SendAsync(command, delay)
    ↓
InMemoryScheduler
    ↓
ITimerProvider.CreateTimer(delay)
    ↓
[Timer stored in memory]
    ↓
[Timer fires after delay]
    ↓
CommandProcessor dispatches command
    ↓
Your Handler executes

When to Use InMemory Scheduler

Recommended Use Cases

Unit Testing:

[Fact]
public async Task Should_Schedule_Command_For_Later_Execution()
{
    // Arrange
    var services = new ServiceCollection();
    services.AddBrighter(options => { ... })
        .UseScheduler(new InMemorySchedulerFactory())  // Perfect for tests
        .AutoFromAssemblies();

    var provider = services.BuildServiceProvider();
    var commandProcessor = provider.GetRequiredService<IAmACommandProcessor>();

    // Act
    var schedulerId = await commandProcessor.SendAsync(
        TimeSpan.FromMilliseconds(100),
        new TestCommand(),
    );

    // Assert
    Assert.NotNull(schedulerId);
    await Task.Delay(150);  // Wait for scheduled execution
    // Verify command was handled...
}

Limited Production Scenarios

The InMemory Scheduler might be acceptable in production only if:

Loss of scheduled work is acceptable (non-critical notifications, analytics, etc.)
Your application rarely restarts
Scheduled work has short delays (minutes, not hours/days)
You have alternative mechanisms to recover lost work

Example - Acceptable Production Use:

// Low-priority analytics events that can be lost
public class AnalyticsService
{
    private readonly IAmACommandProcessor _commandProcessor;

    public async Task TrackUserAction(string userId, string action)
    {
        // Track immediately
        await _repository.SaveActionAsync(userId, action);

        // Schedule low-priority aggregation (acceptable to lose)
        await _commandProcessor.SendAsync(
             TimeSpan.FromMinutes(5),
            new AggregateAnalyticsCommand { UserId = userId }
        );
    }
}

Configuration

Basic Configuration

Configure the InMemory Scheduler with InMemorySchedulerFactory:

using Paramore.Brighter.Extensions.DependencyInjection;
using Paramore.Brighter.InMemoryScheduler;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBrighter(options =>
{
    options.HandlerLifetime = ServiceLifetime.Scoped;
})
.UseScheduler(new InMemorySchedulerFactory())  // Add InMemory Scheduler
.AutoFromAssemblies();

var app = builder.Build();

Environment-Specific Configuration

Use InMemory for development, production schedulers elsewhere:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBrighter(options =>
{
    options.HandlerLifetime = ServiceLifetime.Scoped;
})
.UseScheduler(GetSchedulerFactory(builder.Environment, builder.Configuration))
.AutoFromAssemblies();

static IMessageSchedulerFactory GetSchedulerFactory(
    IHostEnvironment environment,
    IConfiguration configuration)
{
    if (environment.IsDevelopment() || environment.IsEnvironment("Testing"))
    {
        return new InMemorySchedulerFactory();
    }

    // Production - use durable scheduler
    return new HangfireMessageSchedulerFactory(
        configuration.GetConnectionString("Hangfire")
    );
}

Configuration with Custom Timer Provider

The InMemory Scheduler uses ITimerProvider internally. You can provide a custom implementation for testing:

public class FakeTimerProvider : ITimerProvider
{
    public ITimer CreateTimer(TimerCallback callback, object state, TimeSpan dueTime, TimeSpan period)
    {
        // Custom timer implementation for testing
        return new FakeTimer(callback, state, dueTime, period);
    }
}

// Use in tests
services.AddBrighter(options => { ... })
    .UseScheduler(new InMemorySchedulerFactory(new FakeTimerProvider()))
    .AutoFromAssemblies();

NuGet Package

To use the InMemory Scheduler, install the NuGet package:

dotnet add package Paramore.Brighter.InMemoryScheduler

Package: Paramore.Brighter.InMemoryScheduler

Code Examples

Basic Scheduling

Schedule a command with a delay:

public class OrderService
{
    private readonly IAmACommandProcessor _commandProcessor;

    public async Task CreateOrder(Order order)
    {
        await _repository.SaveAsync(order);

        // Schedule order confirmation email for 5 minutes later
        var schedulerId = await _commandProcessor.SendAsync(
            TimeSpan.FromMinutes(5),
            new SendOrderConfirmationCommand { OrderId = order.Id }
        );

        _logger.LogInformation("Scheduled confirmation email: {SchedulerId}", schedulerId);
    }
}

Scheduling with Absolute Time

Schedule for a specific time:

public class ReportService
{
    private readonly IAmACommandProcessor _commandProcessor;

    public async Task ScheduleDailyReport()
    {
        // Schedule for tomorrow at 9 AM
        var tomorrow9AM = DateTimeOffset.UtcNow.Date.AddDays(1).AddHours(9);

        var schedulerId = await _commandProcessor.SendAsync(
            tomorrow9AM, 
            new GenerateDailyReportCommand { Date = DateTime.UtcNow.Date }
        );

        _logger.LogInformation("Scheduled daily report: {SchedulerId}", schedulerId);
    }
}

Cancelling a Scheduled Job

Cancel a previously scheduled job:

public class OrderService
{
    private readonly IAmACommandProcessor _commandProcessor;
    private readonly IMessageScheduler _scheduler;

    public async Task CancelOrder(Guid orderId)
    {
        var order = await _repository.GetAsync(orderId);

        // Cancel the scheduled confirmation email
        if (!string.IsNullOrEmpty(order.ConfirmationSchedulerId))
        {
            await _scheduler.CancelAsync(order.ConfirmationSchedulerId);
            _logger.LogInformation("Cancelled scheduled email for order {OrderId}", orderId);
        }

        order.Status = OrderStatus.Cancelled;
        await _repository.UpdateAsync(order);
    }
}

Testing with InMemory Scheduler

Example unit test using InMemory Scheduler:

public class SchedulingTests : IDisposable
{
    private readonly ServiceProvider _serviceProvider;
    private readonly IAmACommandProcessor _commandProcessor;
    private readonly TestHandlerRegistry _handlerRegistry;

    public SchedulingTests()
    {
        var services = new ServiceCollection();
        _handlerRegistry = new TestHandlerRegistry();

        services.AddBrighter(options =>
        {
            options.HandlerLifetime = ServiceLifetime.Scoped;
        })
        .UseScheduler(new InMemorySchedulerFactory())  // InMemory for tests
        .Handlers(_handlerRegistry)
        .AutoFromAssemblies();

        _serviceProvider = services.BuildServiceProvider();
        _commandProcessor = _serviceProvider.GetRequiredService<IAmACommandProcessor>();
    }

    [Fact]
    public async Task Should_Execute_Scheduled_Command_After_Delay()
    {
        // Arrange
        var command = new TestCommand { Id = Guid.NewGuid() };
        var delay = TimeSpan.FromMilliseconds(100);

        // Act
        var schedulerId = await _commandProcessor.SendAsync(delay, command);

        // Assert - command not yet executed
        Assert.False(_handlerRegistry.WasHandled(command.Id));

        // Wait for scheduled execution
        await Task.Delay(delay.Add(TimeSpan.FromMilliseconds(50)));

        // Assert - command executed
        Assert.True(_handlerRegistry.WasHandled(command.Id));
    }

    [Fact]
    public async Task Should_Cancel_Scheduled_Command()
    {
        // Arrange
        var command = new TestCommand { Id = Guid.NewGuid() };
        var delay = TimeSpan.FromSeconds(10);  // Long delay
        var scheduler = _serviceProvider.GetRequiredService<IMessageScheduler>();

        // Act
        var schedulerId = await _commandProcessor.SendAsync(delay, command);
        await scheduler.CancelAsync(schedulerId);  // Cancel immediately

        // Wait to ensure it would have executed
        await Task.Delay(TimeSpan.FromSeconds(11));

        // Assert - command was NOT executed
        Assert.False(_handlerRegistry.WasHandled(command.Id));
    }

    public void Dispose()
    {
        _serviceProvider?.Dispose();
    }
}

Comparison with Production Schedulers

Feature

InMemory

Quartz.NET

Hangfire

AWS Scheduler

Azure Service Bus

Persistence

None

Database

AWS

Azure

Distribution

Yes

Cancellation

Yes

Limited

Dashboard

Limited

Yes

AWS Console

Azure Portal

Setup Complexity

Minimal

Moderate

Easy

️Moderate

Easy

Production Ready

Yes

Testing

Ideal

Overkill

Best Practices

1. Use for Testing Only

// Good - Environment-specific
if (environment.IsDevelopment() || environment.IsEnvironment("Testing"))
{
    services.UseScheduler(new InMemorySchedulerFactory());
}

// Bad - Always using InMemory in production
services.UseScheduler(new InMemorySchedulerFactory());

2. Document Production Limitations

If you use InMemory in production, document why:

// PRODUCTION NOTE: Using InMemory scheduler because loss of
// scheduled analytics aggregations is acceptable. These are
// non-critical and will be regenerated on next sync.
services.UseScheduler(new InMemorySchedulerFactory());

3. Keep Delays Short

If using in production, keep delays under a few minutes:

// Good - Short delay acceptable to lose
await _commandProcessor.SendAsync(TimeSpan.FromMinutes(2), command);

// Bad - Long delay likely to be lost
await _commandProcessor.SendAsync(TimeSpan.FromHours(24), command);

4. Test Scheduler Behavior

Write tests that verify scheduled behavior:

[Fact]
public async Task Should_Handle_Concurrent_Scheduled_Commands()
{
    // Schedule multiple commands with different delays
    var ids = new List<string>();
    for (int i = 0; i < 10; i++)
    {
        ids.Add(await _commandProcessor.SendAsync(
            TimeSpan.FromMilliseconds(50 + i * 10),
            new TestCommand { Number = i }
        ));
    }

    // Wait for all to execute
    await Task.Delay(TimeSpan.FromMilliseconds(200));

    // Verify all were handled
    Assert.Equal(10, _handlerRegistry.HandledCount);
}

5. Don't Rely on It for Critical Work

// Bad - Critical payment processing
await _commandProcessor.SendAsync(
    TimeSpan.FromMinutes(5),
    new ProcessPaymentCommand { Amount = 1000.00m }
);

// Good - Critical work should use durable scheduler
await _commandProcessor.SendAsync(
    TimeSpan.FromMinutes(5),
    new ProcessPaymentCommand { Amount = 1000.00m }
);  // With Quartz or Hangfire in production

Migration to Production Scheduler

When moving to production, replace InMemory with a durable scheduler:

Before (Development):

services.AddBrighter(options => { ... })
    .UseScheduler(new InMemorySchedulerFactory())
    .AutoFromAssemblies();

After (Production with Hangfire):

services.AddBrighter(options => { ... })
    .UseScheduler(new HangfireMessageSchedulerFactory(
        Configuration.GetConnectionString("Hangfire")
    ))
    .AutoFromAssemblies();

After (Production with Quartz):

services.AddBrighter(options => { ... })
    .UseScheduler(new QuartzMessageSchedulerFactory(
        Configuration.GetSection("Quartz")
    ))
    .AutoFromAssemblies();

No code changes required - just swap the scheduler factory!

Troubleshooting

Scheduled Jobs Not Executing

Symptom: Jobs scheduled but never execute

Possible Causes:

Application stopped before timer fires
Delay too short (already passed)
Exception in handler preventing execution

Solution:

// Add logging to verify scheduling
var schedulerId = await _commandProcessor.SendAsync(delay, command);
_logger.LogInformation("Scheduled job {SchedulerId} for {Delay}", schedulerId, delay);

// Verify handler is registered
Assert.NotNull(_serviceProvider.GetService<IHandleRequestsAsync<YourCommand>>());

Scheduled Jobs Lost After Restart

Symptom: Application restart loses all scheduled jobs

Cause: This is expected behavior - InMemory scheduler has no persistence

Solution: Use a production scheduler (Quartz, Hangfire) if you need durability

Memory Usage Growing

Symptom: Memory consumption increases over time

Cause: Too many scheduled jobs held in memory