---

name: async-patterns description: Async/await patterns for the 3SC widget host. Covers Task handling, cancellation, ConfigureAwait, fire-and-forget prevention, and async command patterns in WPF.

Async Patterns

Overview

Proper async/await usage is critical for UI responsiveness and application stability. This skill covers patterns specific to WPF desktop applications.

Definition of Done (DoD)

• All async methods return Task or Task<T> (never async void except event handlers)
• Long-running operations support CancellationToken
• No .Result or .Wait() calls on UI thread
• Fire-and-forget tasks are handled with proper error logging
• Async commands show loading state and handle exceptions

Core Rules

1. Never Block the UI Thread

Copy// ❌ BAD - Blocks UI thread
var result = SomeAsyncMethod().Result;
var result = SomeAsyncMethod().GetAwaiter().GetResult();

// ✅ GOOD - Async all the way
var result = await SomeAsyncMethod();

2. Always Use CancellationToken

Copy// ✅ GOOD - Supports cancellation
public async Task<List<Widget>> LoadWidgetsAsync(CancellationToken cancellationToken = default)
{
    cancellationToken.ThrowIfCancellationRequested();
    
    return await _repository.GetAllAsync(cancellationToken);
}

3. ConfigureAwait in Library Code

Copy// In Infrastructure/Application layers (non-UI code):
public async Task<Widget> GetByIdAsync(Guid id, CancellationToken ct)
{
    return await _context.Widgets
        .FirstOrDefaultAsync(w => w.Id == id, ct)
        .ConfigureAwait(false);  // Don't capture UI context
}

// In UI layer (ViewModels) - capture context for UI updates:
public async Task LoadAsync()
{
    var widgets = await _service.GetWidgetsAsync();  // No ConfigureAwait
    Widgets = new ObservableCollection<Widget>(widgets);  // Must run on UI thread
}

Async Command Pattern

Standard Async Command

Copypublic partial class WidgetLibraryViewModel : ObservableObject
{
    [ObservableProperty]
    [NotifyPropertyChangedFor(nameof(IsNotLoading))]
    private bool _isLoading;
    
    public bool IsNotLoading => !IsLoading;

    [RelayCommand]
    private async Task LoadWidgetsAsync(CancellationToken cancellationToken)
    {
        if (IsLoading) return;  // Prevent double-execution
        
        IsLoading = true;
        ErrorMessage = null;
        
        try
        {
            var widgets = await _repository.GetAllAsync(cancellationToken);
            Widgets = new ObservableCollection<WidgetViewModel>(
                widgets.Select(w => new WidgetViewModel(w)));
        }
        catch (OperationCanceledException)
        {
            // Expected when user cancels - don't log as error
        }
        catch (Exception ex)
        {
            Log.Error(ex, "Failed to load widgets");
            ErrorMessage = "Failed to load widgets. Please try again.";
        }
        finally
        {
            IsLoading = false;
        }
    }
}

Command with Automatic Busy State

Copy// CommunityToolkit.Mvvm automatically sets IsRunning on async commands
[RelayCommand]
private async Task RefreshAsync(CancellationToken ct)
{
    await _service.RefreshAsync(ct);
}

// In XAML - bind to command's IsRunning
<Button Command="{Binding RefreshCommand}"
        IsEnabled="{Binding RefreshCommand.IsRunning, Converter={StaticResource InverseBoolConverter}}" />
        
<ProgressRing IsActive="{Binding RefreshCommand.IsRunning}" />

Fire-and-Forget Pattern

When you genuinely need fire-and-forget (rare), use this pattern:

