Advanced

// Example 61: ValueTask for High-Performance Async
static class CachedService
{
    private static Dictionary<int, string> _cache = new()
                         // => Dictionary simulates cache storage
    {
        [1] = "Cached Value One",
                         // => Pre-cached values complete synchronously
        [2] = "Cached Value Two"
                         // => No async overhead for cache hits
    };

    public static ValueTask<string> GetValueAsync(int id)
                         // => ValueTask<T> reduces allocations
                         // => Returns struct, not class
                         // => Public API for value retrieval
    {
        if (_cache.TryGetValue(id, out var cached))
                         // => Check cache first
                         // => TryGetValue pattern avoids exceptions
        {
            return ValueTask.FromResult(cached);
                         // => Cache hit: completed ValueTask
                         // => No Task allocation, no heap object
                         // => Synchronous completion path
        }

        return new ValueTask<string>(FetchFromDatabaseAsync(id));
                         // => Cache miss: allocates Task only when needed
                         // => Wraps Task in ValueTask struct
                         // => Asynchronous completion path
    }

    private static async Task<string> FetchFromDatabaseAsync(int id)
                         // => Simulates async database query
                         // => Only invoked on cache misses
    {
        await Task.Delay(100);
                         // => Simulates query delay (100ms)
        return $"Database Value {id}";
                         // => Returns fetched value
    }
}

var result1 = await CachedService.GetValueAsync(1);
                         // => Cache hit, no Task allocation
                         // => result1 is "Cached Value One"
Console.WriteLine(result1);
                         // => Output: Cached Value One

var result2 = await CachedService.GetValueAsync(99);
                         // => Cache miss, Task allocated for async work
                         // => result2 is "Database Value 99"
Console.WriteLine(result2);
                         // => Output: Database Value 99

// Example 62: IAsyncEnumerable for Streaming Data
static async IAsyncEnumerable<int> ProduceNumbersAsync(int count)
                         // => IAsyncEnumerable<T> enables async iteration
                         // => Returns items incrementally
{
    for (int i = 1; i <= count; i++)
                         // => Generates 'count' items
    {
        await Task.Delay(100);
                         // => Simulates async data source
                         // => (database query, API call, sensor reading)
        yield return i * i;
                         // => Produces item WITHOUT completing method
                         // => Consumer gets item immediately, producer continues
    }
                         // => Method completes after all items yielded
}

await foreach (var number in ProduceNumbersAsync(5))
                         // => await foreach pauses until next item available
                         // => Each iteration processes one item as it arrives
{
    Console.WriteLine($"Received: {number}");
                         // => Output appears incrementally (500ms total):
                         // => Received: 1
                         // => Received: 4
                         // => Received: 9
                         // => Received: 16
                         // => Received: 25
}

static async IAsyncEnumerable<Customer> StreamCustomersAsync()
                         // => Simulates database reader returning rows incrementally
{
    var customers = new[]
    {
        new Customer("Alice", 30),
                         // => Row 1
        new Customer("Bob", 25),
                         // => Row 2
        new Customer("Carol", 35)
                         // => Row 3
    };

    foreach (var customer in customers)
    {
        await Task.Delay(50);
                         // => Simulates row fetch delay
        yield return customer;
                         // => Stream each customer as fetched
                         // => Consumer processes while fetching continues
    }
}

record Customer(string Name, int Age);
                         // => Simple data holder (record type)

await foreach (var customer in StreamCustomersAsync())
                         // => Process customers as they arrive (not all at once)
{
    Console.WriteLine($"{customer.Name}: {customer.Age}");
                         // => Each customer processed immediately upon arrival
                         // => No need to wait for all rows to load
}
                         // => Output: Alice: 30
                         // => Output: Bob: 25
                         // => Output: Carol: 35

// Example 63: Span<T> for Zero-Copy Memory Access
int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
                         // => Traditional approach with arrays
int[] firstHalf = numbers[0..5];
                         // => Creates NEW array (allocation)
                         // => Copies 5 elements (CPU cost)
int[] secondHalf = numbers[5..10];
                         // => Creates ANOTHER new array
                         // => Copies 5 more elements

int[] data = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
                         // => Original array
Span<int> span = data;
                         // => Span wraps entire array
                         // => No allocation, no copy
                         // => Points directly to array memory
Span<int> slice1 = span[0..5];
                         // => View of first 5 elements
                         // => No allocation, no copy
                         // => Just pointer + length
Span<int> slice2 = span[5..10];
                         // => View of last 5 elements
                         // => No allocation, no copy

slice1[0] = 100;
                         // => Modifies data[0] directly
                         // => No copying back
Console.WriteLine(data[0]);
                         // => Output: 100
                         // => Original array modified

string input = "2026-02-02";
                         // => Date string to parse
ReadOnlySpan<char> chars = input;
                         // => Span over string characters
                         // => No allocation
ReadOnlySpan<char> year = chars[0..4];
                         // => "2026" view (no substring allocation)
ReadOnlySpan<char> month = chars[5..7];
                         // => "02" view
ReadOnlySpan<char> day = chars[8..10];
                         // => "02" view

int y = int.Parse(year);
                         // => 2026 (parsed from span directly)
int m = int.Parse(month);
                         // => 2 (no substring created)
int d = int.Parse(day);
                         // => 2
Console.WriteLine($"{y}-{m:D2}-{d:D2}");
                         // => Output: 2026-02-02

// Example 64: Memory<T> for Async-Safe Memory Access
async Task ProcessWithSpanAsync()
                         // => Span limitation demonstration
{
    // Span<byte> buffer = stackalloc byte[1024];
                         // => ❌ COMPILER ERROR: Span<T> can't be in async
    // await Task.Delay(100);
                         // => Can't await with Span in scope
}

async Task ProcessWithMemoryAsync()
                         // => Memory solution for async methods
{
    byte[] data = new byte[1024];
                         // => Heap array for async safety
    Memory<byte> memory = data;
                         // => Memory wraps array
                         // => Can cross async boundaries
    await Task.Delay(100);
                         // => ✅ Valid with Memory<T>
    Span<byte> span = memory.Span;
                         // => Convert to Span when needed (in sync context)
    span[0] = 42;
                         // => Direct access through span
}

