ASP.NET Core Diagnostic Scenarios

When using System.Threading.Timer, avoid using async void for the callback, as exceptions can crash the process. Also, avoid blocking the callback with .Result or .Wait(), which causes thread-pool starvation.

For .NET 6 and later, prefer using PeriodicTimer in a dedicated background loop. This allows you to await the timer ticks and handle exceptions gracefully within the loop.

// Recommended for .NET 6+
public class Pinger : IDisposable
{
    private readonly PeriodicTimer _timer;
    private readonly HttpClient _client;

    public Pinger(HttpClient client)
    {
        _client = client;
        _timer = new PeriodicTimer(TimeSpan.FromSeconds(1));
        _ = Task.Run(DoAsyncPings);
    }

    public void Dispose() => _timer.Dispose();

    private async Task DoAsyncPings()
    {
        while (await _timer.WaitForNextTickAsync())
        {
            // TODO: Handle exceptions
            await _client.GetAsync("http://mybackend/api/ping");
        }
    }
}

When building libraries that adapt non-awaitable APIs to be awaitable using TaskCompletionSource<T>, always initialize the source with TaskCreationOptions.RunContinuationsAsynchronously.

By default, continuations run inline on the thread that calls TrySetResult (or similar). This can cause the calling code to resume directly on your library's internal thread, leading to deadlocks, thread-pool starvation, or state corruption. Using this flag ensures the continuation is dispatched to the thread pool instead.

// GOOD: This example uses TaskCreationOptions.RunContinuationsAsynchronously when creating the TaskCompletionSource<T>.
public Task<int> DoSomethingAsync()
{
    var tcs = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
    
    var operation = new LegacyAsyncOperation();
    operation.Completed += result =>
    {
        // Code awaiting on this task will resume on a different thread-pool thread
        tcs.SetResult(result);
    };
    
    return tcs.Task;
}

HttpContext is not thread-safe. Accessing it from multiple threads in parallel can cause corruption, hangs, crashes, or data corruption. If you need to use data from the HttpContext (like Request.Path) inside parallel tasks or background operations, copy the required data into local variables before starting the parallel work.

public class AsyncController : Controller
{
    [HttpGet("/search")]
    public async Task<SearchResults> Get(string query)
    {
        // Copy data from HttpContext before starting parallel tasks
        string path = HttpContext.Request.Path;
        var query1 = SearchAsync(SearchEngine.Google, query, path);
        var query2 = SearchAsync(SearchEngine.Bing, query, path);
        var query3 = SearchAsync(SearchEngine.DuckDuckGo, query, path);

        await Task.WhenAll(query1, query2, query3);
        
        var results1 = await query1;
        var results2 = await query2;
        var results3 = await query3;

        return SearchResults.Combine(results1, results2, results3);
    }

    private async Task<SearchResults> SearchAsync(SearchEngine engine, string query, string path)
    {
        var searchResults = SearchResults.Empty;
        try
        {
            _logger.LogInformation("Starting search query from {path}.", path);
            searchResults = await _searchService.SearchAsync(engine, query);
            _logger.LogInformation("Finishing search query from {path}.", path);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed query from {path}", path);
        }

        return searchResults;
    }
}

While directly returning a Task is slightly more performant because it avoids the async state machine, it is generally better to use the async/await keywords. Using async/await provides several benefits:

• Exception Normalization: Asynchronous and synchronous exceptions are always normalized to be asynchronous.
• Easier Debugging: Diagnostics and debugging of hangs are more straightforward.
• Safety: Exceptions are automatically wrapped in the returned Task rather than surprising the caller.
• AsyncLocals: Prevents AsyncLocal values from leaking out of the method.
• Maintainability: Makes it easier to add logic like using blocks later.

// BAD: Directly returning the Task
public Task<int> DoSomethingAsync()
{
    return CallDependencyAsync();
}

// GOOD: Using async/await
public async Task<int> DoSomethingAsync()
{
    return await CallDependencyAsync();
}

When caching the results of asynchronous operations in a ConcurrentDictionary, do not use .Result inside GetOrAdd, as this causes thread-pool starvation.

Instead, store the Task<T> itself. To prevent the same expensive operation from being triggered multiple times if GetOrAdd runs the delegate concurrently, use an AsyncLazy<T> pattern.

public class PersonController : Controller
{
   private AppDbContext _db;
   // Use AsyncLazy to ensure the delegate runs only once
   private static ConcurrentDictionary<int, AsyncLazy<Person>> _cache = new ConcurrentDictionary<int, AsyncLazy<Person>>();
   
   public PersonController(AppDbContext db) => _db = db;
   
   public async Task<IActionResult> Get(int id)
   {
       var person = await _cache.GetOrAdd(id, (key) => new AsyncLazy<Person>(() => _db.People.FindAsync(key))).Value;
       return Ok(person);
   }
   
   private class AsyncLazy<T> : Lazy<Task<T>>
   {
      public AsyncLazy(Func<Task<T>> valueFactory) : base(valueFactory) { }
   }
}