Skip to main content
Version: Next

Background Tasks and Scheduled Jobs

Files referenced in this document

Table of Contents​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction​

This document details the design and implementation of the background asynchronous task processing mechanism in the CMS plugin, covering two main modes: periodic tasks based on BackgroundWorker and scheduled jobs based on Hangfire. It focuses on how MyPluginNameWorker inherits from AsyncPeriodicBackgroundWorkerBase to implement periodic execution, and how MyPluginNameJob is scheduled via the background job system. It also describes task parameter serialization, registration mechanisms, execution contexts, retry strategies, monitoring methods, and provides performance tuning suggestions and common issue troubleshooting.

Project Structure​

The plugin adopts a modular layered architecture, with background task-related code concentrated in specific directories, ensuring clear responsibilities and easy maintenance.

Diagram sources

Section sources

Core Components​

The system implements two background task modes: MyPluginNameWorker for periodic lightweight tasks, and MyPluginNameJob for schedulable, persistent background jobs. The former is registered and run periodically via IBackgroundWorkerManager, while the latter is registered via AbpBackgroundJobOptions, supporting parameter passing and failure retries.

Section sources

Architecture Overview​

The system implements asynchronous processing via the ABP framework's background task mechanism, divided into periodic workers and persistent jobs. Periodic tasks are driven by AsyncPeriodicBackgroundWorkerBase triggered by a timer; persistent jobs are implemented by BackgroundJob<TArgs> and scheduled by the background job system.

Diagram sources

Detailed Component Analysis​

MyPluginNameWorker Analysis​

MyPluginNameWorker is a periodic background worker inheriting from AsyncPeriodicBackgroundWorkerBase, responsible for executing timed business logic.

Startup and Configuration​

This worker is registered via IBackgroundWorkerManager.AddAsync during the CMSPluginEntry.AfterReadyAsync phase and executes automatically according to the configured period after startup. The default period is 300 seconds (5 minutes), running immediately on first startup (RunOnStart = true).

Diagram sources

Execution Logic​

The DoWorkAsync method is the core execution body, obtaining the service provider via PeriodicBackgroundWorkerContext to access IProjectAccessor for current project information. If the project is valid, business logic (like OEE calculation annotated in the example) can be executed.

Exception Handling​

The framework automatically captures exceptions in DoWorkAsync and logs them, preventing worker termination. Custom exception handling can be added via try-catch blocks within the method.

Section sources

MyPluginNameJob Analysis​

MyPluginNameJob is a persistent task based on the ABP background job system, supporting parameter passing, failure retry, and persistent storage.

Task Scheduling​

This job is registered in CMSPluginModule.ConfigureServices via AbpBackgroundJobOptions and can be enqueued for execution via IBackgroundJobManager.EnqueueAsync.

Diagram sources

Parameter Passing Mechanism​

MyPluginNameArgs serves as the job argument class, containing Subject and Body string properties. This object is serialized for storage upon enqueueing and deserialized into the Execute method during execution, supporting cross-process and cross-machine passing.

Transactions and Data Access​

The job opens an independent transaction (requiresNew: true) internally via IUnitOfWorkManager to ensure operation atomicity. Data access can be performed via IMyEntityNameRepository; explicit SaveChangesAsync calls are needed for persistent changes.

Section sources

Dependency Analysis​

Dependencies between system components are clear, achieving loose coupling via dependency injection.

Diagram sources

Performance Considerations​

  • Periodic Task Frequency: MyPluginNameWorker defaults to every 300 seconds. Adjust Timer.Period based on business needs to avoid system overload.
  • Job Concurrency Control: MyPluginNameJob uses independent transactions to avoid holding connections for long periods. Batch processing is recommended for time-consuming operations.
  • Resource Release: All services are managed by the DI container, no manual release required.
  • Log Level: Use Information or higher in production to avoid Debug logs impacting performance.

Troubleshooting Guide​

Task Not Executing​

  • Check if MyPluginNameWorker is successfully registered in CMSPluginEntry.AfterReadyAsync.
  • Confirm MyPluginNameJob type is registered via AddJob<MyPluginNameJob> in CMSPluginModule.
  • Check logs for errors related to IBackgroundWorkerManager or IBackgroundJobManager.

Task Accumulation​

  • Check if database connections are normal and job tables (like BackgroundJobs) are accessible.
  • Confirm Hangfire service (or corresponding background job provider) is running.
  • Adjust job processing thread count or optimize single job execution time.

Deadlock Prevention​

  • Avoid long synchronous operations in MyPluginNameWorker.DoWorkAsync.
  • Use requiresNew: true in MyPluginNameJob to ensure independent transactions, reducing lock contention.
  • Use non-blocking reads (like ReadUncommitted) for database queries where possible.

Parameter Serialization Failure​

  • Ensure MyPluginNameArgs and its properties are public with get/set accessors.
  • Avoid including delegates, events, or non-serializable fields in argument classes.

Section sources

Conclusion​

The system implements a flexible background task processing mechanism via BackgroundWorker and Hangfire Job modes. MyPluginNameWorker is suitable for periodic, lightweight tasks, while MyPluginNameJob fits complex jobs requiring persistence, parameters, and retries. Both are integrated via the ABP framework, offering good maintainability and extensibility. Reasonable configuration of execution frequency, transaction boundaries, and exception handling strategies ensures stable and efficient system operation.

Last updated on