static async Task ReadFromStreamAsync(Stream stream)
                         // => Async buffer processing example
{
    byte[] buffer = new byte[4096];
                         // => Allocate buffer once for multiple reads
    Memory<byte> memory = buffer;
                         // => Wrap for async operations
    int bytesRead;
    while ((bytesRead = await stream.ReadAsync(memory)) > 0)
                         // => ReadAsync accepts Memory<byte> (async-compatible)
                         // => No allocation per read iteration
    {
        Memory<byte> chunk = memory[0..bytesRead];
                         // => Slice to actual data
                         // => No copy
        ProcessChunk(chunk);
                         // => Pass Memory to other methods
    }
}

static void ProcessChunk(Memory<byte> data)
                         // => Synchronous processing method
{
    Span<byte> span = data.Span;
                         // => Convert to Span for actual processing
    int nonZeroCount = 0;
    foreach (byte b in span)
                         // => Iterate span directly
    {
        if (b != 0) nonZeroCount++;
                         // => Count non-zero bytes
    }
    Console.WriteLine($"Non-zero bytes: {nonZeroCount}");
                         // => Output varies by stream content
}

var stream = new MemoryStream(new byte[] { 1, 0, 2, 0, 3 });
                         // => Create stream with sample data
await ReadFromStreamAsync(stream);
                         // => Process asynchronously
                         // => Output: Non-zero bytes: 3

// Example 65: stackalloc and ArrayPool for Buffer Management
static void ProcessWithHeapAllocation()
                         // => Traditional approach with heap allocation
                         // => Causes GC pressure
{
    byte[] buffer = new byte[256];
                         // => Heap allocation creates garbage
                         // => GC must collect later
                         // => Gen0 collection burden
    buffer[0] = 1;
                         // => Some processing
                         // => Buffer becomes garbage when method returns
                         // => Not reused
}

static void ProcessWithStackAlloc()
                         // => Stack allocation approach
                         // => Zero GC alternative
{
    Span<byte> buffer = stackalloc byte[256];
                         // => Allocated on STACK (not heap)
                         // => No heap allocation, zero GC impact
                         // => Limited to method scope
    buffer[0] = 1;
                         // => Use like normal array
                         // => Stack memory automatically reclaimed at method end
                         // => No garbage created
                         // => Ideal for small, temporary buffers
}

static void ProcessWithArrayPool()
                         // => ArrayPool approach with reusable buffers
                         // => Best for larger buffers
{
    byte[] buffer = ArrayPool<byte>.Shared.Rent(256);
                         // => Rent buffer from shared pool
                         // => May return array >= 256 in size
                         // => Reuses previously returned arrays
                         // => One allocation per buffer (amortized across many uses)
                         // => Thread-safe shared pool
    try
    {
        buffer[0] = 1;
                         // => Use buffer for processing
                         // => try/finally ensures return
    }
    finally
    {
        ArrayPool<byte>.Shared.Return(buffer, clearArray: true);
                         // => Return buffer to pool for reuse
                         // => clearArray: true zeros memory for security
                         // => Buffer available for next Rent call
                         // => Always return in finally block
    }
}

static int ParseNumbers(ReadOnlySpan<char> input)
                         // => stackalloc for small, known-size buffers
                         // => Practical stack usage example
{
    Span<int> results = stackalloc int[10];
                         // => Stack allocation (max 10 numbers)
                         // => 40 bytes (10 * sizeof(int))
    int count = 0;
                         // => Track parsed count
                         // => Results array index
    foreach (char c in input)
    {
        if (char.IsDigit(c))
                         // => Check if digit
                         // => Filters non-numeric chars
        {
            results[count++] = c - '0';
                         // => Parse and store on stack
                         // => '0' ASCII value subtraction
            if (count == 10) break;
                         // => Limit to 10 numbers
                         // => Prevents overflow
        }
    }
    int sum = 0;
                         // => Accumulator initialization
    for (int i = 0; i < count; i++)
    {
        sum += results[i];
                         // => Sum all parsed numbers
                         // => Stack memory access
    }
    return sum;
                         // => Return total
                         // => Stack freed automatically
}

static async Task ProcessLargeDataAsync(Stream stream)
                         // => Large buffer with ArrayPool
                         // => Async I/O pattern
{
    byte[] buffer = ArrayPool<byte>.Shared.Rent(1024 * 1024);
                         // => Rent 1MB buffer from pool
                         // => Too large for stack
                         // => Reusable buffer for I/O
    try
    {
        int read = await stream.ReadAsync(buffer);
                         // => Use buffer for async I/O
                         // => Awaits stream read
        Console.WriteLine($"Read {read} bytes");
                         // => Process 'read' bytes from buffer
                         // => Actual bytes read may be less than 1MB
    }
    finally
    {
        ArrayPool<byte>.Shared.Return(buffer);
                         // => CRITICAL: always return to pool
                         // => Enables buffer reuse
    }
}

int result = ParseNumbers("a1b2c3d4e5");
                         // => Stack-allocated processing
                         // => result is 15 (1+2+3+4+5)
Console.WriteLine($"Sum: {result}");
                         // => Output: Sum: 15

var stream = new MemoryStream(new byte[512]);
await ProcessLargeDataAsync(stream);
                         // => Pool-based processing
                         // => Output: Read 512 bytes

// Example 66: Reflection Basics - Type Inspection
class Person
{
    public string Name { get; set; }
                         // => Auto-property
    public int Age { get; set; }
                         // => Another auto-property
    public void Greet() => Console.WriteLine($"Hello, I'm {Name}");
                         // => Expression-bodied method
}

Type personType = typeof(Person);
                         // => Get Type object for Person
                         // => Type metadata available at runtime
Console.WriteLine($"Type name: {personType.Name}");
                         // => Output: Type name: Person

PropertyInfo[] properties = personType.GetProperties();
                         // => Get all public properties via reflection
                         // => Returns PropertyInfo array
foreach (var prop in properties)
{
    Console.WriteLine($"Property: {prop.Name}, Type: {prop.PropertyType.Name}");
                         // => Output: Property: Name, Type: String
                         // => Output: Property: Age, Type: Int32
}

var person = Activator.CreateInstance(personType);
                         // => Create instance dynamically (no 'new Person()')
                         // => Returns object (must cast)
PropertyInfo nameProp = personType.GetProperty("Name")!;
                         // => Get Name property by string
nameProp.SetValue(person, "Alice");
                         // => Set Name value dynamically
                         // => Equivalent to person.Name = "Alice"
PropertyInfo ageProp = personType.GetProperty("Age")!;
ageProp.SetValue(person, 30);
                         // => Set Age value dynamically

