Shaunebu.MAUI.BackgroundTaskManager 1.0.0

Shaunebu.MAUI.BackgroundTaskManager ⏱️

A MAUI library for scheduling foreground and background tasks easily, with CRON support, persistence, and logging. Inspired by Quartz, compatible with Android and iOS.

Features

• Schedule foreground jobs (run while the app is alive) with CRON expressions.

• Schedule persistent background jobs (Android/iOS) using platform APIs (WorkManager / BGTaskScheduler).

• Restore scheduled jobs automatically after app restart using Preferences.

• Optional logging via IBackgroundLogger interface.

• Supports custom jobs implementing IBackgroundJob.

• Cancel jobs dynamically at runtime.

• Cross-platform compatible with .NET MAUI.

Installation

Install via NuGet Package:

dotnet add package Shaunebu.MAUI.BackgroundTaskManager

Or using Visual Studio Package Manager:

Install-Package Shaunebu.MAUI.BackgroundTaskManager

Add the namespace to your code:

using Shaunebu.MAUI.BackgroundTaskManager;

Initialization & Usage

Step 1: Configure Logger

BackgroundTaskManager.Current.Logger = new ConsoleBackgroundLogger();

Step 2: Register Jobs

BackgroundTaskManager.Current.RegisterJob<PushNotificationJob>();

Step 3: Initialize TaskManager (restores jobs from Preferences)

BackgroundTaskManager.Current.Initialize();

Step 4: Schedule a Foreground Job

BackgroundTaskManager.Current.Schedule(
    "SyncJob",
    "0 0/5 * * * ?", // every 5 minutes
    async (ct) =>
    {
        await Task.Delay(500, ct);
        Console.WriteLine("✔ Foreground sync done");
    });

Step 5: Schedule a Persistent Background Job

BackgroundTaskManager.Current.ScheduleInBackground(
    "PushJob",
    "0 0 * * * ?", // every hour
    typeof(PushNotificationJob));

Logger Interface

public interface IBackgroundLogger
{
    void Info(string message);
    void Warn(string message);
    void Error(string message, Exception? ex = null);
}

Example:

public class ConsoleBackgroundLogger : IBackgroundLogger
{
    public void Info(string message) => Debug.WriteLine($"[INFO] {message}");
    public void Warn(string message) => Debug.WriteLine($"[WARN] {message}");
    public void Error(string message, Exception? ex = null) =>
        Debug.WriteLine($"[ERROR] {message} {ex?.Message}");
}

Job Interface

public interface IBackgroundJob
{
    Task ExecuteAsync(CancellationToken cancellationToken);
}

Example:

public class PushNotificationJob : IBackgroundJob
{
    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        await Task.Delay(1000, cancellationToken); // simulate work
        Debug.WriteLine("🔔 PushNotificationJob executed.");
    }
}

App.xaml.cs Example

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
 
        // 1️ Configure global logger
        BackgroundTaskManager.Current.Logger = new ConsoleBackgroundLogger();
 
        // 2️ Register available background jobs
        BackgroundTaskManager.Current.RegisterJob<PushNotificationJob>();
 
        // 3️ Register foreground job with actual callback
        BackgroundTaskManager.Current.Schedule(
            "SyncJob",
            "0 0/5 * * * ?", // every 5 minutes
            async (ct) =>
            {
                await Task.Delay(500, ct); // simulate work
                Console.WriteLine("✔ Foreground sync done");
            });
 
        // 4️ Initialize TaskManager (restores jobs from Preferences)
        // Foreground jobs restored will automatically use the registered callback above
        BackgroundTaskManager.Current.Initialize();
 
        // 5️ Register persistent background job (approximately every hour)
        BackgroundTaskManager.Current.ScheduleInBackground(
            "PushJob",
            "0 0 * * * ?", // every hour
            typeof(PushNotificationJob));
    }
 
    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
}

Flow Diagram

::: mermaid flowchart TD; A[App Starts] --> B[Initialize BackgroundTaskManager] B --> C[Load Jobs from Preferences] B --> D[Register New Jobs] C --> E[Foreground Job Scheduler] D --> E C --> F[Background Job Scheduler OS] D --> F E --> G[Execute Foreground Jobs when App is Alive] F --> H[Execute Background Jobs Persistently] G --> I[Logging via IBackgroundLogger] H --> I I --> J[Update Preferences with Job State] :::

• Foreground Jobs: Run only while the app is alive.

• Background Jobs: Persisted by OS, can run even if the app is terminated.

• Preferences: Keep track of jobs and restore them after restart.

• Logger: Optional, but recommended for debugging and monitoring.

Platform Configuration

Android

• Minimum API 23 required for WorkManager.

• Add the following permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

• WorkManager handles periodic background execution approximately (CRON expressions are converted to minimum intervals, usually >=15 minutes).

iOS

• Add Background Modes in Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>remote-notification</string>
</array>

• iOS background tasks cannot run exactly at CRON intervals. The OS decides the best time.

Platform Limitations & Notes

• CRON approximation:

  • On Android, minimum interval for periodic work is 15 minutes. CRON schedules below this are rounded up.

  • On iOS, background tasks are scheduled by the OS; exact timing cannot be guaranteed.

• Foreground jobs run only while the app is alive. Use Schedule for these.

• Persistent background jobs are registered via ScheduleInBackground. Use this for tasks that must survive app termination.

• Preferences storage is used to restore jobs on app restart.

• Always implement CancellationToken support in your job logic for safe termination.

• Logging is optional but recommended for monitoring job execution.

Advanced Tips

• Update a job’s CRON schedule: Cancel the job, then Schedule again.

• Cancel a job anytime:

BackgroundTaskManager.Current.Cancel("JobId");

• Combine foreground and background jobs for hybrid scheduling.

• Works seamlessly with CancellationToken to safely stop tasks.