C# Coding Standards

Goal: Write clean, secure ASP.NET Core code with proper authentication

Hot Reload Development Workflow

The backend runs in watch mode (dotnet watch run). When you edit C# code:

1. Save the file - .NET automatically recompiles
2. Check the terminal - Look for compilation output in the "Backend: ASP.NET Core API" terminal
3. Verify via console logs - New requests will use updated code immediately

VS Code Tasks (use Run Task command or check terminal panel):

• Backend: ASP.NET Core API - Runs dotnet watch run with live recompilation
• Logs are visible directly in VS Code terminal

No restart needed - Just edit, save, and test. Watch for compilation errors in the terminal.

Testing changes: Use Playwright browser tools to make requests and check browser console logs, or call endpoints directly.

Minimal API Patterns

Use typed request models, CancellationToken, and IHostEnvironment:

app.MapPost("/api/endpoint", async (
    RequestModel request,
    MyService service,
    IHostEnvironment env,
    CancellationToken cancellationToken) =>
{
    try
    {
        var result = await service.ProcessAsync(request, cancellationToken);
        return Results.Ok(result);
    }
    catch (Exception ex)
    {
        return ErrorResponseFactory.CreateFromException(ex, env);
    }
})
.RequireAuthorization("RequireChatScope")
.WithName("EndpointName");

Authentication Setup

JWT Bearer with Entra ID:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.ValidAudiences = new[]
        {
            builder.Configuration["AzureAd:ClientId"],
            $"api://{builder.Configuration["AzureAd:ClientId"]}"
        };
    }, options => builder.Configuration.Bind("AzureAd", options));

Async Best Practices

// ✅ Use async/await with CancellationToken
public async Task<Result> ProcessAsync(Request req, CancellationToken ct)
{
    return await _service.ExecuteAsync(req, ct);
}

// ❌ Never block on async
var result = _service.ExecuteAsync(req).Result;  // WRONG

IAsyncEnumerable for Streaming

public async IAsyncEnumerable<string> StreamAsync(
    string input,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    await foreach (var chunk in source.WithCancellation(cancellationToken))
    {
        yield return chunk;
    }
}

Credential Strategy

TokenCredential credential = env.IsDevelopment()
    ? new ChainedTokenCredential(
        new AzureCliCredential(),
        new AzureDeveloperCliCredential())  // Supports 'azd auth login'
    : new ManagedIdentityCredential(miClientId); // User-assigned MI in production

Why ChainedTokenCredential: Avoids DefaultAzureCredential's "fail fast" mode issues. Explicit, predictable credential chain.

IDisposable Pattern

public class MyService : IDisposable
{
    private readonly SemaphoreSlim _lock = new(1, 1);
    private readonly CancellationTokenSource _disposeCts = new();
    private bool _disposed;

    public void DoWork()
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
        // ...
    }

    public void Dispose()
    {
        if (_disposed) return;
        _disposed = true;
        
        // Cancel pending operations first
        try { _disposeCts.Cancel(); }
        catch (ObjectDisposedException) { }
        
        _disposeCts.Dispose();
        _lock.Dispose();
    }
}

Error Responses (RFC 7807)

Use ErrorResponseFactory.CreateFromException() for consistent error responses.

See: backend/WebApp.Api/Models/ErrorResponse.cs

Common Mistakes

• ❌ Using .Result or .Wait() on async methods
• ❌ Forgetting CancellationToken parameter
• ❌ Missing .RequireAuthorization() on endpoints
• ❌ Exposing internal errors in production
• ❌ Forgetting disposal guards in IDisposable

Project-Specific: Middleware Pipeline

Goal: Serve static files → validate auth → route APIs → SPA fallback

app.UseDefaultFiles();     // index.html for /
app.UseStaticFiles();      // wwwroot/* assets  
app.UseCors();             // Dev only
app.UseAuthentication();   // Validate JWT
app.UseAuthorization();    // Enforce scope
// Map endpoints here
app.MapFallbackToFile("index.html");  // MUST BE LAST

Project-Specific: AgentFrameworkService

See: backend/WebApp.Api/Services/AgentFrameworkService.cs

SDK Packages:

• Azure.AI.Projects — Main entry point, v2 Agents API (see *.csproj for version)
• Azure.AI.Projects.Agents — ProjectsAgentVersion, DeclarativeAgentDefinition, AgentAdministrationClient
• Azure.AI.Extensions.OpenAI — ProjectOpenAIClient, ProjectConversationsClient, ProjectResponsesClient

Sub-namespaces: Azure.AI.Projects.Agents, Azure.AI.Extensions.OpenAI, OpenAI.Responses

Key patterns:

• IDisposable implementation
• Disposal guards (ObjectDisposedException.ThrowIf) in all public methods
• Environment-aware credential selection (ChainedTokenCredential vs ManagedIdentityCredential vs OnBehalfOfCredential)
• Static-cached ProjectsAgentVersion resolved once per process via SemaphoreSlim
• Configuration validation (AI_AGENT_ENDPOINT, AI_AGENT_ID, optional AI_AGENT_VERSION)

Agent Loading (direct SDK):

// Load agent metadata directly from v2 Agents API.
// NOTE: the REST spec has no "latest" keyword — the agent_version path parameter is a
// plain string. To resolve the newest version, enumerate versions in descending order
// and take the first. Pin a specific version by passing its id to GetAgentVersionAsync.
ProjectsAgentVersion? agentVersion = null;
await foreach (var v in projectClient.AgentAdministrationClient.GetAgentVersionsAsync(
    agentName: agentId,
    limit: 1,
    order: AgentListOrder.Descending,
    after: null,
    before: null,
    cancellationToken: ct))
{
    agentVersion = v;
    break;
}