MethodInfo greetMethod = personType.GetMethod("Greet")!;
                         // => Get Greet method by string
greetMethod.Invoke(person, null);
                         // => Invoke Greet() dynamically
                         // => Output: Hello, I'm Alice

object nameValue = nameProp.GetValue(person)!;
                         // => Get Name value dynamically
                         // => nameValue is "Alice" (type: object)
Console.WriteLine($"Name via reflection: {nameValue}");
                         // => Output: Name via reflection: Alice

// Example 67: Custom Attributes and Attribute Reflection
[AttributeUsage(AttributeTargets.Property)]
                         // => AttributeUsage specifies valid targets
                         // => This attribute applies to properties only
class ValidateRangeAttribute : Attribute
                         // => Custom attribute (inherits Attribute)
{
    public int Min { get; }
                         // => Minimum value for validation
    public int Max { get; }
                         // => Maximum value for validation
    public ValidateRangeAttribute(int min, int max)
    {
        Min = min;
                         // => Store min constraint
        Max = max;
                         // => Store max constraint
    }
}

class Product
{
    [ValidateRange(1, 100)]
                         // => Apply custom attribute with parameters
                         // => Metadata attached to Quantity property
    public int Quantity { get; set; }

    [ValidateRange(0, 10000)]
                         // => Different range for Price
    public decimal Price { get; set; }
}

static bool Validate<T>(T obj)
                         // => Generic validation using reflection + attributes
{
    Type type = typeof(T);
                         // => Get type metadata
    foreach (PropertyInfo prop in type.GetProperties())
                         // => Iterate all properties
    {
        var attr = prop.GetCustomAttribute<ValidateRangeAttribute>();
                         // => Get ValidateRange attribute if present
                         // => Returns null if not found
        if (attr != null)
                         // => Property has validation attribute
        {
            object? value = prop.GetValue(obj);
                         // => Get property value via reflection
            if (value is int intValue)
                         // => Check if value is int
            {
                if (intValue < attr.Min || intValue > attr.Max)
                         // => Validate against min/max constraints
                {
                    Console.WriteLine($"{prop.Name} out of range: {intValue} (valid: {attr.Min}-{attr.Max})");
                         // => Validation failed
                    return false;
                }
            }
        }
    }
    return true;
                         // => All validations passed
}

var product1 = new Product { Quantity = 50, Price = 100 };
                         // => Valid product (Quantity in [1,100])
Console.WriteLine($"Product1 valid: {Validate(product1)}");
                         // => Output: Product1 valid: True

var product2 = new Product { Quantity = 150, Price = 100 };
                         // => Invalid product (Quantity > 100)
Console.WriteLine($"Product2 valid: {Validate(product2)}");
                         // => Output: Quantity out of range: 150 (valid: 1-100)
                         // => Output: Product2 valid: False

// Example 68: Expression Trees - Code as Data
Expression<Func<int, int>> expr = x => x * 2 + 1;
                         // => Expression tree captures lambda as data
                         // => NOT compiled code - data structure
                         // => Type: Expression<Func<int, int>>
Console.WriteLine($"Expression: {expr}");
                         // => Output: Expression: x => ((x * 2) + 1)
                         // => ToString() shows expression structure

BinaryExpression body = (BinaryExpression)expr.Body;
                         // => Body is the + operation
                         // => Cast to BinaryExpression for inspection
Console.WriteLine($"NodeType: {body.NodeType}");
                         // => Output: NodeType: Add
Console.WriteLine($"Left: {body.Left}");
                         // => Output: Left: (x * 2)
Console.WriteLine($"Right: {body.Right}");
                         // => Output: Right: 1

Func<int, int> compiled = expr.Compile();
                         // => Compile expression tree to executable delegate
                         // => Now runnable as normal function
int result = compiled(5);
                         // => Execute compiled function
                         // => result is 11 (5 * 2 + 1)
Console.WriteLine($"Result: {result}");
                         // => Output: Result: 11

Expression<Func<Person, bool>> filter = p => p.Age > 25;
                         // => Expression for LINQ query
                         // => Entity Framework translates to SQL WHERE clause
var param = filter.Parameters[0];
                         // => Get parameter (p)
var bodyExpr = filter.Body;
                         // => Get body expression (p.Age > 25)
Console.WriteLine($"Parameter: {param.Name}, Body: {bodyExpr}");
                         // => Output: Parameter: p, Body: (p.Age > 25)

class Person
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

Expression<Func<Person, string>> selector = p => p.Name.ToUpper();
                         // => Property access + method call expression
var selectorBody = selector.Body;
                         // => Body is MethodCallExpression (ToUpper)
if (selectorBody is MethodCallExpression methodCall)
{
    Console.WriteLine($"Method: {methodCall.Method.Name}");
                         // => Output: Method: ToUpper
    Console.WriteLine($"Object: {methodCall.Object}");
                         // => Output: Object: p.Name
}

// Example 69: Source Generators - Compile-Time Code Generation
// This example shows USAGE of source-generated code
// Source generator implementation requires separate project

[AutoNotify]
                         // => Attribute triggers source generator
                         // => Generator creates INotifyPropertyChanged implementation
partial class ViewModel
                         // => Must be partial for source generator
{
    private string _name = "";
                         // => Backing field
                         // => Generator creates Name property with change notification
    private int _age;
                         // => Another backing field
                         // => Generator creates Age property
}

var vm = new ViewModel();
                         // => Create instance
vm.PropertyChanged += (s, e) =>
                         // => Subscribe to generated event
{
    Console.WriteLine($"Property changed: {e.PropertyName}");
                         // => Output when properties change
};

vm.Name = "Alice";
                         // => Generated property setter
                         // => Raises PropertyChanged event
                         // => Output: Property changed: Name
vm.Age = 30;
                         // => Generated property setter
                         // => Output: Property changed: Age

[JsonSerializable(typeof(Person))]
                         // => System.Text.Json source generator attribute
                         // => Generates serialization code at compile time
partial class PersonJsonContext : JsonSerializerContext
                         // => Partial class completed by generator
{
}

var person = new Person { Name = "Bob", Age = 25 };
                         // => Create person instance
string json = JsonSerializer.Serialize(person, PersonJsonContext.Default.Person);
                         // => Use generated serialization code
                         // => No reflection at runtime (faster)
                         // => json is {"Name":"Bob","Age":25}
