DotNetBrightener.Core.BackgroundTasks 2025.0.6-preview-406

This is a prerelease version of DotNetBrightener.Core.BackgroundTasks.
There is a newer version of this package available.
See the version list below for details.
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.8 0 9/23/2025
2025.0.6 36 9/22/2025
2025.0.6-preview-455 39 9/22/2025
2025.0.6-preview-454 269 9/17/2025
2025.0.6-preview-441 114 9/14/2025
2025.0.6-preview-440 111 9/14/2025
2025.0.6-preview-406 151 9/2/2025
2025.0.6-preview-401 137 9/2/2025
2025.0.6-preview-400 139 9/2/2025
2025.0.6-preview-369 185 8/27/2025
2025.0.6-preview-368 184 8/27/2025
2025.0.6-preview-334 166 8/18/2025
2025.0.6-preview-333 76 7/27/2025
2025.0.6-preview-332 468 7/24/2025
2025.0.6-preview-331 475 7/24/2025
2025.0.6-preview-328 473 7/24/2025
2025.0.6-preview-327 345 7/21/2025
2025.0.6-preview-326 340 7/21/2025
2025.0.6-preview-325 249 7/20/2025
2025.0.6-preview-324 245 7/20/2025
2025.0.6-preview-322 247 7/20/2025
2025.0.6-preview-321 256 7/19/2025
2025.0.6-preview-320 249 7/19/2025
2025.0.6-preview-319 158 7/17/2025
2025.0.6-preview-317 155 7/17/2025
2025.0.6-preview-316 154 7/17/2025
2025.0.6-preview-315 152 7/17/2025
2025.0.6-preview-314 152 7/17/2025
2025.0.6-preview-313 155 7/17/2025
2025.0.6-preview-312 156 7/16/2025
2025.0.5 180 7/10/2025
2025.0.5-preview-307 96 7/5/2025
2025.0.4 106 7/5/2025
2025.0.4-preview-305 108 7/4/2025
2025.0.4-preview-304 164 7/1/2025
2025.0.4-preview-299 150 5/31/2025
2025.0.4-preview-298 132 5/30/2025
2025.0.4-preview-296 163 5/30/2025
2025.0.4-preview-295 171 5/29/2025
2025.0.4-preview-293 169 5/26/2025
2025.0.4-preview-292 172 5/26/2025
2025.0.3 185 2/10/2025
2025.0.3-preview-288 141 2/10/2025
2025.0.2 170 1/21/2025
2025.0.2-preview-278 123 1/21/2025
2025.0.2-preview-277 134 12/16/2024
2025.0.1-rc-243301701 421 11/25/2024
2024.0.14.6 182 11/25/2024
2024.0.14.6-rc-243031001 220 10/29/2024
2024.0.14.6-rc-243030701 148 10/29/2024
2024.0.14.6-rc-242840501 134 10/10/2024
2024.0.14.6-rc-242820305 143 10/8/2024
2024.0.14.6-rc-242771401 281 10/3/2024
2024.0.14.6-rc-242770501 140 10/3/2024
2024.0.14.6-rc-242770201 158 10/3/2024
2024.0.14.6-rc-242761801 142 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 153 10/2/2024
2024.0.14.6-rc-242760701 158 10/2/2024
2024.0.14.6-rc-242751002 139 10/1/2024
2024.0.14.6-rc-242750901 153 10/1/2024
2024.0.14.6-rc-242750502 143 10/1/2024
2024.0.14.6-rc-242750201 141 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 141 9/29/2024
2024.0.14.6-preview-2701501 167 9/26/2024
2024.0.14.6-preview-2620901 208 9/18/2024
2024.0.14.6-preview-2570701 164 9/13/2024
2024.0.14.6-preview-2510703 222 9/7/2024
2024.0.14.6-preview-2480501 173 9/4/2024
2024.0.14.6-preview-2430401 185 8/30/2024
2024.0.14.6-preview-242730701 135 9/29/2024
2024.0.14.6-preview-2421703 162 8/29/2024
2024.0.14.6-preview-2421701 145 8/29/2024
2024.0.14.6-preview-2420901 144 8/29/2024
2024.0.14.6-preview-2390101 188 8/26/2024
2024.0.14.6-preview-2381603 178 8/25/2024
2024.0.14.6-preview-2341601 218 8/21/2024
2024.0.14.6-preview-2321602 179 8/20/2024
2024.0.14.6-preview-2190801 203 8/6/2024
2024.0.14.6-preview-2041501 160 7/22/2024
2024.0.14.6-preview-1920603 216 7/10/2024
2024.0.14.6-preview-1920301 146 7/10/2024
2024.0.14.6-preview-1911302 151 7/9/2024
2024.0.14.6-preview-1901001 166 7/8/2024
2024.0.14.6-preview-1900901 157 7/8/2024
2024.0.14.6-preview-1900801 154 7/8/2024
2024.0.14.6-preview-1860304 165 7/4/2024
2024.0.14.5 249 7/1/2024
2024.0.14.5-preview-1811601 168 6/29/2024
2024.0.14.5-preview-1810501 185 6/29/2024
2024.0.14.5-preview-180132 174 6/28/2024
2024.0.14.5-preview-180131 161 6/28/2024
2024.0.14.5-preview-180121 164 6/28/2024
2024.0.14.4 210 6/27/2024
2024.0.14.4-preview-8 141 6/27/2024
2024.0.14.4-preview-7 170 6/27/2024
2024.0.14.3 198 6/21/2024
2024.0.14.1 196 6/6/2024
2024.0.14.1-preview 160 6/6/2024
2024.0.14-preview-1 157 6/6/2024
2024.0.13.8-preview 167 6/6/2024
2024.0.13.2-preview-247 128 6/6/2024
2024.0.13.1-preview-0146 165 6/6/2024
2024.0.13-preview-1 132 6/6/2024
2024.0.12.15803-preview-03 153 6/6/2024
2024.0.12.15608 181 6/4/2024
2024.0.12.15515 275 6/3/2024
2024.0.12.15220 185 5/31/2024
2024.0.12.15220-alpha31-240... 136 5/31/2024
2024.0.12.14911 240 5/28/2024
2024.0.12.14910-alpha28-240... 153 5/28/2024
2024.0.12.14823 213 5/27/2024
2024.0.12.14522-alpha7-2405... 166 5/24/2024
2024.0.12.14514-alpha6-2405... 187 5/24/2024
2024.0.12.14511 220 5/24/2024
2024.0.12.14314 242 5/22/2024
2024.0.12.14114 227 5/20/2024
2024.0.12.12815 253 5/7/2024
2024.0.12.12814 218 5/7/2024
2024.0.12.12721 237 5/6/2024
2024.0.12.12702 208 5/5/2024
2024.0.12.12622 230 5/5/2024
2024.0.12.12514 209 5/4/2024
2024.0.12.12512 218 5/4/2024
2024.0.12.12510 224 5/4/2024
2024.0.12.12420 199 5/3/2024
2024.0.12.12319 177 5/2/2024
2024.0.12.12319-rc-2405021801 114 5/2/2024
2024.0.12.12318 163 5/2/2024
2024.0.12.12215 208 5/1/2024
2024.0.12.12011 207 4/29/2024
2024.0.12.11720 216 4/26/2024
2024.0.12.11719 208 4/26/2024
2024.0.12.11621 218 4/25/2024
2024.0.12.11523 212 4/24/2024
2024.0.12.11522 221 4/24/2024
2024.0.12.11417 204 4/23/2024
2024.0.12.11400 207 4/22/2024
2024.0.12.11316 200 4/22/2024
2024.0.11.10220 200 4/11/2024
2024.0.11.10120 171 4/10/2024
2024.0.11.10119 176 4/10/2024
2024.0.11.10115 167 4/10/2024
2024.0.11.9914 206 4/8/2024
2024.0.11.9901 176 4/7/2024
2024.0.11.9823 189 4/7/2024
2024.0.11.9401 193 4/2/2024
2024.0.11.9301 183 4/1/2024
2024.0.11.9206 194 3/31/2024
2024.0.11.9205 185 3/31/2024
2024.0.11.8200 196 3/21/2024
2024.0.11.8122 161 3/21/2024
2024.0.11.8120 171 3/21/2024
2024.0.11.7320 211 3/13/2024
2024.0.11.7316 177 3/13/2024
2024.0.11.7310 188 3/13/2024
2024.0.11 189 3/13/2024
2024.0.10 222 3/3/2024
2024.0.9 202 2/27/2024
2024.0.8 236 2/1/2024
2024.0.7 179 1/26/2024
2024.0.6 185 1/25/2024
2024.0.5 174 1/24/2024
2024.0.4 171 1/24/2024
2024.0.3 187 1/22/2024
2024.0.2 243 1/10/2024
2024.0.1 186 1/9/2024
2024.0.1-alpha-3 172 1/9/2024
2024.0.1-alpha-2 140 1/9/2024
2024.0.1-alpha-1 158 1/3/2024
2024.0.0 242 12/26/2023
2023.0.27 318 12/21/2023
2023.0.26 208 12/21/2023
2023.0.25 239 12/11/2023
2023.0.24 215 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 166 10/16/2023
2023.0.15 210 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 300 5/31/2023
2023.0.7 229 5/12/2023
2023.0.6 397 5/10/2023
2023.0.5 241 5/7/2023
2023.0.4 254 4/22/2023
2023.0.3 284 4/19/2023
2023.0.2 302 4/6/2023
2023.0.1 291 3/13/2023
2022.10.0 342 10/28/2022