DotNetBrightener.Core.BackgroundTasks 2025.0.6-preview-406

This is a prerelease version of DotNetBrightener.Core.BackgroundTasks.
dotnet add package DotNetBrightener.Core.BackgroundTasks --version 2025.0.6-preview-406
                    
NuGet\Install-Package DotNetBrightener.Core.BackgroundTasks -Version 2025.0.6-preview-406
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="DotNetBrightener.Core.BackgroundTasks" Version="2025.0.6-preview-406" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="DotNetBrightener.Core.BackgroundTasks" Version="2025.0.6-preview-406" />
                    
Directory.Packages.props
<PackageReference Include="DotNetBrightener.Core.BackgroundTasks" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add DotNetBrightener.Core.BackgroundTasks --version 2025.0.6-preview-406
                    
#r "nuget: DotNetBrightener.Core.BackgroundTasks, 2025.0.6-preview-406"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package DotNetBrightener.Core.BackgroundTasks@2025.0.6-preview-406
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=DotNetBrightener.Core.BackgroundTasks&version=2025.0.6-preview-406&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=DotNetBrightener.Core.BackgroundTasks&version=2025.0.6-preview-406&prerelease
                    
Install as a Cake Tool

DotNetBrightener Background Tasks

Overview

The DotNetBrightener Background Tasks module provides a comprehensive, cron-based task scheduling system for .NET applications. It enables developers to schedule and execute background tasks with precise timing control, overlap prevention, and robust error handling.

Key Features

  • Flexible Scheduling: Support for cron expressions, predefined intervals, and one-time execution
  • Overlap Prevention: Built-in locking mechanism to prevent concurrent execution of the same task
  • Multiple Task Types: Support for both interface-based tasks (IBackgroundTask) and method-based tasks
  • Event-Driven Architecture: Integration with EventPubSub system for task lifecycle events
  • Database Persistence: Optional database storage for task definitions and execution history
  • Timezone Support: Execute tasks in specific timezones
  • Conditional Execution: Execute tasks based on custom predicates
  • Dependency Injection: Full integration with .NET's dependency injection container
  • Comprehensive Logging: Detailed logging for monitoring and debugging

Architecture

Core Components

IScheduler

The main interface for scheduling and managing background tasks. Provides methods to:

  • Schedule tasks by type or method
  • Execute tasks at specific times
  • Cancel running tasks
  • Unschedule tasks
IBackgroundTask

Interface that background task classes must implement:

public interface IBackgroundTask
{
    Task Execute();
}
ICancellableTask

Extended interface for tasks that support cancellation:

public interface ICancellableTask : IBackgroundTask
{
    CancellationToken CancellationToken { get; set; }
}
IScheduleConfig

Fluent interface for configuring task schedules with methods like:

  • EverySecond(), EveryMinute(), Hourly(), Daily()
  • Cron(string expression)
  • PreventOverlapping()
  • When(Func<Task<bool>> predicate)
  • AtTimeZone(TimeZoneInfo timeZoneInfo)

Task Execution Flow

  1. SchedulerHostedService runs every second
  2. Scheduler checks all registered tasks for due execution
  3. Tasks are executed in parallel with proper scoping
  4. Events are published for task lifecycle (Started, Ended, Failed)
  5. Overlap prevention is enforced if configured
  6. Results and errors are logged

Getting Started

1. Installation and Setup

Add the background tasks services to your application:

var builder = WebApplication.CreateBuilder(args);

// Enable background task services
builder.Services.EnableBackgroundTaskServices(builder.Configuration);

var app = builder.Build();

2. Creating Background Tasks

Interface-Based Tasks
public class EmailCleanupTask : IBackgroundTask
{
    private readonly IEmailService _emailService;
    private readonly ILogger<EmailCleanupTask> _logger;

    public EmailCleanupTask(IEmailService emailService, ILogger<EmailCleanupTask> logger)
    {
        _emailService = emailService;
        _logger = logger;
    }

    public async Task Execute()
    {
        _logger.LogInformation("Starting email cleanup task");
        await _emailService.DeleteOldEmails();
        _logger.LogInformation("Email cleanup task completed");
    }
}
Cancellable Tasks
public class DataProcessingTask : ICancellableTask
{
    public CancellationToken CancellationToken { get; set; }
    