Console.WriteLine(json);
                         // => Output: {"Name":"Bob","Age":25}

Person? deserialized = JsonSerializer.Deserialize<Person>(json, PersonJsonContext.Default.Person);
                         // => Use generated deserialization code
                         // => No reflection overhead
Console.WriteLine($"{deserialized?.Name}, {deserialized?.Age}");
                         // => Output: Bob, 25

class Person
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

// Example 70: Advanced Pattern Matching - List Patterns and Type Patterns
static string DescribeArray(int[] numbers) => numbers switch
                         // => List pattern matching (C# 11+)
{
    [] => "Empty array",
                         // => Matches empty array
    [var single] => $"Single element: {single}",
                         // => Matches array with exactly one element
                         // => Captures element in 'single'
    [var first, var second] => $"Two elements: {first}, {second}",
                         // => Matches exactly two elements
    [var first, .., var last] => $"Multiple: first={first}, last={last}",
                         // => '..' matches any number of elements in between
                         // => Captures first and last only
    _ => "Other"
                         // => Fallback (never reached with above patterns)
};

Console.WriteLine(DescribeArray(new int[] { }));
                         // => Output: Empty array
Console.WriteLine(DescribeArray(new int[] { 42 }));
                         // => Output: Single element: 42
Console.WriteLine(DescribeArray(new int[] { 1, 2 }));
                         // => Output: Two elements: 1, 2
Console.WriteLine(DescribeArray(new int[] { 1, 2, 3, 4, 5 }));
                         // => Output: Multiple: first=1, last=5

static string ProcessValue(object obj) => obj switch
                         // => Type patterns with property patterns
{
    int n when n > 0 => $"Positive int: {n}",
                         // => Type pattern with guard clause
    int n => $"Non-positive int: {n}",
                         // => Type pattern without guard
    string { Length: > 0 } s => $"Non-empty string: {s}",
                         // => Type pattern + property pattern
                         // => Matches string with Length > 0
    string => "Empty string",
                         // => Matches any string not caught above
    Person { Age: >= 18 } p => $"Adult: {p.Name}",
                         // => Type pattern + property pattern
                         // => Matches Person with Age >= 18
    Person p => $"Minor: {p.Name}",
                         // => Matches any Person not caught above
    _ => "Unknown type"
                         // => Discard pattern (fallback)
};

Console.WriteLine(ProcessValue(42));
                         // => Output: Positive int: 42
Console.WriteLine(ProcessValue(-5));
                         // => Output: Non-positive int: -5
Console.WriteLine(ProcessValue("Hello"));
                         // => Output: Non-empty string: Hello
Console.WriteLine(ProcessValue(""));
                         // => Output: Empty string
Console.WriteLine(ProcessValue(new Person { Name = "Alice", Age = 30 }));
                         // => Output: Adult: Alice
Console.WriteLine(ProcessValue(new Person { Name = "Bob", Age = 15 }));
                         // => Output: Minor: Bob

record Person(string Name, int Age);
                         // => Record type for matching

// Example 71: Channels for Producer-Consumer Patterns
var channel = Channel.CreateBounded<int>(new BoundedChannelOptions(10)
                         // => Bounded channel with capacity 10
                         // => Blocks writers when full (backpressure)
{
    FullMode = BoundedChannelFullMode.Wait
                         // => Wait when full (alternative: DropOldest, DropNewest, DropWrite)
});

var producer = Task.Run(async () =>
                         // => Producer task writes to channel
{
    for (int i = 1; i <= 20; i++)
    {
        await channel.Writer.WriteAsync(i);
                         // => Write item to channel
                         // => Blocks if channel full (backpressure)
        Console.WriteLine($"Produced: {i}");
        await Task.Delay(100);
                         // => Simulate production delay
    }
    channel.Writer.Complete();
                         // => Signal no more items
                         // => Consumers can finish
});

var consumer = Task.Run(async () =>
                         // => Consumer task reads from channel
{
    await foreach (var item in channel.Reader.ReadAllAsync())
                         // => ReadAllAsync provides IAsyncEnumerable
                         // => Completes when channel completed
    {
        Console.WriteLine($"Consumed: {item}");
        await Task.Delay(200);
                         // => Simulate processing delay (slower than producer)
                         // => Backpressure kicks in when channel fills
    }
});

await Task.WhenAll(producer, consumer);
                         // => Wait for both tasks to complete
                         // => Output shows backpressure: producer waits when channel full

var unboundedChannel = Channel.CreateUnbounded<string>();
                         // => Unbounded channel (no capacity limit)
                         // => No backpressure, but risk of memory growth

var writer = unboundedChannel.Writer;
writer.TryWrite("Message 1");
                         // => TryWrite for synchronous, non-blocking write
                         // => Returns false if bounded channel full
writer.TryWrite("Message 2");

var reader = unboundedChannel.Reader;
if (reader.TryRead(out var message))
                         // => TryRead for synchronous, non-blocking read
                         // => Returns false if no items available
{
    Console.WriteLine($"Read: {message}");
                         // => Output: Read: Message 1
}

// Example 72: SemaphoreSlim for Async Concurrency Control
var semaphore = new SemaphoreSlim(3);
                         // => Allow 3 concurrent operations max
                         // => Initial count: 3 (type: SemaphoreSlim)
                         // => 4th caller waits until slot available
async Task ProcessAsync(int id)
{                        // => Async method accepting task ID
                         // => id parameter identifies task
    Console.WriteLine($"{id}: Waiting...");
                         // => Output: 1: Waiting... (or current id)
    await semaphore.WaitAsync();
                         // => Wait for available slot (async operation)
                         // => Decrements count (3 -> 2 -> 1 -> 0)
                         // => Blocks when count reaches 0
                         // => Returns when slot acquired
    try
    {                    // => Protected execution block
        Console.WriteLine($"{id}: Processing started");
                         // => Output: 1: Processing started
        await Task.Delay(2000);
                         // => Simulate 2-second operation
                         // => Async delay (non-blocking)
        Console.WriteLine($"{id}: Processing finished");
                         // => Output: 1: Processing finished
    }
    finally
    {                    // => Cleanup block (always executes)
        semaphore.Release();
                         // => Release slot for waiting tasks
                         // => Increments count (0 -> 1 -> 2 -> 3)
                         // => Allows next waiting task to proceed
    }
}

