Advanced Background Tasks

🚀 Advanced Background Tasks in ASP.NET

The Airport Control Tower Story

Imagine you run a busy airport. Planes arrive, passengers check in, bags get loaded, and flights depart. But here’s the thing—when the airport needs to close for the night, you can’t just flip a switch and leave planes mid-air!

You need:

1. Someone watching when to start closing (IHostApplicationLifetime)
2. A way to land all planes safely before shutdown (Graceful shutdown)
3. An organized line for passengers waiting to board (Background queue)
4. Fast conveyor belts moving bags to the right planes (Channel-based processing)

That’s exactly what Advanced Background Tasks do in ASP.NET! Let’s explore each one.

🎯 What Are Background Tasks?

Background tasks are jobs that run behind the scenes while your app handles normal requests.

Simple Example:

• You order pizza online 🍕
• The website says “Order received!”
• But BEHIND the scenes, someone is making your pizza, packaging it, calling the driver…

That’s background work! The website didn’t make you wait for all that.

1️⃣ IHostApplicationLifetime

What Is It?

Think of IHostApplicationLifetime as the airport’s announcement system. It tells everyone:

• 📢 “The airport is NOW OPEN!” (ApplicationStarted)
• 📢 “Attention! We’re STARTING to close!” (ApplicationStopping)
• 📢 “Airport is CLOSED. Everyone out!” (ApplicationStopped)

Why Do We Need It?

Your background tasks need to know when the app is:

• Starting up (time to prepare!)
• Shutting down (time to finish and clean up!)

The Three Signals

public class MyService : IHostedService
{
    private readonly IHostApplicationLifetime _lifetime;

    public MyService(IHostApplicationLifetime lifetime)
    {
        _lifetime = lifetime;
    }

    public Task StartAsync(CancellationToken token)
    {
        // Register for notifications
        _lifetime.ApplicationStarted.Register(() =>
        {
            Console.WriteLine("App started!");
        });

        _lifetime.ApplicationStopping.Register(() =>
        {
            Console.WriteLine("Stopping soon...");
        });

        _lifetime.ApplicationStopped.Register(() =>
        {
            Console.WriteLine("Goodbye!");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken token)
    {
        return Task.CompletedTask;
    }
}

Real Life Example

graph TD
    A["App Starts"] --> B["ApplicationStarted fires"]
    B --> C["Background tasks run"]
    C --> D["Someone presses Ctrl+C"]
    D --> E["ApplicationStopping fires"]
    E --> F["Tasks finish their work"]
    F --> G["ApplicationStopped fires"]
    G --> H["App exits cleanly"]

2️⃣ Graceful Shutdown

The Problem Without It

Imagine you’re writing an important email. Suddenly, someone pulls the plug on your computer. 😱

• Email = LOST
• Work = GONE
• You = ANGRY

That’s what happens when apps shut down without grace.

What Is Graceful Shutdown?

It’s like saying: “Hey everyone, we’re closing in 5 minutes. Please finish what you’re doing!”

Instead of just stopping, your app:

1. Signals that shutdown is starting
2. Waits for tasks to complete
3. Then closes cleanly

How It Works

public class EmailSenderService : BackgroundService
{
    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Check if we should stop
            if (stoppingToken.IsCancellationRequested)
            {
                // Finish current email first!
                await FinishCurrentEmail();
                break;
            }

            await SendNextEmail();
            await Task.Delay(1000, stoppingToken);
        }

        // Clean up when done
        Console.WriteLine("All emails sent. Goodbye!");
    }
}

The Magic: CancellationToken

The CancellationToken is like a gentle tap on the shoulder saying “please stop when you can.”

graph TD
    A["Shutdown requested"] --> B{Task checking token}
    B -->|Token cancelled| C["Finish current work"]
    C --> D["Clean up resources"]
    D --> E["Exit gracefully"]
    B -->|Token active| F["Continue working"]
    F --> B

Setting Shutdown Timeout

By default, ASP.NET waits 30 seconds for tasks to finish. You can change this:

builder.Services.Configure<HostOptions>(options =>
{
    // Wait up to 60 seconds for graceful shutdown
    options.ShutdownTimeout = TimeSpan.FromSeconds(60);
});

3️⃣ Background Queue

The Coffee Shop Line 🏪

Ever been to a busy coffee shop? You:

1. Place your order at the counter
2. Get a number
3. Wait while they make drinks in order

That’s a queue! First come, first served.

What Is a Background Queue?

It’s a waiting line for tasks. Jobs go in one end, and workers process them one by one.

Building a Simple Queue

Step 1: Define the Queue Interface

public interface IBackgroundTaskQueue
{
    // Add a task to the queue
    void QueueBackgroundWork(
        Func<CancellationToken, Task> workItem);

    // Get the next task to process
    Task<Func<CancellationToken, Task>> DequeueAsync(
        CancellationToken cancellationToken);
}

Step 2: Implement the Queue

public class BackgroundTaskQueue : IBackgroundTaskQueue
{
    private ConcurrentQueue<Func<CancellationToken, Task>>
        _workItems = new();
    private SemaphoreSlim _signal = new(0);

    public void QueueBackgroundWork(
        Func<CancellationToken, Task> workItem)
    {
        _workItems.Enqueue(workItem);
        _signal.Release(); // Signal: new item!
    }

    public async Task<Func<CancellationToken, Task>>
        DequeueAsync(CancellationToken token)
    {
        await _signal.WaitAsync(token); // Wait for item
        _workItems.TryDequeue(out var workItem);
        return workItem!;
    }
}