// Access definition for model/instructions/structured inputs
var definition = agentVersion?.Definition as DeclarativeAgentDefinition;

Streaming (direct ProjectResponsesClient — required for specialized types):

// Direct SDK for streaming — IChatClient doesn't expose MCP/annotations.
// Pin to the resolved agentVersion.Version so streaming and metadata stay in sync.
ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(
    new AgentReference(agentId, agentVersion.Version), conversationId);

Why direct streaming? The IChatClient abstraction doesn't expose:

• McpToolCallApprovalRequestItem for MCP approval flows
• FileSearchCallResponseItem for file search quotes
• MessageResponseItem.OutputTextAnnotations for citations

Streaming Pattern: Returns IAsyncEnumerable<StreamChunk> where StreamChunk contains either:

• Text delta (chunk.IsText, chunk.TextDelta)
• Annotations/citations (chunk.HasAnnotations, chunk.Annotations)

Streaming Response Types (from OpenAI.Responses):

• StreamingResponseOutputTextDeltaUpdate - Text content delta
• StreamingResponseOutputItemDoneUpdate - Item completion (has annotations)
• StreamingResponseCompletedUpdate - Response completion with usage stats

Image Validation (in BuildUserMessage()):

• Maximum 5 images per request
• Maximum 5MB per image (decoded size)
• Allowed: image/png, image/jpeg, image/gif, image/webp
• Returns HTTP 400 with validation details if constraints violated

Annotation Types (from OpenAI.Responses):

• UriCitationMessageAnnotation - Bing, Azure AI Search, SharePoint
• FileCitationMessageAnnotation - File search (vector stores)
• FilePathMessageAnnotation - Code interpreter output
• ContainerFileCitationMessageAnnotation - Container file citations

Starter Prompts: Parsed from agent metadata (starterPrompts key, newline-separated).

Project-Specific: Configuration Loading

Auto-load .env file before building configuration:

var envFile = Path.Combine(Directory.GetCurrentDirectory(), ".env");
if (File.Exists(envFile))
{
    foreach (var line in File.ReadAllLines(envFile)
        .Where(l => !string.IsNullOrWhiteSpace(l) && !l.StartsWith("#")))
    {
        var parts = line.Split('=', 2);
        if (parts.Length == 2)
            Environment.SetEnvironmentVariable(parts[0].Trim(), parts[1].Trim());
    }
}

Troubleshooting SDK Issues

When things break: SDK type mismatches and missing methods almost always happen after a package upgrade. Check backend/WebApp.Api/WebApp.Api.csproj for current versions:

• Azure.AI.Projects - check WebApp.Api.csproj for current version
• Azure.Identity - check WebApp.Api.csproj for current version

If types don't match documentation or samples, verify you're looking at docs for the same version installed in the project.

GitHub SDK Source (For Deep Dives)

When you need to understand SDK internals, fetch the actual source:

• Azure.AI.Projects: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/src
• SDK samples: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent/samples
• OpenAI.Responses: https://github.com/openai/openai-dotnet/tree/main/src

Quick Structure Checks (CLI)

For project-level overviews only—use sparingly:

# List public types in backend (overview, not deep exploration)
Get-ChildItem -Path backend -Recurse -Include *.cs | 
    Select-String -Pattern "^\s*(public|internal)\s+(class|record|interface)\s+(\w+)" |
    ForEach-Object { $_.Matches.Groups[3].Value } | Sort-Object -Unique

# Find IDisposable implementations
Get-ChildItem -Path backend -Recurse -Include *.cs |
    Select-String -Pattern ":\s*.*IDisposable"

Use for: Quick inventory of what exists. Follow up with pattern search or IDE navigation for understanding.

PowerShell Reflection for .NET Assemblies

Use when you need to discover exact type members on any .NET assembly (especially beta SDKs):

# 1. Build first to ensure DLLs are current
cd backend/WebApp.Api; dotnet build --no-restore

# 2. Find and load any assembly by name
$dll = Get-ChildItem -Path "bin/Debug" -Recurse -Filter "SomePackage.dll" | Select-Object -First 1
$asm = [System.Reflection.Assembly]::LoadFrom($dll.FullName)

# 3. Inspect a specific type's properties
$type = $asm.GetType("SomeNamespace.SomeClass")
Write-Host "Type: $($type.FullName)"
Write-Host "Assembly: $($asm.GetName().Name) v$($asm.GetName().Version)"
$type.GetProperties() | ForEach-Object { Write-Host "  $($_.PropertyType.Name) $($_.Name)" }

# 4. Check base type for inherited members
Write-Host "Base: $($type.BaseType.Name)"
$type.BaseType.GetProperties() | ForEach-Object { Write-Host "    $($_.PropertyType.Name) $($_.Name)" }

Finding types by pattern (when you don't know exact namespace):

# Search for types matching a pattern
$asm.GetTypes() | Where-Object { $_.Name -like "*Response*" } | ForEach-Object { Write-Host $_.FullName }

# Find methods on a type
$type.GetMethods() | Where-Object { $_.Name -like "*Async*" } | Select-Object Name, ReturnType

Common assemblies to inspect (after dotnet build):

When to use: Beta SDK properties aren't in docs, IDE tooltips are incomplete, or you need to verify a type's actual API surface.

Limitation: Returns raw API surface without intent or usage guidance. Combine with GitHub source for context.

Related Skills

• implementing-chat-streaming - SSE streaming patterns and backend endpoint implementation
• troubleshooting-authentication - MSAL/JWT debugging for 401 errors
• researching-azure-ai-sdk - SDK research workflow and sample repositories