var tasks = Enumerable.Range(1, 10)
                         // => Create sequence 1-10 (type: IEnumerable<int>)
                         // => Generates 10 task IDs
    .Select(i => ProcessAsync(i))
                         // => Map each ID to ProcessAsync call
                         // => Returns IEnumerable<Task>
    .ToArray();          // => Execute enumeration, create array
                         // => tasks is Task[] (10 elements)
await Task.WhenAll(tasks);
                         // => Wait for all 10 tasks to complete
                         // => Run all tasks (but only 3 concurrent at a time)
                         // => Output shows 3 tasks run, then next 3 when slots free

class RateLimitedApi
                         // => Practical rate limiting example
                         // => Encapsulates rate-limited API access
{
    private readonly SemaphoreSlim _semaphore = new(5);
                         // => Field: SemaphoreSlim with initial count 5
                         // => Allow 5 concurrent API calls max
                         // => readonly ensures immutability after construction
    public async Task<string> CallApiAsync(string endpoint)
    {                    // => Async method returning Task<string>
                         // => endpoint parameter specifies API endpoint
        await _semaphore.WaitAsync();
                         // => Wait for available slot
                         // => Blocks if 5 calls already in progress
        try
        {                // => Protected API call
            await Task.Delay(1000);
                         // => Simulate API call (1 second delay)
                         // => In real code: HttpClient.GetAsync()
            return $"Result from {endpoint}";
                         // => Return simulated response
                         // => Type: string
        }
        finally
        {                // => Cleanup (always executes)
            _semaphore.Release();
                         // => Always release in finally
                         // => Even if exception occurs
        }
    }
}

var api = new RateLimitedApi();
                         // => Create instance (type: RateLimitedApi)
var apiTasks = Enumerable.Range(1, 20)
                         // => 20 concurrent requests (sequence 1-20)
    .Select(i => api.CallApiAsync($"endpoint{i}"))
                         // => Call API for each endpoint
                         // => endpoint1, endpoint2, ..., endpoint20
    .ToArray();          // => Convert to Task<string>[]
await Task.WhenAll(apiTasks);
                         // => Wait for all 20 API calls to complete
                         // => Only 5 execute at a time (rate limiting)
                         // => Remaining 15 queue up

using var timeoutSemaphore = new SemaphoreSlim(1);
                         // => Binary semaphore (mutex alternative)
                         // => Count: 1 (only one task can acquire)
                         // => using ensures Dispose called
bool acquired = await timeoutSemaphore.WaitAsync(TimeSpan.FromSeconds(5));
                         // => Wait with timeout (max 5 seconds)
                         // => Returns true if acquired, false if timeout
                         // => Returns false if timeout expires
                         // => acquired is bool
if (acquired)
{                        // => Successfully acquired within timeout
    try
    {
        Console.WriteLine("Acquired lock");
                         // => Output: Acquired lock
    }
    finally
    {                    // => Release block
        timeoutSemaphore.Release();
                         // => Return semaphore to available state
    }
}
else
{                        // => Timeout occurred (5 seconds passed)
    Console.WriteLine("Timeout waiting for lock");
                         // => Output: Timeout waiting for lock
}

// Example 73: Lock and Monitor for Thread Safety
class Counter
{                        // => Thread-safe counter implementation
    private int _count = 0;
                         // => Shared state (not thread-safe alone)
                         // => Field: int initialized to 0
    private readonly object _lock = new();
                         // => Lock object for synchronization
                         // => object type (any reference type works)
                         // => readonly: reference immutable after construction
    public void Increment()
    {                    // => Public method to increment counter
        lock (_lock)
                         // => Acquires lock (Monitor.Enter)
                         // => Only one thread in lock block at a time
                         // => Syntactic sugar for Monitor.Enter/Exit
        {                // => Critical section begins
            _count++;
                         // => Increment operation (read, add 1, write)
                         // => Critical section (thread-safe)
                         // => Read-modify-write operation atomic
        }                // => Critical section ends
                         // => Releases lock (Monitor.Exit automatically)
                         // => Next waiting thread can enter
    }
    public int GetCount()
    {                    // => Thread-safe getter
        lock (_lock)
                         // => Must lock for reads too
                         // => Ensures memory visibility
        {
            return _count;
                         // => Thread-safe read
                         // => Returns current count value
        }
    }
}

var counter = new Counter();
                         // => Create Counter instance (type: Counter)
var tasks = Enumerable.Range(0, 1000)
                         // => Sequence 0-999 (1000 items)
                         // => 1000 parallel increments
    .Select(_ => Task.Run(() => counter.Increment()))
                         // => Map each index to Task
                         // => Discard parameter (_)
                         // => Each task calls Increment
    .ToArray();          // => Convert to Task[]
await Task.WhenAll(tasks);
                         // => Wait for all 1000 increments to complete
                         // => Parallel execution
Console.WriteLine($"Final count: {counter.GetCount()}");
                         // => Call GetCount to retrieve value
                         // => Output: Final count: 1000
                         // => Without lock: race conditions, lost updates

class BankAccount
                         // => Monitor example with timeouts
                         // => Demonstrates Monitor.TryEnter API
{
    private decimal _balance = 0;
                         // => Balance field (type: decimal)
    private readonly object _balanceLock = new();
                         // => Lock object for balance operations
    public bool TryDeposit(decimal amount, TimeSpan timeout)
    {                    // => Returns bool (success/failure)
                         // => amount parameter: decimal to deposit
                         // => timeout parameter: max wait time
        if (Monitor.TryEnter(_balanceLock, timeout))
                         // => Try to acquire lock with timeout
                         // => Returns true if acquired, false otherwise
                         // => Returns false if timeout expires
        {                // => Lock acquired successfully
            try
            {            // => Protected operation
                _balance += amount;
                         // => Add amount to balance
                         // => Critical section
                return true;
                         // => Deposit succeeded
            }
            finally
            {            // => Cleanup (always executes)
                Monitor.Exit(_balanceLock);
                         // => Release lock manually
                         // => Must call when using TryEnter
            }
        }
        return false;
                         // => Failed to acquire lock within timeout
                         // => Deposit failed
    }
    public decimal Balance
    {                    // => Property getter
        get
        {                // => Getter implementation
            lock (_balanceLock) return _balance;
                         // => Thread-safe balance read
                         // => Single-line lock statement
        }
    }
}

var account = new BankAccount();
                         // => Create BankAccount instance