Step 3: Create a Worker Service

public class QueuedHostedService : BackgroundService
{
    private readonly IBackgroundTaskQueue _queue;

    public QueuedHostedService(IBackgroundTaskQueue queue)
    {
        _queue = queue;
    }

    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var workItem = await _queue
                .DequeueAsync(stoppingToken);

            await workItem(stoppingToken);
        }
    }
}

Using the Queue

// In your controller
[HttpPost("send-report")]
public IActionResult SendReport()
{
    _queue.QueueBackgroundWork(async token =>
    {
        // This runs in background!
        await GenerateReport();
        await EmailReport();
    });

    return Ok("Report queued!");
}

graph LR
    A["Request 1"] --> Q["Queue"]
    B["Request 2"] --> Q
    C["Request 3"] --> Q
    Q --> W["Worker"]
    W --> D["Process 1"]
    D --> E["Process 2"]
    E --> F["Process 3"]

4️⃣ Channel-Based Processing

The Supercharged Conveyor Belt 🏭

Remember the queue? It’s great, but what if you have:

• 1000 orders per second?
• Multiple workers ready to help?

You need something FASTER. Enter Channels!

What Are Channels?

Channels are like super-fast conveyor belts built into .NET. They’re:

• ⚡ Very fast (made for high performance)
• 🔄 Thread-safe (multiple workers, no problems)
• 📦 Bounded or unbounded (limit how much can queue up)

Creating a Channel

// Bounded channel: max 100 items
var channel = Channel.CreateBounded<string>(
    new BoundedChannelOptions(100)
    {
        FullMode = BoundedChannelFullMode.Wait
    });

// Unbounded channel: no limit
var channel = Channel.CreateUnbounded<string>();

Writing to a Channel (Producer)

public class OrderProducer
{
    private readonly Channel<Order> _channel;

    public OrderProducer(Channel<Order> channel)
    {
        _channel = channel;
    }

    public async Task AddOrderAsync(Order order)
    {
        await _channel.Writer.WriteAsync(order);
        Console.WriteLine(quot;Order {order.Id} queued!");
    }
}

Reading from a Channel (Consumer)

public class OrderProcessor : BackgroundService
{
    private readonly Channel<Order> _channel;

    public OrderProcessor(Channel<Order> channel)
    {
        _channel = channel;
    }

    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        await foreach (var order in
            _channel.Reader.ReadAllAsync(stoppingToken))
        {
            await ProcessOrder(order);
        }
    }
}

Multiple Consumers (Super Fast!)

// Register multiple consumers!
services.AddHostedService<OrderProcessor>();
services.AddHostedService<OrderProcessor>();
services.AddHostedService<OrderProcessor>();
// 3 workers processing orders in parallel!

graph TD
    A["Order 1"] --> C["Channel"]
    B["Order 2"] --> C
    D["Order 3"] --> C
    C --> W1["Worker 1"]
    C --> W2["Worker 2"]
    C --> W3["Worker 3"]
    W1 --> P1["Processed!"]
    W2 --> P2["Processed!"]
    W3 --> P3["Processed!"]

Complete Channel Example

// Setup in Program.cs
var channel = Channel.CreateBounded<EmailJob>(100);
builder.Services.AddSingleton(channel);
builder.Services.AddHostedService<EmailProcessor>();

// Producer (in controller)
[HttpPost("send-email")]
public async Task<IActionResult> SendEmail(EmailRequest req)
{
    await _channel.Writer.WriteAsync(new EmailJob
    {
        To = req.To,
        Subject = req.Subject,
        Body = req.Body
    });

    return Ok("Email queued!");
}

// Consumer (background service)
public class EmailProcessor : BackgroundService
{
    private readonly Channel<EmailJob> _channel;

    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        await foreach (var job in
            _channel.Reader.ReadAllAsync(stoppingToken))
        {
            await SendEmail(job);
        }
    }
}

🔗 Putting It All Together

Here’s how all four concepts work together:

graph TD
    A["App Starts"] --> B["IHostApplicationLifetime signals START"]
    B --> C["Background Services Begin"]
    C --> D["Queue receives work items"]
    D --> E["Channel processes items fast"]
    E --> F{Shutdown Signal?}
    F -->|No| D
    F -->|Yes| G["Graceful Shutdown begins"]
    G --> H["Finish current items"]
    H --> I["IHostApplicationLifetime signals STOP"]
    I --> J["App Exits Cleanly"]

Quick Comparison

🎓 Key Takeaways

1. IHostApplicationLifetime = Your app’s announcement system
2. Graceful Shutdown = Finish work before leaving
3. Background Queue = Simple waiting line for tasks
4. Channels = Super-fast conveyor belt for high-volume work

Remember the Airport! 🛫

• Control Tower (IHostApplicationLifetime) announces open/close
• Safe Landing (Graceful Shutdown) lands all planes before closing
• Check-in Line (Background Queue) organizes passengers
• Baggage Conveyors (Channels) move bags super fast

Now you can build background tasks that are fast, safe, and reliable!

💡 Pro Tips

🚀 Use Channels when you have high throughput (1000s of items)

🛡️ Always handle CancellationToken for graceful shutdown

📊 Use Bounded Channels to prevent memory overflow

⚡ Multiple workers can read from one channel for parallel processing

You’ve got this! Background tasks are just like running a well-organized airport. Now go build something awesome! 🎉