    public async Task Execute()
    {
        while (!CancellationToken.IsCancellationRequested)
        {
            // Process data
            await ProcessBatch();
            await Task.Delay(1000, CancellationToken);
        }
    }
}

3. Registering Tasks

// Register background tasks
builder.Services.AddBackgroundTask<EmailCleanupTask>();
builder.Services.AddBackgroundTask<DataProcessingTask>();

4. Scheduling Tasks

var scheduler = app.Services.GetService<IScheduler>();

// Schedule with predefined intervals
scheduler.ScheduleTask<EmailCleanupTask>()
         .Daily()
         .PreventOverlapping();

// Schedule with custom intervals
scheduler.ScheduleTask<DataProcessingTask>()
         .EverySeconds(30)
         .PreventOverlapping();

// Schedule with cron expressions
scheduler.ScheduleTask<EmailCleanupTask>()
         .Cron("0 2 * * *") // Daily at 2 AM
         .AtTimeZone(TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time"));

// One-time execution
scheduler.ScheduleTask<DataProcessingTask>()
         .Once();

Advanced Features

Method-Based Scheduling

You can schedule methods directly without implementing IBackgroundTask:

public class UtilityService
{
    public async Task CleanupTempFiles()
    {
        // Cleanup logic
    }
    
    public void GenerateReports()
    {
        // Report generation logic
    }
}

// Schedule methods
var methodInfo = typeof(UtilityService).GetMethod(nameof(UtilityService.CleanupTempFiles));
scheduler.ScheduleTask(methodInfo)
         .Hourly()
         .PreventOverlapping();

Conditional Execution

Execute tasks only when certain conditions are met:

scheduler.ScheduleTask<BackupTask>()
         .Daily()
         .When(async () => await IsMaintenanceWindowOpen())
         .PreventOverlapping();

Timezone-Aware Scheduling

scheduler.ScheduleTask<ReportTask>()
         .DailyAt(9, 0) // 9:00 AM
         .AtTimeZone(TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time"));

Configuration

Basic Configuration

Configure the scheduler interval in appsettings.json:

{
  "BackgroundTaskOptions": {
    "Interval": "00:00:30"
  }
}

Database Storage (Optional)

For persistent task definitions and execution history:

builder.Services.AddBackgroundTaskStorage(options =>
{
    options.UseSqlServer(connectionString);
});

This creates a BackgroundTaskDefinition table to store:

  • Task assembly and type information
  • Cron expressions and timezone settings
  • Execution history and error logs
  • Enable/disable status

Event System Integration

The background tasks system publishes events through the EventPubSub system:

Available Events

  • ScheduledEventStarted: Published when a task begins execution
  • ScheduledEventEnded: Published when a task completes successfully
  • ScheduledEventFailed: Published when a task throws an exception

Event Handlers

public class TaskMonitoringHandler : IEventHandler<ScheduledEventFailed>
{
    public async Task<bool> HandleEvent(ScheduledEventFailed eventMessage)
    {
        // Log error, send notifications, etc.
        return true;
    }
}

Scheduling Options Reference

Predefined Intervals

  • EverySecond() - Every second
  • EverySeconds(int seconds) - Every N seconds
  • EveryMinute() - Every minute
  • EveryFiveMinutes() - Every 5 minutes
  • EveryTenMinutes() - Every 10 minutes
  • EveryFifteenMinutes() - Every 15 minutes
  • EveryThirtyMinutes() - Every 30 minutes
  • Hourly() - Every hour
  • HourlyAt(int minute) - Every hour at specified minute
  • Daily() - Every day at midnight
  • DailyAt(int hour, int minute) - Every day at specified time
  • Weekly() - Every week
  • Monthly() - Every month

Day-of-Week Restrictions

  • Monday(), Tuesday(), Wednesday(), Thursday(), Friday(), Saturday(), Sunday()
  • Weekday() - Monday through Friday
  • Weekend() - Saturday and Sunday

Cron Expressions

Support for standard 5 or 6-part cron expressions:

  • 5-part: minute hour day month weekday
  • 6-part: second minute hour day month weekday

Examples:

  • "0 2 * * *" - Daily at 2:00 AM
  • "*/15 * * * *" - Every 15 minutes
  • "0 0 * * 0" - Every Sunday at midnight
  • "30 14 1 * *" - 2:30 PM on the 1st of every month

Error Handling and Monitoring

Logging

The system provides comprehensive logging at various levels:

  • Task execution start/end
  • Error details with stack traces
  • Performance metrics (execution duration)
  • Overlap prevention actions

Exception Handling

  • Exceptions in tasks are caught and logged
  • Failed tasks don't affect other scheduled tasks
  • ScheduledEventFailed events are published for monitoring

Performance Monitoring

  • Execution duration tracking
  • Concurrent execution monitoring
  • Scheduler iteration counts

Best Practices

  1. Use Dependency Injection: Register tasks as scoped services for proper resource management
  2. Implement Proper Logging: Use structured logging for better monitoring
  3. Handle Cancellation: Implement ICancellableTask for long-running tasks
  4. Prevent Overlapping: Use PreventOverlapping() for tasks that shouldn't run concurrently
  5. Use Appropriate Intervals: Don't over-schedule tasks; consider system resources
  6. Monitor Performance: Watch execution times and adjust schedules accordingly
  7. Handle Exceptions: Implement proper error handling within tasks
  8. Use Timezone Awareness: Specify timezones for business-critical scheduling

Troubleshooting

Common Issues

  1. Tasks Not Executing: Check if EnableBackgroundTaskServices() is called
  2. Dependency Resolution Errors: Ensure tasks are registered with AddBackgroundTask<T>()
  3. Overlapping Prevention Not Working: Verify unique identifiers are properly set
  4. Timezone Issues: Use IANA timezone identifiers for cross-platform compatibility

Debugging

Enable detailed logging to troubleshoot issues:

builder.Services.AddLogging(logging =>
{
    logging.SetMinimumLevel(LogLevel.Debug);
    logging.AddConsole();
});

Migration and Deployment

When using database storage, the system automatically handles database migrations through the MigrateBackgroundTaskDbContextHostedService.

Performance Considerations

  • The scheduler runs every second by default
  • Tasks execute in parallel using separate service scopes
  • Overlap prevention uses in-memory locking with configurable timeouts
  • Database operations are optimized with proper indexing
Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on DotNetBrightener.Core.BackgroundTasks:

Package Downloads
DotNetBrightener.WebApp.CommonShared

Package Description

DotNetBrightener.Core.BackgroundTasks.DependencyInjection

Package Description

DotNetBrightener.Core.BackgroundTasks.Data

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2025.0.6-preview-406 0 9/2/2025
2025.0.6-preview-401 19 9/2/2025
2025.0.6-preview-400 24 9/2/2025
2025.0.6-preview-369 169 8/27/2025
2025.0.6-preview-368 168 8/27/2025
2025.0.6-preview-334 160 8/18/2025
2025.0.6-preview-333 71 7/27/2025
2025.0.6-preview-332 442 7/24/2025
2025.0.6-preview-331 448 7/24/2025
2025.0.6-preview-328 445 7/24/2025
2025.0.6-preview-327 284 7/21/2025
2025.0.6-preview-326 283 7/21/2025
2025.0.6-preview-325 190 7/20/2025
2025.0.6-preview-324 187 7/20/2025
2025.0.6-preview-322 190 7/20/2025
2025.0.6-preview-321 194 7/19/2025
2025.0.6-preview-320 191 7/19/2025
2025.0.6-preview-319 121 7/17/2025
2025.0.6-preview-317 120 7/17/2025
2025.0.6-preview-316 122 7/17/2025
2025.0.6-preview-315 120 7/17/2025
2025.0.6-preview-314 120 7/17/2025
2025.0.6-preview-313 120 7/17/2025
2025.0.6-preview-312 134 7/16/2025
2025.0.5 166 7/10/2025
2025.0.5-preview-307 90 7/5/2025
2025.0.4 96 7/5/2025
2025.0.4-preview-305 102 7/4/2025
2025.0.4-preview-304 157 7/1/2025
2025.0.4-preview-299 140 5/31/2025
2025.0.4-preview-298 124 5/30/2025
2025.0.4-preview-296 154 5/30/2025
2025.0.4-preview-295 166 5/29/2025
2025.0.4-preview-293 167 5/26/2025
2025.0.4-preview-292 166 5/26/2025
2025.0.3 175 2/10/2025
2025.0.3-preview-288 135 2/10/2025
2025.0.2 160 1/21/2025
2025.0.2-preview-278 117 1/21/2025
2025.0.2-preview-277 130 12/16/2024
2025.0.1-rc-243301701 416 11/25/2024
2024.0.14.6 170 11/25/2024
2024.0.14.6-rc-243031001 212 10/29/2024
2024.0.14.6-rc-243030701 140 10/29/2024
2024.0.14.6-rc-242840501 132 10/10/2024
2024.0.14.6-rc-242820305 134 10/8/2024
2024.0.14.6-rc-242771401 273 10/3/2024
2024.0.14.6-rc-242770501 132 10/3/2024
2024.0.14.6-rc-242770201 151 10/3/2024
2024.0.14.6-rc-242761801 135 10/2/2024
2024.0.14.6-rc-242761601 143 10/2/2024
2024.0.14.6-rc-242761501 135 10/2/2024
2024.0.14.6-rc-242761401 149 10/2/2024
2024.0.14.6-rc-242760701 150 10/2/2024
2024.0.14.6-rc-242751002 134 10/1/2024
2024.0.14.6-rc-242750901 144 10/1/2024
2024.0.14.6-rc-242750502 139 10/1/2024
2024.0.14.6-rc-242750201 134 10/1/2024
2024.0.14.6-rc-242741501 137 9/30/2024
2024.0.14.6-rc-242730701 150 9/29/2024
2024.0.14.6-preview-2730501 136 9/29/2024
2024.0.14.6-preview-2701501 163 9/26/2024
2024.0.14.6-preview-2620901 200 9/18/2024
2024.0.14.6-preview-2570701 159 9/13/2024
2024.0.14.6-preview-2510703 214 9/7/2024
2024.0.14.6-preview-2480501 165 9/4/2024
2024.0.14.6-preview-2430401 179 8/30/2024
2024.0.14.6-preview-242730701 131 9/29/2024
2024.0.14.6-preview-2421703 153 8/29/2024
2024.0.14.6-preview-2421701 139 8/29/2024
2024.0.14.6-preview-2420901 138 8/29/2024
2024.0.14.6-preview-2390101 179 8/26/2024
2024.0.14.6-preview-2381603 171 8/25/2024
2024.0.14.6-preview-2341601 214 8/21/2024
2024.0.14.6-preview-2321602 171 8/20/2024
2024.0.14.6-preview-2190801 194 8/6/2024
2024.0.14.6-preview-2041501 151 7/22/2024
2024.0.14.6-preview-1920603 208 7/10/2024
2024.0.14.6-preview-1920301 138 7/10/2024
2024.0.14.6-preview-1911302 147 7/9/2024
2024.0.14.6-preview-1901001 158 7/8/2024
2024.0.14.6-preview-1900901 149 7/8/2024
2024.0.14.6-preview-1900801 150 7/8/2024
2024.0.14.6-preview-1860304 153 7/4/2024
2024.0.14.5 241 7/1/2024
2024.0.14.5-preview-1811601 160 6/29/2024
2024.0.14.5-preview-1810501 179 6/29/2024
2024.0.14.5-preview-180132 168 6/28/2024
2024.0.14.5-preview-180131 153 6/28/2024
2024.0.14.5-preview-180121 156 6/28/2024
2024.0.14.4 198 6/27/2024
2024.0.14.4-preview-8 137 6/27/2024
2024.0.14.4-preview-7 163 6/27/2024
2024.0.14.3 186 6/21/2024
2024.0.14.1 184 6/6/2024
2024.0.14.1-preview 152 6/6/2024
2024.0.14-preview-1 149 6/6/2024
2024.0.13.8-preview 160 6/6/2024
2024.0.13.2-preview-247 124 6/6/2024
2024.0.13.1-preview-0146 157 6/6/2024
2024.0.13-preview-1 128 6/6/2024
2024.0.12.15803-preview-03 146 6/6/2024
2024.0.12.15608 173 6/4/2024
2024.0.12.15515 262 6/3/2024
2024.0.12.15220 174 5/31/2024
2024.0.12.15220-alpha31-240... 128 5/31/2024
2024.0.12.14911 229 5/28/2024
2024.0.12.14910-alpha28-240... 144 5/28/2024
2024.0.12.14823 206 5/27/2024
2024.0.12.14522-alpha7-2405... 166 5/24/2024
2024.0.12.14514-alpha6-2405... 179 5/24/2024
2024.0.12.14511 208 5/24/2024
2024.0.12.14314 234 5/22/2024
2024.0.12.14114 218 5/20/2024
2024.0.12.12815 241 5/7/2024
2024.0.12.12814 207 5/7/2024
2024.0.12.12721 225 5/6/2024
2024.0.12.12702 196 5/5/2024
2024.0.12.12622 220 5/5/2024
2024.0.12.12514 199 5/4/2024
2024.0.12.12512 207 5/4/2024
2024.0.12.12510 212 5/4/2024
2024.0.12.12420 187 5/3/2024
2024.0.12.12319 164 5/2/2024
2024.0.12.12319-rc-2405021801 106 5/2/2024
2024.0.12.12318 151 5/2/2024
2024.0.12.12215 197 5/1/2024
2024.0.12.12011 193 4/29/2024
2024.0.12.11720 208 4/26/2024
2024.0.12.11719 196 4/26/2024
2024.0.12.11621 205 4/25/2024
2024.0.12.11523 200 4/24/2024
2024.0.12.11522 209 4/24/2024
2024.0.12.11417 194 4/23/2024
2024.0.12.11400 194 4/22/2024
2024.0.12.11316 186 4/22/2024
2024.0.11.10220 190 4/11/2024
2024.0.11.10120 163 4/10/2024
2024.0.11.10119 168 4/10/2024
2024.0.11.10115 159 4/10/2024
2024.0.11.9914 197 4/8/2024
2024.0.11.9901 167 4/7/2024
2024.0.11.9823 180 4/7/2024
2024.0.11.9401 185 4/2/2024
2024.0.11.9301 174 4/1/2024
2024.0.11.9206 186 3/31/2024
2024.0.11.9205 177 3/31/2024
2024.0.11.8200 188 3/21/2024
2024.0.11.8122 149 3/21/2024
2024.0.11.8120 165 3/21/2024
2024.0.11.7320 203 3/13/2024
2024.0.11.7316 169 3/13/2024
2024.0.11.7310 183 3/13/2024
2024.0.11 180 3/13/2024
2024.0.10 212 3/3/2024
2024.0.9 198 2/27/2024
2024.0.8 226 2/1/2024
2024.0.7 170 1/26/2024
2024.0.6 177 1/25/2024
2024.0.5 165 1/24/2024
2024.0.4 164 1/24/2024
2024.0.3 179 1/22/2024
2024.0.2 235 1/10/2024
2024.0.1 178 1/9/2024
2024.0.1-alpha-3 167 1/9/2024
2024.0.1-alpha-2 136 1/9/2024
2024.0.1-alpha-1 154 1/3/2024
2024.0.0 235 12/26/2023
2023.0.27 307 12/21/2023
2023.0.26 199 12/21/2023
2023.0.25 229 12/11/2023
2023.0.24 207 12/8/2023
2023.0.23 198 12/6/2023
2023.0.21 210 12/4/2023
2023.0.20 231 11/27/2023
2023.0.19 208 11/20/2023
2023.0.18 237 10/25/2023
2023.0.17 250 10/22/2023
2023.0.16 290 10/16/2023
2023.0.16-alpha-1 161 10/16/2023
2023.0.15 205 10/14/2023
2023.0.14 190 10/14/2023
2023.0.13 191 10/14/2023
2023.0.12 208 10/14/2023
2023.0.11 196 10/10/2023
2023.0.10 206 10/9/2023
2023.0.9 296 8/16/2023
2023.0.8 221 8/15/2023
2023.0.8-alpha-2 293 5/31/2023
2023.0.7 221 5/12/2023
2023.0.6 384 5/10/2023
2023.0.5 229 5/7/2023
2023.0.4 246 4/22/2023
2023.0.3 276 4/19/2023
2023.0.2 294 4/6/2023
2023.0.1 283 3/13/2023
2022.10.0 332 10/28/2022