bool success = account.TryDeposit(100, TimeSpan.FromSeconds(1));
                         // => Attempt deposit of 100 with 1-second timeout
                         // => TimeSpan.FromSeconds creates TimeSpan
                         // => success is bool
Console.WriteLine($"Deposit success: {success}, Balance: {account.Balance}");
                         // => Output: Deposit success: True, Balance: 100
                         // => Accesses Balance property

class UnsafeCounter
                         // => Demonstration of race condition
                         // => Shows WHY locks are needed
{
    private int _count = 0;
                         // => Shared field (no lock protection)
    public void Increment() => _count++;
                         // => NO LOCK (race condition)
                         // => Expression-bodied member
                         // => Read-modify-write not atomic
                         // => Multiple threads can interleave operations
    public int GetCount() => _count;
                         // => Unprotected read
}

var unsafeCounter = new UnsafeCounter();
                         // => Create unsafe counter instance
var unsafeTasks = Enumerable.Range(0, 1000)
                         // => 1000 tasks (same as safe counter)
    .Select(_ => Task.Run(() => unsafeCounter.Increment()))
                         // => Each task increments WITHOUT lock
    .ToArray();          // => Convert to Task[]
await Task.WhenAll(unsafeTasks);
                         // => Wait for all 1000 tasks
Console.WriteLine($"Unsafe count: {unsafeCounter.GetCount()}");
                         // => Output: Unsafe count: <1000 (lost updates)
                         // => Actual value varies (950-990 typically)
                         // => Race condition causes lost increments
                         // => Non-deterministic result

// Example 74: Unsafe Code and Pointers
unsafe void UnsafeArrayAccess()
                         // => unsafe keyword required for pointer code
{
    int[] numbers = { 1, 2, 3, 4, 5 };
    fixed (int* ptr = numbers)
                         // => fixed prevents GC from moving array
                         // => ptr points to first element
    {
        Console.WriteLine($"First element: {*ptr}");
                         // => *ptr dereferences pointer (value at address)
                         // => Output: First element: 1
        *(ptr + 1) = 99;
                         // => Pointer arithmetic: ptr+1 points to second element
                         // => Assigns 99 to numbers[1]
        Console.WriteLine($"Second element: {*(ptr + 1)}");
                         // => Output: Second element: 99
    }
                         // => Array can move again after fixed block
    Console.WriteLine($"Array[1]: {numbers[1]}");
                         // => Output: Array[1]: 99
}

unsafe int SumWithPointers(int[] arr)
                         // => Unsafe method for performance
{
    int sum = 0;
    fixed (int* ptr = arr)
                         // => Pin array for pointer access
    {
        int* current = ptr;
                         // => Current pointer starts at first element
        int* end = ptr + arr.Length;
                         // => End pointer points past last element
        while (current < end)
                         // => Iterate using pointer comparison
        {
            sum += *current;
                         // => Dereference and add to sum
            current++;
                         // => Move to next element (pointer arithmetic)
        }
    }
    return sum;
                         // => Return total
}

unsafe
{
    UnsafeArrayAccess();
                         // => Call unsafe method
    int[] data = { 10, 20, 30, 40, 50 };
    int total = SumWithPointers(data);
                         // => total is 150
    Console.WriteLine($"Sum: {total}");
                         // => Output: Sum: 150
}

unsafe void StackAllocWithPointers()
                         // => Combine unsafe with stackalloc
{
    int* buffer = stackalloc int[10];
                         // => Allocate 10 ints on stack
                         // => Returns pointer (not Span)
    for (int i = 0; i < 10; i++)
    {
        buffer[i] = i * i;
                         // => Pointer indexing (like array)
    }
    for (int i = 0; i < 10; i++)
    {
        Console.WriteLine($"buffer[{i}] = {buffer[i]}");
                         // => Output: buffer[0] = 0, buffer[1] = 1, buffer[2] = 4, ...
    }
}

unsafe
{
    StackAllocWithPointers();
                         // => Demonstrate stack-allocated pointer buffer
}

unsafe struct UnmanagedStruct
                         // => Struct with only unmanaged types
{
    public int Id;
    public float Value;
    public fixed byte Buffer[16];
                         // => Fixed-size buffer (inline array)
                         // => Only allowed in unsafe structs
}

unsafe
{
    UnmanagedStruct data;
    data.Id = 42;
    data.Value = 3.14f;
    for (int i = 0; i < 16; i++)
    {
        data.Buffer[i] = (byte)i;
                         // => Initialize fixed buffer
    }
    Console.WriteLine($"Id: {data.Id}, Value: {data.Value}, Buffer[0]: {data.Buffer[0]}");
                         // => Output: Id: 42, Value: 3.14, Buffer[0]: 0
}

// Example 75: P/Invoke - Calling Native Code
using System.Runtime.InteropServices;
                         // => Required namespace for P/Invoke

static class NativeMethods
                         // => Convention: static class for P/Invoke declarations
                         // => Groups native method imports
{
    [DllImport("kernel32.dll", SetLastError = true)]
                         // => DllImport attribute specifies native DLL
                         // => SetLastError = true enables Marshal.GetLastWin32Error()
                         // => Windows kernel32 library
    public static extern bool Beep(uint frequency, uint duration);
                         // => extern indicates external (native) implementation
                         // => Maps to Beep function in kernel32.dll
                         // => Returns bool (Win32 BOOL)
                         // => Parameters: uint for frequency/duration

    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
                         // => CharSet specifies string encoding (Unicode/Ansi/Auto)
                         // => Windows user32 library
    public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
                         // => IntPtr for handles/pointers
                         // => string marshaled automatically
                         // => Returns int (button clicked)

    [DllImport("libc", EntryPoint = "strlen")]
                         // => Linux/macOS libc
                         // => EntryPoint specifies actual function name
                         // => Cross-platform example
    public static extern int StrLen([MarshalAs(UnmanagedType.LPStr)] string str);
                         // => MarshalAs controls marshaling behavior
                         // => LPSTR for null-terminated string
}

bool success = NativeMethods.Beep(800, 200);
                         // => Call native Beep function
                         // => 800 Hz for 200ms
                         // => success indicates if call succeeded
if (!success)
{
    int error = Marshal.GetLastWin32Error();
                         // => Get Win32 error code
                         // => Only valid with SetLastError = true
    Console.WriteLine($"Beep failed: {error}");
                         // => Report error
}

