MonoGame.Samples/BackgroundThreadTester/README.md

Background Thread Tester - MonoGame 3.8.4

This project demonstrates background thread management in MonoGame applications.

Project Structure

This project has been modernized to use SDK-style projects with MonoGame 3.8.4 NuGet packages:

• BackgroundThreadTester.Windows.csproj - Windows DirectX version (net8.0-windows)
• BackgroundThreadTester.DesktopGL.csproj - Cross-platform OpenGL version (net8.0)
• BackgroundThreadTester.Android.csproj - Android version (net8.0-android)
• BackgroundThreadTester.iOS.csproj - iOS version (net8.0-ios)

Building and Running

Prerequisites

• .NET 8.0 SDK or later
• Visual Studio 2022 or VS Code

Build Commands

# Windows version
dotnet build BackgroundThreadTester.Windows.csproj

# DesktopGL version
dotnet build BackgroundThreadTester.DesktopGL.csproj

# Android version (requires Android SDK)
dotnet build BackgroundThreadTester.Android.csproj

Run Commands

# Windows version
dotnet run --project BackgroundThreadTester.Windows.csproj

# DesktopGL version
dotnet run --project BackgroundThreadTester.DesktopGL.csproj

VS Code Support

The project includes .vscode/tasks.json and .vscode/launch.json for building and debugging in VS Code.

Available VS Code configurations:

• Launch Windows - Debug Windows version with internal console
• Launch DesktopGL - Debug DesktopGL version with internal console
  
• Launch Windows (External Console) - Run Windows version with external terminal
• Launch DesktopGL (External Console) - Run DesktopGL version with external terminal

Quick Start:

1. Press F5 to start debugging
2. Select a launch configuration
3. Set breakpoints by clicking in the left margin

📖 Troubleshooting: See VSCODE_LAUNCH_GUIDE.md for detailed setup and troubleshooting instructions.

Visual Studio Support

Open BackgroundThreadTester.sln in Visual Studio 2022.

Features

• Modern Async Background Tasks - Uses Task-based async/await patterns instead of raw Thread
• Cross-Platform Thread Safety - Proper thread marshaling for UI operations across all platforms
• Cancellation Support - Background tasks can be cancelled cooperatively using CancellationToken
• Error Handling - Comprehensive exception handling with try/catch blocks
• Non-Blocking Operations - Uses Task.Delay() instead of Thread.Sleep() for better responsiveness
• Thread-Safe Component Management - Uses locks for safe component addition from background threads
• Resource Cleanup - Proper disposal of background task resources
• Cross-platform compatibility
• Uses existing .xnb content files (no .mgcb pipeline needed)

Modern Threading Patterns Used

This project demonstrates modern .NET threading best practices:

✅ Task-Based Async Pattern

// Modern approach using async/await
private async Task CreateBackgroundTaskAsync(CancellationToken cancellationToken)
{
    await Task.Delay(2000, cancellationToken); // Non-blocking delay
}

✅ Cooperative Cancellation

// Cancellation token support
cancellationToken.ThrowIfCancellationRequested();

✅ Thread-Safe Operations

// Thread-safe component addition
lock (_componentLock)
{
    Components.Add(testTexture);
}

✅ Exception Handling

try {
    // Background work
} catch (OperationCanceledException) {
    // Handle cancellation
} catch (Exception ex) {
    // Handle other errors
}

❌ Legacy Patterns (Avoided)

• Direct Thread usage with Thread.Start()
• Thread.Sleep() blocking calls
• Unsafe cross-thread operations
• No cancellation support
• No error handling

Original Description

Sample originally created by CircleOf14 and modified by Kenneth Pouncey to create new textures to be added to the game components dynamically in the background.

Of special interest look at the following methods:

• CreateBackgroundThread() - Creates a modern async background task with cancellation support
• CreateBackgroundTaskAsync() - NEW Modern async worker using Task-based patterns with proper error handling
• BackgroundWorkerThread() - Legacy method (now redirects to modern implementation for compatibility)

Key Modern Improvements:

1. Async/Await Pattern: Uses Task.Delay() instead of Thread.Sleep() for non-blocking operations
2. Cancellation Support: All background operations can be cancelled using CancellationToken
3. Thread Safety: Components are added using thread-safe locking mechanisms
4. Error Handling: Comprehensive exception handling for robust operation
5. Resource Management: Proper cleanup and disposal of background task resources
6. Cross-Platform: Works consistently across Windows, DesktopGL, Android, and iOS

Make sure to read the comments in these two methods.

MonoGame Version

This project uses MonoGame 3.8.* NuGet packages for better dependency management and cross-platform support.