Copypublic static class TaskExtensions
{
    /// <summary>
    /// Safely executes a fire-and-forget task with error logging.
    /// Use sparingly - prefer proper async/await chains.
    /// </summary>
    public static void FireAndForget(
        this Task task, 
        Action<Exception>? onError = null,
        [CallerMemberName] string? callerName = null)
    {
        task.ContinueWith(t =>
        {
            if (t.IsFaulted && t.Exception != null)
            {
                var ex = t.Exception.Flatten().InnerException ?? t.Exception;
                Log.Error(ex, "Fire-and-forget task failed in {Caller}", callerName);
                onError?.Invoke(ex);
            }
        }, TaskContinuationOptions.OnlyOnFaulted);
    }
}

// Usage:
_syncService.SyncAsync().FireAndForget(
    onError: ex => NotifyUser("Sync failed"));

Startup Async Pattern

For async operations during app startup:

Copy// ❌ BAD - Blocks startup
protected override void OnStartup(StartupEventArgs e)
{
    base.OnStartup(e);
    InitializeAsync().GetAwaiter().GetResult();  // Blocks!
}

// ✅ GOOD - Non-blocking startup
protected override async void OnStartup(StartupEventArgs e)
{
    base.OnStartup(e);
    
    // Show splash/shell immediately
    _shellWindow = new ShellWindow();
    _shellWindow.Show();
    
    try
    {
        await InitializeAsync();
    }
    catch (Exception ex)
    {
        Log.Fatal(ex, "Startup initialization failed");
        ShowCriticalError("Failed to start application");
        Shutdown(-1);
    }
}

Parallel Operations

When to Use Parallel

Copy// ✅ GOOD - Independent operations
var widgetsTask = _widgetRepo.GetAllAsync(ct);
var layoutsTask = _layoutRepo.GetAllAsync(ct);
var settingsTask = _settingsService.LoadAsync(ct);

await Task.WhenAll(widgetsTask, layoutsTask, settingsTask);

var widgets = await widgetsTask;
var layouts = await layoutsTask;
var settings = await settingsTask;

Bounded Parallelism

Copy// ✅ GOOD - Limit concurrent operations
public async Task ProcessWidgetsAsync(
    IEnumerable<Widget> widgets, 
    CancellationToken ct)
{
    var semaphore = new SemaphoreSlim(maxConcurrency: 4);
    
    var tasks = widgets.Select(async widget =>
    {
        await semaphore.WaitAsync(ct);
        try
        {
            await ProcessWidgetAsync(widget, ct);
        }
        finally
        {
            semaphore.Release();
        }
    });
    
    await Task.WhenAll(tasks);
}

Timeout Pattern

Copypublic async Task<T> WithTimeoutAsync<T>(
    Func<CancellationToken, Task<T>> operation,
    TimeSpan timeout,
    CancellationToken cancellationToken = default)
{
    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    cts.CancelAfter(timeout);
    
    try
    {
        return await operation(cts.Token);
    }
    catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
    {
        throw new TimeoutException($"Operation timed out after {timeout}");
    }
}

// Usage:
var result = await WithTimeoutAsync(
    ct => _api.FetchDataAsync(ct),
    timeout: TimeSpan.FromSeconds(30));

Anti-Patterns to Avoid

Testing Async Code

Copy[Fact]
public async Task LoadWidgetsAsync_WhenCancelled_ThrowsOperationCancelledException()
{
    // Arrange
    var cts = new CancellationTokenSource();
    cts.Cancel();
    
    // Act & Assert
    await Assert.ThrowsAsync<OperationCanceledException>(
        () => _viewModel.LoadWidgetsCommand.ExecuteAsync(cts.Token));
}

[Fact]
public async Task LoadWidgetsAsync_OnError_SetsErrorMessage()
{
    // Arrange
    _mockRepo.Setup(r => r.GetAllAsync(It.IsAny<CancellationToken>()))
        .ThrowsAsync(new InvalidOperationException("DB error"));
    
    // Act
    await _viewModel.LoadWidgetsCommand.ExecuteAsync(null);
    
    // Assert
    Assert.NotNull(_viewModel.ErrorMessage);
    Assert.False(_viewModel.IsLoading);
}

References

• Async/Await Best Practices
• ConfigureAwait FAQ