A Complete Guide - ASP.NET Web API Background Jobs with Hosted Services

Prerequisites

• .NET SDK installed (version 5.0 or later).
• An IDE like Visual Studio or Visual Studio Code.

Step 1: Create a New ASP.NET Core Web API Project

Using Visual Studio

1. Open Visual Studio.
2. Select Create a new project.
3. Choose ASP.NET Core Web API from the list of templates.
4. Click Next.
5. Enter a project name and location, then click Create.
6. In the next dialog, ensure .NET 5.0 (or later) is selected, and click Create.

Using Visual Studio Code / Command Line

1. Open your terminal.
2. Run:

   dotnet new webapi -n BackgroundJobWebApi
   cd BackgroundJobWebApi
   

Step 2: Add a Hosted Service

A hosted service in ASP.NET Core is a class that implements IHostedService. This interface provides two methods, StartAsync and StopAsync, which are used when the service is started and stopped, respectively.

1. Create a folder named Services inside your project.
2. Inside the Services folder, create a new class named BackgroundJobService.cs.
3. Implement BackgroundJobService to inherit from BackgroundService, which is a base class that implements IHostedService and IDisposable.

// Services/BackgroundJobService.cs
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks; namespace BackgroundJobWebApi.Services
{ public class BackgroundJobService : BackgroundService { private readonly ILogger<BackgroundJobService> _logger; public BackgroundJobService(ILogger<BackgroundJobService> logger) { _logger = logger; } protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { // Your periodic task logic goes here _logger.LogInformation("Periodic Task running at: {time}", DateTimeOffset.Now); await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken); } } }
}

Step 3: Register the Hosted Service

To use the hosted service, we need to register it in the DI container. Open the Program.cs or Startup.cs file and add the following:

For .NET 6 and above, modify the Program.cs file as follows:

// Program.cs
var builder = WebApplication.CreateBuilder(args); // Add services to the container.
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(); // Register our hosted service
builder.Services.AddHostedService<BackgroundJobService>(); var app = builder.Build(); // Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{ app.UseSwagger(); app.UseSwaggerUI();
} app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();

For .NET 5, modify the Startup.cs file as follows:

// Startup.cs
public class Startup
{ public void ConfigureServices(IServiceCollection services) { services.AddControllers(); // Register our hosted service services.AddHostedService<BackgroundJobService>(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseHttpsRedirection(); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
}

Step 4: Test the Hosted Service

1. Run the application using Visual Studio or Visual Studio Code by executing:

   dotnet run
   

2. Check the console outputs for log information indicating that the periodic task is running every 5 seconds:

   info: BackgroundJobWebApi.Services.BackgroundJobService[0] Periodic Task running at: 1/1/2023 12:00:05 PM +00:00
   

Step 5: Implement a More Complex Background Job

Let's implement a more complex hosted service that fetches data from an external API and logs it periodically.

1. First, let's install a package to send HTTP requests:

   dotnet add package System.Net.Http.Json
   

2. Create a new interface named IBackgroundTaskQueue.cs in the Services folder:

// Services/IBackgroundTaskQueue.cs
using System.Collections.Concurrent; namespace BackgroundJobWebApi.Services
{ public interface IBackgroundTaskQueue { void EnqueueWorkItem(Func<CancellationToken, ValueTask> workItem); ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync(CancellationToken cancellationToken); } public class BackgroundTaskQueue : IBackgroundTaskQueue { private ConcurrentQueue<Func<CancellationToken, ValueTask>> _workItems = new ConcurrentQueue<Func<CancellationToken, ValueTask>>(); private SemaphoreSlim _signal = new SemaphoreSlim(0); public void EnqueueWorkItem(Func<CancellationToken, ValueTask> workItem) { if (workItem == null) { throw new ArgumentNullException(nameof(workItem)); } _workItems.Enqueue(workItem); _signal.Release(); } public async ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync( CancellationToken cancellationToken) { await _signal.WaitAsync(cancellationToken); _workItems.TryDequeue(out var workItem); return workItem; } }
}

3. Create a new class named QueuedHostedService.cs for the actual periodic execution:

// Services/QueuedHostedService.cs
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;
using System.Threading;
using System.Threading.Tasks; namespace BackgroundJobWebApi.Services
{ public class QueuedHostedService : BackgroundService { private readonly IServiceScopeFactory _serviceScopeFactory; private readonly IBackgroundTaskQueue _taskQueue; public QueuedHostedService(IBackgroundTaskQueue taskQueue, IServiceScopeFactory serviceScopeFactory) { _taskQueue = taskQueue; _serviceScopeFactory = serviceScopeFactory; } protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { // Get the next worker item from the queue var workItem = await _taskQueue.DequeueAsync(stoppingToken); // Log start of work using (var scope = _serviceScopeFactory.CreateScope()) { var _logger = scope.ServiceProvider.GetRequiredService<ILogger<QueuedHostedService>>(); var fetchDataService = scope.ServiceProvider.GetRequiredService<IFetchDataService>(); _logger.LogInformation($"QueuedHostedService received a job to run at {DateTimeOffset.Now}"); // Execute the worker item await workItem(stoppingToken); } } } } public interface IFetchDataService { Task FetchDataAsync(); } public class FetchDataService : IFetchDataService { private readonly ILogger<FetchDataService> _logger; private readonly HttpClient _httpClient; public FetchDataService(ILogger<FetchDataService> logger, HttpClient httpClient) { _logger = logger; _httpClient = httpClient; } public async Task FetchDataAsync() { try { var response = await _httpClient.GetStringAsync(" _logger.LogInformation($"Fetched data successfully at {DateTimeOffset.Now}: Size={response.Length}"); } catch (Exception ex) { _logger.LogError(ex, $"Error occurred at: {DateTimeOffset.Now}"); } } }
}

4. Modify Program.cs or Startup.cs to schedule tasks periodically and use HttpClient.

For .NET 6 and above, modify the Program.cs file as follows:

// Program.cs
var builder = WebApplication.CreateBuilder(args); // Add services to the container.
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(); // Register services
builder.Services.AddHttpClient();
builder.Services.AddSingleton<IBackgroundTaskQueue, BackgroundTaskQueue>();
builder.Services.AddHostedService<QueuedHostedService>();
builder.Services.AddSingleton<IFetchDataService, FetchDataService>(); using var app = builder.Build(); // Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{ app.UseSwagger(); app.UseSwaggerUI();
} app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); var scopeFactory = app.Services.GetService<IServiceScopeFactory>(); DoWork(scopeFactory).GetAwaiter().GetResult(); await app.RunAsync(); static async Task DoWork(IServiceScopeFactory scopeFactory)
{ using IServiceScope scope = scopeFactory.CreateScope(); var taskQueue = scope.ServiceProvider.GetRequiredService<IBackgroundTaskQueue>(); while (true) { taskQueue.EnqueueWorkItem(async token => { await scope.ServiceProvider.GetRequiredService<IFetchDataService>().FetchDataAsync(); }); await Task.Delay(TimeSpan.FromSeconds(10)); // Adjust delay time as needed }
}

For .NET 5, modify the Startup.cs file as follows:

// Startup.cs
public class Startup
{ public IConfiguration Configuration { get; } public Startup(IConfiguration configuration) { Configuration = configuration; } public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services.AddHttpClient(); services.AddSingleton<IBackgroundTaskQueue, BackgroundTaskQueue>(); services.AddHostedService<QueuedHostedService>(); services.AddSingleton<IFetchDataService, FetchDataService>(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseHttpsRedirection(); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); using (var serviceScope = app.ApplicationServices.CreateScope()) { var taskQueue = serviceScope.ServiceProvider.GetRequiredService<IBackgroundTaskQueue>(); DoWork(taskQueue, serviceScope.ServiceProvider).GetAwaiter().GetResult(); } } static async Task DoWork(IBackgroundTaskQueue taskQueue, IServiceProvider serviceProvider) { while (true) { taskQueue.EnqueueWorkItem(async token => { var fetchDataService = serviceProvider.GetRequiredService<IFetchDataService>(); await fetchDataService.FetchDataAsync(); }); await Task.Delay(TimeSpan.FromSeconds(10)); // Adjust delay time as needed } }
}

Step 6: Test the Enhanced Hosted Service

1. Run the application again.
2. Check the console for log messages indicating data fetching operations.

You should see output similar to:

info: BackgroundJobWebApi.Services.QueuedHostedService[0] QueuedHostedService received a job to run at 01/01/2023 12:20:00 PM +00:00
info: BackgroundJobWebApi.Services.FetchDataService[0] Fetched data successfully at 01/01/2023 12:20:00 PM +00:00: Size=39678

Conclusion

In this example, we created an ASP.NET Core Web API and implemented a background job using a hosted service. The background job fetches data from an external API periodically and logs it. This setup can be expanded to include more complex background operations or different types of background tasks as needed.