Writing Csharp Code

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).