DotNetBrightener.Core.BackgroundTasks 2025.0.8

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package DotNetBrightener.Core.BackgroundTasks --version 2025.0.8
                    
NuGet\Install-Package DotNetBrightener.Core.BackgroundTasks -Version 2025.0.8
                    
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.8" />
                    
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.8" />
                    
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.8
                    
#r "nuget: DotNetBrightener.Core.BackgroundTasks, 2025.0.8"
                    
#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.8
                    
#: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.8
                    
Install as a Cake Addin
#tool nuget:?package=DotNetBrightener.Core.BackgroundTasks&version=2025.0.8
                    
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.9-preview-473 20 9/28/2025
2025.0.8 169 9/23/2025
2025.0.6 173 9/22/2025
2025.0.6-preview-455 180 9/22/2025
2025.0.6-preview-454 284 9/17/2025
2025.0.6-preview-441 136 9/14/2025
2025.0.6-preview-440 117 9/14/2025
2025.0.6-preview-406 164 9/2/2025
2025.0.6-preview-401 144 9/2/2025
2025.0.6-preview-400 143 9/2/2025
2025.0.6-preview-369 194 8/27/2025
2025.0.6-preview-368 194 8/27/2025
2025.0.6-preview-334 186 8/18/2025
2025.0.6-preview-333 121 7/27/2025
2025.0.6-preview-332 474 7/24/2025
2025.0.6-preview-331 488 7/24/2025
2025.0.6-preview-328 479 7/24/2025
2025.0.6-preview-327 361 7/21/2025
2025.0.6-preview-326 349 7/21/2025
2025.0.6-preview-325 267 7/20/2025
2025.0.6-preview-324 255 7/20/2025
2025.0.6-preview-322 253 7/20/2025
2025.0.6-preview-321 262 7/19/2025
2025.0.6-preview-320 255 7/19/2025
2025.0.6-preview-319 161 7/17/2025
2025.0.6-preview-317 161 7/17/2025
2025.0.6-preview-316 155 7/17/2025
2025.0.6-preview-315 169 7/17/2025
2025.0.6-preview-314 159 7/17/2025
2025.0.6-preview-313 168 7/17/2025
2025.0.6-preview-312 173 7/16/2025
2025.0.5 195 7/10/2025
2025.0.5-preview-307 99 7/5/2025
2025.0.4 125 7/5/2025
2025.0.4-preview-305 114 7/4/2025
2025.0.4-preview-304 169 7/1/2025
2025.0.4-preview-299 166 5/31/2025
2025.0.4-preview-298 132 5/30/2025
2025.0.4-preview-296 179 5/30/2025
2025.0.4-preview-295 180 5/29/2025
2025.0.4-preview-293 188 5/26/2025
2025.0.4-preview-292 186 5/26/2025
2025.0.3 194 2/10/2025
2025.0.3-preview-288 145 2/10/2025
2025.0.2 179 1/21/2025
2025.0.2-preview-278 123 1/21/2025
2025.0.2-preview-277 155 12/16/2024
2025.0.1-rc-243301701 428 11/25/2024
2024.0.14.6 189 11/25/2024
2024.0.14.6-rc-243031001 231 10/29/2024
2024.0.14.6-rc-243030701 162 10/29/2024
2024.0.14.6-rc-242840501 152 10/10/2024
2024.0.14.6-rc-242820305 147 10/8/2024
2024.0.14.6-rc-242771401 285 10/3/2024
2024.0.14.6-rc-242770501 154 10/3/2024
2024.0.14.6-rc-242770201 165 10/3/2024
2024.0.14.6-rc-242761801 146 10/2/2024
2024.0.14.6-rc-242761601 151 10/2/2024
2024.0.14.6-rc-242761501 143 10/2/2024
2024.0.14.6-rc-242761401 157 10/2/2024
2024.0.14.6-rc-242760701 161 10/2/2024
2024.0.14.6-rc-242751002 147 10/1/2024
2024.0.14.6-rc-242750901 157 10/1/2024
2024.0.14.6-rc-242750502 149 10/1/2024
2024.0.14.6-rc-242750201 146 10/1/2024
2024.0.14.6-rc-242741501 146 9/30/2024
2024.0.14.6-rc-242730701 154 9/29/2024
2024.0.14.6-preview-2730501 148 9/29/2024
2024.0.14.6-preview-2701501 179 9/26/2024
2024.0.14.6-preview-2620901 212 9/18/2024
2024.0.14.6-preview-2570701 174 9/13/2024
2024.0.14.6-preview-2510703 240 9/7/2024
2024.0.14.6-preview-2480501 181 9/4/2024
2024.0.14.6-preview-2430401 199 8/30/2024
2024.0.14.6-preview-242730701 143 9/29/2024
2024.0.14.6-preview-2421703 170 8/29/2024
2024.0.14.6-preview-2421701 163 8/29/2024
2024.0.14.6-preview-2420901 158 8/29/2024
2024.0.14.6-preview-2390101 197 8/26/2024
2024.0.14.6-preview-2381603 186 8/25/2024
2024.0.14.6-preview-2341601 226 8/21/2024
2024.0.14.6-preview-2321602 199 8/20/2024
2024.0.14.6-preview-2190801 207 8/6/2024
2024.0.14.6-preview-2041501 168 7/22/2024
2024.0.14.6-preview-1920603 235 7/10/2024
2024.0.14.6-preview-1920301 160 7/10/2024
2024.0.14.6-preview-1911302 159 7/9/2024
2024.0.14.6-preview-1901001 170 7/8/2024
2024.0.14.6-preview-1900901 171 7/8/2024
2024.0.14.6-preview-1900801 175 7/8/2024
2024.0.14.6-preview-1860304 174 7/4/2024
2024.0.14.5 259 7/1/2024
2024.0.14.5-preview-1811601 176 6/29/2024
2024.0.14.5-preview-1810501 207 6/29/2024
2024.0.14.5-preview-180132 186 6/28/2024
2024.0.14.5-preview-180131 169 6/28/2024
2024.0.14.5-preview-180121 168 6/28/2024
2024.0.14.4 222 6/27/2024
2024.0.14.4-preview-8 155 6/27/2024
2024.0.14.4-preview-7 178 6/27/2024
2024.0.14.3 219 6/21/2024
2024.0.14.1 218 6/6/2024
2024.0.14.1-preview 174 6/6/2024
2024.0.14-preview-1 161 6/6/2024
2024.0.13.8-preview 181 6/6/2024
2024.0.13.2-preview-247 128 6/6/2024
2024.0.13.1-preview-0146 177 6/6/2024
2024.0.13-preview-1 142 6/6/2024
2024.0.12.15803-preview-03 162 6/6/2024
2024.0.12.15608 192 6/4/2024
2024.0.12.15515 280 6/3/2024
2024.0.12.15220 195 5/31/2024
2024.0.12.15220-alpha31-240... 140 5/31/2024
2024.0.12.14911 260 5/28/2024
2024.0.12.14910-alpha28-240... 167 5/28/2024
2024.0.12.14823 222 5/27/2024
2024.0.12.14522-alpha7-2405... 180 5/24/2024
2024.0.12.14514-alpha6-2405... 201 5/24/2024
2024.0.12.14511 240 5/24/2024
2024.0.12.14314 261 5/22/2024
2024.0.12.14114 230 5/20/2024
2024.0.12.12815 258 5/7/2024
2024.0.12.12814 227 5/7/2024
2024.0.12.12721 257 5/6/2024
2024.0.12.12702 214 5/5/2024
2024.0.12.12622 248 5/5/2024
2024.0.12.12514 215 5/4/2024
2024.0.12.12512 224 5/4/2024
2024.0.12.12510 231 5/4/2024
2024.0.12.12420 205 5/3/2024
2024.0.12.12319 193 5/2/2024
2024.0.12.12319-rc-2405021801 128 5/2/2024
2024.0.12.12318 168 5/2/2024
2024.0.12.12215 213 5/1/2024
2024.0.12.12011 212 4/29/2024
2024.0.12.11720 221 4/26/2024
2024.0.12.11719 224 4/26/2024
2024.0.12.11621 234 4/25/2024
2024.0.12.11523 218 4/24/2024
2024.0.12.11522 234 4/24/2024
2024.0.12.11417 226 4/23/2024
2024.0.12.11400 209 4/22/2024
2024.0.12.11316 206 4/22/2024
2024.0.11.10220 202 4/11/2024
2024.0.11.10120 183 4/10/2024
2024.0.11.10119 178 4/10/2024
2024.0.11.10115 169 4/10/2024
2024.0.11.9914 218 4/8/2024
2024.0.11.9901 188 4/7/2024
2024.0.11.9823 191 4/7/2024
2024.0.11.9401 207 4/2/2024
2024.0.11.9301 195 4/1/2024
2024.0.11.9206 198 3/31/2024
2024.0.11.9205 198 3/31/2024
2024.0.11.8200 208 3/21/2024
2024.0.11.8122 173 3/21/2024
2024.0.11.8120 183 3/21/2024
2024.0.11.7320 213 3/13/2024
2024.0.11.7316 178 3/13/2024
2024.0.11.7310 200 3/13/2024
2024.0.11 190 3/13/2024
2024.0.10 223 3/3/2024
2024.0.9 203 2/27/2024
2024.0.8 236 2/1/2024
2024.0.7 190 1/26/2024
2024.0.6 186 1/25/2024
2024.0.5 175 1/24/2024
2024.0.4 173 1/24/2024
2024.0.3 189 1/22/2024
2024.0.2 245 1/10/2024
2024.0.1 189 1/9/2024
2024.0.1-alpha-3 184 1/9/2024
2024.0.1-alpha-2 150 1/9/2024
2024.0.1-alpha-1 178 1/3/2024
2024.0.0 245 12/26/2023
2023.0.27 331 12/21/2023
2023.0.26 221 12/21/2023
2023.0.25 240 12/11/2023
2023.0.24 226 12/8/2023
2023.0.23 198 12/6/2023
2023.0.21 210 12/4/2023
2023.0.20 236 11/27/2023
2023.0.19 211 11/20/2023
2023.0.18 242 10/25/2023
2023.0.17 255 10/22/2023
2023.0.16 296 10/16/2023
2023.0.16-alpha-1 176 10/16/2023
2023.0.15 220 10/14/2023
2023.0.14 195 10/14/2023
2023.0.13 196 10/14/2023
2023.0.12 210 10/14/2023
2023.0.11 201 10/10/2023
2023.0.10 212 10/9/2023
2023.0.9 307 8/16/2023
2023.0.8 227 8/15/2023
2023.0.8-alpha-2 311 5/31/2023
2023.0.7 230 5/12/2023
2023.0.6 402 5/10/2023
2023.0.5 242 5/7/2023
2023.0.4 257 4/22/2023
2023.0.3 297 4/19/2023
2023.0.2 303 4/6/2023
2023.0.1 292 3/13/2023
2022.10.0 343 10/28/2022