EverTask.EfCore
1.1.0
See the version list below for details.
dotnet add package EverTask.EfCore --version 1.1.0
NuGet\Install-Package EverTask.EfCore -Version 1.1.0
<PackageReference Include="EverTask.EfCore" Version="1.1.0" />
paket add EverTask.EfCore --version 1.1.0
#r "nuget: EverTask.EfCore, 1.1.0"
// Install EverTask.EfCore as a Cake Addin #addin nuget:?package=EverTask.EfCore&version=1.1.0 // Install EverTask.EfCore as a Cake Tool #tool nuget:?package=EverTask.EfCore&version=1.1.0
Overview
EverTask is a .NET library for executing background tasks in .NET applications. It is designed to be simple and focuses on task persistence, ensuring that pending tasks resume upon application restart.
This project is in its initial stages, more detailed documentation will be provided in the future.
Features
Feature | Description | |
---|---|---|
Background Task Execution | Easily run background tasks with parameters in .NET | |
Persistence | Resumes pending tasks after application restarts. | |
Managed Parallelism | Efficiently handles concurrent task execution with configurable parallelism. | |
Async All The Way | Fully asynchronous architecture, enhancing performance and scalability in modern environments. | |
Simplicity by Design | Created for simplicity, using the latest .NET technologies. | |
Inspiration from MediaTr | Implementation based on creating requests and handlers. | |
Error Handling | Method overrides for error observation and task completion. | |
In-Memory Storage | Provides an in-memory storage solution for testing and lightweight applications. | |
SQL Storage | Includes support for SQL Server storage, enabling persistent task management. | |
Serilog Integration | Supports integration with Serilog for detailed and customizable logging. | |
Extensible Storage & Logging | Designed to allow easy plug-in of additional database solutions or logging systems. |
Efficient Task Processing
EverTask employs a non-polling approach for task management, utilizing the .NET's System.Threading.Channels
to create a BoundedQueue
. This queue efficiently manages task execution without the need for constant database polling. Upon application restart after a stop, any unprocessed tasks are retrieved from the database in bulk and re-queued in the channel's queue for execution by the background service. This design ensures a seamless and efficient task processing cycle, even across application restarts.
Creating Requests and Handlers with Lifecycle Control
This example demonstrates how to create a request and its corresponding handler in EverTask. The SampleTaskRequest
and SampleTaskRequestHandler
illustrate the basic structure. Additionally, the handler includes optional overrides that allow you to control and monitor the lifecycle of a background task, providing hooks for when a task starts, completes, or encounters an error.
public record SampleTaskRequest(string TestProperty) : IEverTask;
public class SampleTaskRequestHanlder : EverTaskHandler<SampleTaskRequest>
{
private readonly ILogger<SampleTaskRequestHanlder> _logger;
public SampleTaskRequestHanlder(ILogger<SampleTaskRequestHanlder> logger)
{
_logger = logger;
}
public override Task Handle(SampleTaskRequest backgroundTask, CancellationToken cancellationToken)
{
_logger.LogInformation($"Property value: {backgroundTask.TestProperty}");
return Task.CompletedTask;
}
// Optional Overrides
public override ValueTask OnStarted(Guid persistenceId)
{
_logger.LogInformation($"====== TASK WITH ID {persistenceId} STARTED IN BACKGROUND ======");
return ValueTask.CompletedTask;
}
public override ValueTask OnCompleted(Guid persistenceId)
{
_logger.LogInformation($"====== TASK WITH ID {persistenceId} COMPLETED IN BACKGROUND ======");
return ValueTask.CompletedTask;
}
public override ValueTask OnError(Guid persistenceId, Exception? exception, string? message)
{
_logger.LogError(exception, $"Error in task with ID {persistenceId}: {message}");
return ValueTask.CompletedTask;
}
}
Task Dispatch
To dispatch a task, obtain an instance of ITaskDispatcher
. This can be done using Dependency Injection:
// Retrieving ITaskDispatcher via method injection
var _dispatcher = serviceProvider.GetService<ITaskDispatcher>();
// Alternatively, ITaskDispatcher can be injected directly into the constructor of your class
_dispatcher.Dispatch(new SampleTaskRequest("Hello World"));
Basic Configuration
builder.Services.AddEverTask(opt =>
{
opt.SetChannelOptions(50)
.SetThrowIfUnableToPersist(true)
.RegisterTasksFromAssembly(typeof(Program).Assembly);
})
.AddMemoryStorage();
Advanced Configuration
builder.Services.AddEverTask(opt =>
{
opt.SetChannelOptions(settingsManager.Settings.Properties.BackgroundQueueCapacity)
.SetThrowIfUnableToPersist(true)
.RegisterTasksFromAssembly(typeof(AppSettings).Assembly);
})
.AddSqlServerStorage(configuration.GetConnectionString("QueueWorkerSqlStorage")!,
opt =>
{
opt.SchemaName = "EverTask";
opt.AutoApplyMigrations = true;
})
.AddSerilog(opt => opt.ReadFrom.Configuration(configuration, new ConfigurationReaderOptions { SectionName = "EverTaskSerilog" }));
Fluent Service Configuration
EverTaskService
can be configured using a series of fluent methods, allowing a clear and user-friendly way to set up the service. These methods enable precise control over task processing, persistence, and parallel execution. Below are the available configuration methods, along with their default values and types:
SetChannelOptions (Overloaded Methods)
- Type:
Action<BoundedChannelOptions>
orint
- Default: Capacity set to 100,
FullMode
set toBoundedChannelFullMode.Wait
- Functionality: Configures the behavior of the task queue. You can directly specify the queue capacity or provide a
BoundedChannelOptions
object. This defines the maximum number of tasks that can be queued and the behavior when the queue is full.
SetThrowIfUnableToPersist
- Type:
bool
- Default:
true
- Functionality: Determines whether the service should throw an exception if it is unable to persist a task. When enabled, it ensures that task persistence failures are explicitly managed, aiding in data integrity.
SetMaxDegreeOfParallelism
- Type:
int
- Default:
1
- Functionality: Sets the maximum number of tasks that can be executed concurrently. The default sequential execution can be adjusted to enable parallel processing, optimizing task throughput in multi-core systems.
RegisterTasksFromAssembly
- Functionality: Facilitates the registration of task handlers from a single assembly. This is particularly beneficial for applications structured in a modular fashion, enabling easy integration of task handlers.
RegisterTasksFromAssemblies
- Functionality: Allows for the registration of task handlers from multiple assemblies. This approach suits larger applications with distributed task handling logic spread across various modules or libraries.
SQL Server Persistence and Logging
SQL Server Storage
- Default Schema: Creates a new schema named
EverTask
by default. This approach avoids adding clutter to the main data schema. - Migration Table: Places the Entity Framework Core migration table in the custom
EverTask
schema. - Schema Customization: Allows specifying a different schema or using
null
to default to the main schema. - Migration Handling: Option to apply database migrations automatically or handle them manually.
Serilog Integration
- Default Logging: Uses .NET configured
ILogger
by default. - Serilog Option: Enables adding Serilog as a separate logger for EverTask, with customizable options.
- Example Configuration in appsettings.json:
"EverTaskSerilog": { "MinimumLevel": { "Default": "Information", "Override": { "Default": "Information", "Microsoft": "Warning", "Microsoft.AspNetCore.SpaProxy": "Information", "Microsoft.Hosting.Lifetime": "Information", "Microsoft.EntityFrameworkCore.Database.Command": "Information" } }, "WriteTo": [ { "Name": "Console" }, { "Name": "File", "Args": { "path": "Logs/evertask-log-.txt", "rollingInterval": "Day", "fileSizeLimitBytes": 10485760, "retainedFileCountLimit": 10, "shared": true, "flushToDiskInterval": "00:00:01" } } ], "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ], "Properties": { "Application": "CliClub" } }
EverTask and EverTask.Abstractions
EverTask is complemented by the EverTask.Abstractions
package, designed for use in Application projects where additional implementations are not required. This allows separation of concerns, keeping your application layer free from infrastructural code.
In your Infrastructure project, where EverTask is added, specify the assembly (or assemblies) containing IEverTask
requests. This modular approach ensures that the application layer remains clean and focused, while the infrastructure layer handles task execution and management.
Serialization and deserialization of Requests for Persistence
EverTask uses Newtonsoft.Json for serializing and deserializing task requests, due to its robust support for polymorphism and inheritance, features that are limited in System.Text.Json. It is recommended to use simple objects for task requests, preferably primitives or uncomplicated complex objects, to ensure smooth serialization. In cases where EverTask is unable to serialize a request, it will throw an exception during the Dispatch
method. This design choice emphasizes reliability in task persistence, ensuring that only serializable tasks are queued for execution.
Future Developments
Feature | Description |
---|---|
Web Dashboard | Implement a simple web dashboard for monitoring tasks. |
Delayed and Scheduled Tasks | Executing tasks with a delay (specified via TimeSpan) and scheduled tasks (using cron expressions). |
Support for New Storage Options | Considering the inclusion of additional storage options like MySql, Postgres, and various DocumentDBs initially supported by EfCore, with the possibility of expanding to other databases. |
Improving documentation | docs needs more love... |
🌟 Acknowledgements
Special thanks to jbogard for the MediaTr project, providing significant inspiration in the development of key components of this library, especially in the creation of:
I have included comments within these files to acknowledge and reference the specific parts of the MediaTr project that inspired them.
Their approach and architecture have been instrumental in shaping the functionality and design of these elements.
This project includes code from MediatR, which is licensed under the Apache 2.0 License. The full text of the license can be found in the LICENSE file.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- EverTask (>= 1.1.0)
- Microsoft.EntityFrameworkCore (>= 7.0.0)
- Microsoft.EntityFrameworkCore.Relational (>= 7.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
-
net7.0
- EverTask (>= 1.1.0)
- Microsoft.EntityFrameworkCore (>= 7.0.0)
- Microsoft.EntityFrameworkCore.Relational (>= 7.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
-
net8.0
- EverTask (>= 1.1.0)
- Microsoft.EntityFrameworkCore (>= 8.0.0)
- Microsoft.EntityFrameworkCore.Relational (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on EverTask.EfCore:
Package | Downloads |
---|---|
EverTask.SqlServer
Easy background task with persistence for ASP.NET Core |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated | |
---|---|---|---|
1.5.1 | 288 | 11/23/2023 | |
1.5.0 | 157 | 11/21/2023 | |
1.4.1 | 171 | 11/19/2023 | |
1.4.0 | 151 | 11/19/2023 | |
1.3.0 | 160 | 11/19/2023 | |
1.2.0 | 159 | 11/17/2023 | |
1.1.0 | 150 | 11/16/2023 | |
1.0.4-beta | 71 | 11/13/2023 | |
1.0.3-beta | 61 | 11/13/2023 | |
1.0.0 | 147 | 11/15/2023 |