NativeMethods.MessageBox(IntPtr.Zero, "Hello from C#!", "P/Invoke Demo", 0);
                         // => Show native Windows message box
                         // => IntPtr.Zero for no parent window
                         // => 0 for MB_OK button

[StructLayout(LayoutKind.Sequential)]
                         // => StructLayout controls memory layout
                         // => Sequential matches C struct layout
                         // => Required for native interop
struct Point
{                         // => Value type for Win32 POINT structure
    public int X;
                         // => X coordinate
    public int Y;
                         // => Y coordinate
}

static class NativeMethods2
{                         // => Additional native methods
    [DllImport("user32.dll")]
                         // => GetCursorPos from user32.dll
    public static extern bool GetCursorPos(out Point point);
                         // => out parameter receives struct from native code
                         // => point filled by native call
}

Point cursorPos;
                         // => Uninitialized struct
if (NativeMethods2.GetCursorPos(out cursorPos))
                         // => Get mouse cursor position via Win32 API
                         // => cursorPos receives screen coordinates
{
    Console.WriteLine($"Cursor: ({cursorPos.X}, {cursorPos.Y})");
                         // => Output: Cursor: (X, Y) [actual screen coordinates]
                         // => Screen coordinates updated by native call
}

[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
                         // => Delegate for native callback
delegate int NativeCallback(int value);

static class NativeMethods3
{
    [DllImport("custom.dll")]
    public static extern void ProcessWithCallback(NativeCallback callback);
                         // => Pass managed delegate to native code
                         // => Native code calls back into C#
}

static int MyCallback(int value)
                         // => C# method called by native code
{
    Console.WriteLine($"Callback received: {value}");
    return value * 2;
}

// NativeMethods3.ProcessWithCallback(MyCallback);
                         // => Commented out (requires custom.dll)
                         // => Demonstrates callback pattern

// Example 76: BenchmarkDotNet for Performance Measurement
// Install NuGet: BenchmarkDotNet
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]
                         // => MemoryDiagnoser tracks allocations
                         // => Reports Gen0/Gen1/Gen2 collections and bytes allocated
public class StringBenchmarks
{
    private const int Iterations = 1000;

    [Benchmark]
                         // => Benchmark attribute marks method for measurement
    public string StringConcat()
                         // => Concatenation via + operator
    {
        string result = "";
        for (int i = 0; i < Iterations; i++)
        {
            result += "x";
                         // => Creates new string each iteration
                         // => O(n²) complexity
        }
        return result;
    }

    [Benchmark]
    public string StringBuilderConcat()
                         // => Concatenation via StringBuilder
    {
        var sb = new StringBuilder();
        for (int i = 0; i < Iterations; i++)
        {
            sb.Append("x");
                         // => Amortized O(1) per append
                         // => O(n) total complexity
        }
        return sb.ToString();
    }

    [Benchmark]
    public string StringCreate()
                         // => string.Create (C# 7.2+)
    {
        return string.Create(Iterations, 'x', (span, c) =>
        {
            span.Fill(c);
                         // => Fill Span<char> directly
                         // => No intermediate allocations
        });
    }
}

[MemoryDiagnoser]
public class CollectionBenchmarks
{
    private readonly int[] _data = Enumerable.Range(0, 10000).ToArray();

    [Benchmark]
    public int ListSum()
                         // => LINQ Sum on List
    {
        return _data.ToList().Sum();
                         // => ToList() allocates new List
    }

    [Benchmark]
    public int ArraySum()
                         // => Direct array Sum
    {
        return _data.Sum();
                         // => No allocation
    }

    [Benchmark]
    public int SpanSum()
                         // => Span-based sum
    {
        Span<int> span = _data;
        int sum = 0;
        foreach (var item in span)
        {
            sum += item;
                         // => Direct iteration
        }
        return sum;
    }
}

// Run benchmarks (in Program.cs Main)
// var summary = BenchmarkRunner.Run<StringBenchmarks>();
                         // => Executes all [Benchmark] methods
                         // => Warmup, multiple iterations, statistical analysis
                         // => Generates detailed report

// Example output:
// Method                | Mean      | Error    | StdDev   | Gen0   | Allocated
// StringConcat          | 45.23 μs  | 0.234 μs | 0.219 μs | 125.00 | 500 KB
// StringBuilderConcat   | 2.15 μs   | 0.012 μs | 0.011 μs | 1.25   | 5 KB
// StringCreate          | 0.89 μs   | 0.008 μs | 0.007 μs | 0.25   | 1 KB
                         // => string.Create is much faster than + operator
                         // => StringBuilder is significantly faster
                         // => Allocation differences show GC impact

[Benchmark]
[Arguments(10)]
[Arguments(100)]
[Arguments(1000)]
                         // => Test with different input sizes
public int ParameterizedBenchmark(int size)
{
    var list = new List<int>(size);
    for (int i = 0; i < size; i++)
    {
        list.Add(i);
    }
    return list.Sum();
}

// Example 77: Minimal APIs - Lightweight HTTP Endpoints
var builder = WebApplication.CreateBuilder(args);
                         // => Create web application builder
                         // => Configures services and middleware
builder.Services.AddEndpointsApiExplorer();
                         // => Enable endpoint discovery for OpenAPI
builder.Services.AddSwaggerGen();
                         // => Add Swagger/OpenAPI generation
var app = builder.Build();
                         // => Build application from builder

app.MapGet("/", () => "Hello World!");
                         // => GET endpoint at root
                         // => Lambda returns response
                         // => Output: "Hello World!"

app.MapGet("/users/{id:int}", (int id) =>
                         // => Route parameter with type constraint
                         // => id automatically parsed from URL
{
    return new User(id, $"User{id}");
                         // => Returns JSON automatically
                         // => Output: {"Id":123,"Name":"User123"}
});

app.MapPost("/users", (User user) =>
                         // => POST endpoint accepting JSON body
                         // => user deserialized from request body
{
    Console.WriteLine($"Created user: {user.Name}");
    return Results.Created($"/users/{user.Id}", user);
                         // => Returns 201 Created with Location header
});

app.MapGet("/products", async (HttpContext context) =>
                         // => Access HttpContext directly
{
    var products = new[] { "Product1", "Product2", "Product3" };
    await context.Response.WriteAsJsonAsync(products);
                         // => Write JSON response
});

app.MapGet("/search", (string? query, int page = 1, int pageSize = 10) =>
                         // => Query string parameters
                         // => Optional (?) and default values supported
{
    return new
    {
        Query = query ?? "none",
        Page = page,
        PageSize = pageSize,
        Results = Array.Empty<string>()
    };
                         // => Anonymous type serialized to JSON
});

