dotnet-csharp-async-patterns

name	dotnet-csharp-async-patterns
description	Writing async/await code. Task patterns, ConfigureAwait, cancellation, and common agent pitfalls.
license	MIT
targets	["*"]
category	fundamentals
subcategory	language-patterns
tags	["csharp","dotnet","skill","language-patterns","async"]
version	1.0.0
author	dotnet-agent-harness
invocable	true
related_skills	["dotnet-csharp-coding-standards","dotnet-csharp-concurrency-patterns","dotnet-csharp-dependency-injection"]
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for csharp tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

dotnet-csharp-async-patterns

Async/await best practices for .NET applications. Covers correct task usage, cancellation propagation, and the most common mistakes AI agents make when generating async code.

Scope

• Async/await best practices and Task patterns
• ConfigureAwait usage and SynchronizationContext
• Cancellation token propagation
• Common async agent pitfalls and fixes

Out of scope

• Thread synchronization primitives (lock, SemaphoreSlim) -- see [skill:dotnet-csharp-concurrency-patterns]
• Channel producer/consumer patterns -- see [skill:dotnet-channels]
• BackgroundService registration and lifecycle -- see [skill:dotnet-background-services]

Cross-references: [skill:dotnet-csharp-dependency-injection] for IHostedService/BackgroundService registration, [skill:dotnet-csharp-coding-standards] for Async suffix naming, [skill:dotnet-csharp-modern-patterns] for language-level features.

---

Core Rules

Always Async All the Way

Every method in the async call chain must be async and awaited. Mixing sync and async causes deadlocks or thread pool starvation.

// Correct: async all the way
public async Task<Order> GetOrderAsync(int id, CancellationToken ct = default)
{
    var order = await _repo.GetByIdAsync(id, ct);
    return order;
}

// WRONG: blocking on async -- causes deadlocks in ASP.NET and UI contexts
public Order GetOrder(int id)
{
    return _repo.GetByIdAsync(id).Result; // DEADLOCK RISK
}

```text

### Prefer `Task` and `ValueTask`

Return `Task` or `Task<T>` by default. Use `ValueTask<T>`  the method frequently completes  () to avoid `Task` allocation.

```csharp


 ValueTask<User?> ()
{
     (_cache.TryGetValue(id,   user))
    {
         ValueTask.FromResult<User?>(user);
    }

     LoadUserAsync(id, ct);
}

  ValueTask<User?> LoadUserAsync( id, CancellationToken ct)
{
     user =  _repo.GetByIdAsync(id, ct);
     (user   )
    {
        _cache[id] = user;
    }

     user;
}

```text

**ValueTask rules:**

- Never `` a `ValueTask` more than once
- Never use `.Result`  `.GetAwaiter().GetResult()`  an incomplete `ValueTask`
- If you need to  multiple times  pass it around, convert  `.AsTask()`

---



These are the most common  mistakes AI agents make  generating C



```csharp


 result = GetDataAsync().Result;
GetDataAsync().Wait();
 result = GetDataAsync().GetAwaiter().GetResult();


 result =  GetDataAsync();

```text

The only safe place  `.GetAwaiter().GetResult()`   `Main()` pre-C

{
     _repo.SaveAsync(order);
}



{
     _repo.SaveAsync(order);
}

```text

The **only** valid use of ` ` 
{
     bytes =  File.ReadAllBytesAsync(path, ct).ConfigureAwait();
     bytes;
}



{
     order =  _service.GetOrderAsync(id, ct);
     Ok(order);
}

```text



```csharp


_ = SendEmailAsync(order);


 _backgroundQueue.EnqueueAsync(ct => SendEmailAsync(order, ct));

```text

If fire--forget  truly necessary, at minimum log the exception:

```csharp

_ = Task.Run( () =>
{
    
    {
         SendEmailAsync(order);
    }
     (Exception ex)
    {
        _logger.LogError(ex, , order.Id);
    }
});

```text



Always accept  forward `CancellationToken`. Never silently drop it.

```csharp


  Task<List<Order>> GetAllAsync(CancellationToken ct = )
{
      _dbContext.Orders.ToListAsync(); 
}


  Task<List<Order>> GetAllAsync(CancellationToken ct = )
{
      _dbContext.Orders.ToListAsync(ct);
}

```text

---





Combine external cancellation  a timeout:

```
{
      cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
    cts.CancelAfter(TimeSpan.FromSeconds());

      DoWorkAsync(cts.Token);
}

```text



```
{
     ( item  items)
    {
        ct.ThrowIfCancellationRequested();
         ProcessItemAsync(item, ct);
    }
}

```text

---





```
{
     ordersTask = _orderService.GetRecentAsync(userId, ct);
     profileTask = _profileService.GetAsync(userId, ct);
     statsTask = _statsService.GetAsync(userId, ct);

     Task.WhenAll(ordersTask, profileTask, statsTask);

      Dashboard(ordersTask.Result, profileTask.Result, statsTask.Result);
}

```text



```csharp

 Parallel.ForEachAsync(items,  ParallelOptions
{
    MaxDegreeOfParallelism = ,
    CancellationToken = ct
},  (item, token) =>
{
     ProcessItemAsync(item, token);
});

```text

---



Use `IAsyncEnumerable<T>`  streaming results instead of buffering entire collections:

```
{
      ( order  _dbContext.Orders.AsAsyncEnumerable().WithCancellation(ct))
    {
          order;
    }
}

```text

---



For background processing, use `BackgroundService` ( `IHostedService`) instead of `Task.Run`  fire--forget
patterns. See [skill:dotnet-csharp-dependency-injection]  registration patterns.

```
{
    
    {
         (!stoppingToken.IsCancellationRequested)
        {
              scope = scopeFactory.CreateScope();
             processor = scope.ServiceProvider.GetRequiredService<IOrderProcessor>();

             processor.ProcessPendingAsync(stoppingToken);
             Task.Delay(TimeSpan.FromSeconds(), stoppingToken);
        }
    }
}

```text

---



```csharp

[]

{
    
     repo = Substitute.For<IOrderRepository>();
    repo.GetByIdAsync(, Arg.Any<CancellationToken>())
        .Returns( Order { Id =  });
     service =  OrderService(repo);

    
     result =  service.GetOrderAsync();

    
    Assert.NotNull(result);
    Assert.Equal(, result.Id);
}

[]

{
      cts =  CancellationTokenSource();
    cts.Cancel();

     Assert.ThrowsAsync<OperationCanceledException>(
        () => _service.ProcessAsync(cts.Token));
}

```text

---



Async patterns   skill are grounded  publicly available content :

- **Stephen Clearys Async Guidance** -- Practical  anti-patterns  diagnostic scenarios  ASP.NET Core. Source:
  https:
- **Stephen Toubs Async Blog](https:
- [Asynchronous programming patterns](https:
- [Task-