C# Advanced Concepts Showcase: Eagle Sight AI

This document breaks down the educational C# code example focused on advanced language features and popular libraries, all themed around an eagle's sharp vision.

1. C# 12 Features

Primary Constructors & Records

public record Prey(string Name, double Distance);
public record Eagle(string Name, int Acuity)
{
    public string Status { get; init; } = "Hunting";
}

Records provide a concise syntax for defining immutable data models. C# 12 primary constructors are used here directly in the class/record signature, reducing boilerplate code for initializing properties. The init keyword ensures the Status can only be set during object creation.

Collection Expressions

Prey[] preyList = [new("Fish", 120.5), new("Rabbit", 45.0)];

C# 12 introduced a unified, highly readable syntax [...] for initializing arrays, lists, and other collections, replacing older new[] or new List<T> initialization patterns.

2. Advanced Performance Features

Ref Structs & Span

public readonly ref struct SightBuffer
{
    public ReadOnlySpan<byte> Data { get; init; }
}

ref struct is used for high-performance, zero-allocation memory operations. They are strictly allocated on the stack. Paired with ReadOnlySpan<byte>, it allows the eagle AI to safely and efficiently read chunks of memory (like visual pixel data) without allocating new arrays on the heap.

3. Asynchronous Programming

Async Streams (IAsyncEnumerable)

public async IAsyncEnumerable<Prey> ScanSkyAsync()
{
    foreach (var prey in preyList)
    {
        await Task.Delay(10);
        yield return prey;
    }
}

Async streams allow you to yield multiple values asynchronously over time. This is perfect for simulating a continuous process, like an eagle scanning the ground and discovering prey one by one without blocking the main execution thread.

4. Pattern Matching

Switch Expressions & Property Patterns

public static string AssessTarget(Prey prey) => prey switch
{
    { Distance: < 50.0 } => "Immediate Strike",
    { Distance: <= 200.0 } => "Tracking Target",
    _ => "Out of Range"
};

This demonstrates C# 8+ pattern matching. It evaluates the Distance property of the Prey record directly within a terse switch expression, replacing a verbose if-else chain. The _ acts as the default discard case.

5. Popular Libraries Showcase

Data Access with Dapper

public async Task<Eagle?> GetEagleAsync(IDbConnection db, string name)
{
    string sql = """
        SELECT * FROM Eagles
        WHERE Name = @Name
        """;
    return await db.QueryFirstOrDefaultAsync<Eagle>(sql, new { Name = name });
}

Dapper is a lightweight, high-performance micro-ORM. This snippet shows an asynchronous query mapping database columns directly to the Eagle record. It also utilizes C# 11 Raw String Literals (""") to keep multi-line SQL queries clean without escape characters.

Resilience with Polly

public async Task<float[]> GetEmbeddingRetry(Func<Task<float[]>> aiCall)
{
    var policy = Policy.Handle<Exception>().RetryAsync(3);
    return await policy.ExecuteAsync(aiCall);
}

Polly is a library for transient fault handling. In this AI context, calling an external embedding model might fail due to network issues. Polly elegantly wraps the asynchronous function call in a policy that automatically retries up to 3 times if an exception is thrown.

6. AI & Math Integration

Vector Math

public static float CosineSimilarity(ReadOnlySpan<float> v1, ReadOnlySpan<float> v2)

A common operation in AI is comparing embeddings (vectors). This function calculates the cosine similarity between two spans of floats, representing how closely related two visual concepts are, mimicking the eagle's pattern recognition.

7. Testing with xUnit

[Fact]
public void Test_Target_Assessment()
{
    var target = new Prey("Mouse", 30.0);
    string act = EagleEyeAI.AssessTarget(target);
    Assert.Equal("Immediate Strike", act);
}

The file concludes with unit tests using the xUnit framework. [Fact] attributes denote individual test cases, and Assert methods verify that the AI logic (like target assessment distance thresholds) behaves exactly as expected.