record User(int Id, string Name);

var group = app.MapGroup("/api/v1")
                         // => Group related endpoints
                         // => Prefix all routes with /api/v1
    .RequireAuthorization();
                         // => Apply authorization to all endpoints in group

group.MapGet("/admin", () => "Admin area");
                         // => Endpoint: GET /api/v1/admin
                         // => Authorization required

app.MapGet("/weather", async () =>
                         // => Async endpoint example
{
    await Task.Delay(100);
                         // => Simulate async work
    return new { Temperature = 72, Condition = "Sunny" };
});

if (app.Environment.IsDevelopment())
                         // => Conditional middleware for development
{
    app.UseSwagger();
                         // => Enable Swagger JSON endpoint
    app.UseSwaggerUI();
                         // => Enable Swagger UI
}

// app.Run();
                         // => Start HTTP server
                         // => Listens on configured port (default: 5000/5001)

// Example 78: Middleware Pipeline - Request Processing
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.Use(async (context, next) =>
                         // => Custom middleware (inline)
                         // => context: HttpContext, next: next middleware
{
    Console.WriteLine($"Before: {context.Request.Path}");
                         // => Log request path before processing
    await next();
                         // => Call next middleware in pipeline
                         // => Response generated here
    Console.WriteLine($"After: {context.Response.StatusCode}");
                         // => Log response status after processing
});

app.Use(async (context, next) =>
                         // => Timing middleware
{
    var sw = System.Diagnostics.Stopwatch.StartNew();
                         // => Start timer
    await next();
                         // => Process request through pipeline
    sw.Stop();
    Console.WriteLine($"Request took {sw.ElapsedMilliseconds}ms");
                         // => Log request duration
});

app.UseWhen(context => context.Request.Path.StartsWithSegments("/api"),
                         // => Conditional middleware (only for /api paths)
    appBuilder =>
    {
        appBuilder.Use(async (context, next) =>
        {
            context.Response.Headers.Add("X-API-Version", "1.0");
                         // => Add header only for API requests
            await next();
        });
    });

app.Map("/admin", adminApp =>
                         // => Branch pipeline for /admin paths
{
    adminApp.Use(async (context, next) =>
    {
        Console.WriteLine("Admin middleware");
                         // => Only runs for /admin requests
        await next();
    });
    adminApp.Run(async context =>
                         // => Terminal middleware (doesn't call next)
    {
        await context.Response.WriteAsync("Admin area");
                         // => Generate response
    });
});

app.MapGet("/", () => "Root endpoint");
                         // => Regular endpoint

class RequestLoggingMiddleware
                         // => Custom middleware class
{
    private readonly RequestDelegate _next;
                         // => Next middleware in pipeline
    public RequestLoggingMiddleware(RequestDelegate next)
    {
        _next = next;
                         // => Constructor receives next middleware
    }
    public async Task InvokeAsync(HttpContext context)
                         // => Called for each request
    {
        Console.WriteLine($"[{DateTime.UtcNow}] {context.Request.Method} {context.Request.Path}");
                         // => Log request details
        await _next(context);
                         // => Call next middleware
    }
}

app.UseMiddleware<RequestLoggingMiddleware>();
                         // => Register custom middleware class

app.Run(async context =>
                         // => Fallback middleware (terminal)
                         // => Handles requests not matched by earlier middleware
{
    context.Response.StatusCode = 404;
    await context.Response.WriteAsync("Not Found");
                         // => 404 response for unmatched routes
});

// app.Run();
                         // => Start server

// Example 79: Health Checks - Service Monitoring
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
                         // => Register health check services
    .AddCheck("self", () => HealthCheckResult.Healthy("API is running"))
                         // => Basic liveness check
    .AddCheck("database", () =>
                         // => Custom database health check
    {
        try
        {
            // Simulate database ping
            bool dbConnected = true;
                         // => Replace with actual database check
            return dbConnected
                ? HealthCheckResult.Healthy("Database is reachable")
                : HealthCheckResult.Unhealthy("Database is unreachable");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Database check failed", ex);
                         // => Include exception for debugging
        }
    })
    .AddCheck("external-api", () =>
                         // => External dependency check
    {
        // Simulate external API check
        return HealthCheckResult.Degraded("External API is slow");
                         // => Degraded: functional but impaired
    });

var app = builder.Build();

app.MapHealthChecks("/health");
                         // => Health check endpoint at /health
                         // => Returns 200 OK if healthy, 503 if unhealthy

app.MapHealthChecks("/health/ready", new HealthCheckOptions
                         // => Readiness probe for Kubernetes
{
    Predicate = check => check.Tags.Contains("ready"),
                         // => Only run checks tagged "ready"
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";
        var result = System.Text.Json.JsonSerializer.Serialize(new
        {
            status = report.Status.ToString(),
                         // => Overall status: Healthy/Degraded/Unhealthy
            checks = report.Entries.Select(e => new
            {
                name = e.Key,
                status = e.Value.Status.ToString(),
                description = e.Value.Description,
                duration = e.Value.Duration.TotalMilliseconds
            })
        });
        await context.Response.WriteAsync(result);
                         // => JSON response with detailed check results
    }
});

app.MapHealthChecks("/health/live", new HealthCheckOptions
                         // => Liveness probe (simpler)
{
    Predicate = _ => false
                         // => Don't run any checks (just return 200)
                         // => Confirms process is running
});

class DatabaseHealthCheck : IHealthCheck
                         // => Custom health check class
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            await Task.Delay(100, cancellationToken);
                         // => Simulate async database check
            return HealthCheckResult.Healthy("Database connection OK");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Database connection failed", ex);
        }
    }
}

builder.Services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database-v2", tags: new[] { "ready", "db" });
                         // => Register custom health check with tags

app.MapGet("/", () => "Use /health, /health/ready, /health/live for health checks");

// app.Run();

// Example responses:
// GET /health
// => Status: 200 OK (all checks pass)
// => Status: 503 Service Unavailable (any check fails)

// GET /health/ready (JSON response)
// {
//   "status": "Healthy",
//   "checks": [
//     {"name": "self", "status": "Healthy", "description": "API is running", "duration": 0.5},
//     {"name": "database", "status": "Healthy", "description": "Database is reachable", "duration": 15.2}
//   ]
// }