Intermediate

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
// => Registers controller infrastructure: routing, binding, validation, formatters
var app = builder.Build();
app.MapControllers();
app.Run();

// Controller class in separate file
[ApiController]
// => [ApiController] enables:
// => - Automatic 400 for validation failures (no ModelState.IsValid check needed)
// => - Binding source inference ([FromBody] inferred for complex types)
// => - Problem details for 400/404 responses
[Route("api/[controller]")]
// => [controller] token replaced with class name minus "Controller" suffix
// => => Route is "api/products"
public class ProductsController : ControllerBase
{
    // ControllerBase - base class without view support (API-only)
    // Controller - base class with view support (not needed for JSON APIs)

    private readonly ILogger<ProductsController> _logger;

    public ProductsController(ILogger<ProductsController> logger)
    {
        _logger = logger;
        // => Constructor injection - DI resolves ILogger automatically
    }

    [HttpGet]
    // => Maps GET api/products
    public IActionResult GetAll()
    {
        var products = new[] { new { Id = 1, Name = "Widget" } };
        return Ok(products);
        // => Ok() returns 200 with JSON body (inherited from ControllerBase)
    }

    [HttpGet("{id:int}")]
    // => Maps GET api/products/42
    [ProducesResponseType<Product>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    // => [ProducesResponseType] documents possible response types for OpenAPI
    public ActionResult<Product> GetById(int id)
    {
        // => ActionResult<T> allows returning T directly or an ActionResult
        if (id > 1000) return NotFound();
        // => NotFound() returns 404 Not Found
        return new Product { Id = id, Name = $"Product {id}" };
        // => Returning T directly wraps in 200 OK ActionResult
    }

    [HttpPost]
    public ActionResult<Product> Create([FromBody] Product product)
    {
        // => [FromBody] explicit but inferred by [ApiController] for complex types
        product = product with { Id = 42 };
        // => with expression: copy record with Id changed to 42
        return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
        // => CreatedAtAction: 201 Created + Location: /api/products/42
    }
}

public record Product
{
    public int Id { get; init; }
    public string Name { get; init; } = "";
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

// Custom action filter as an attribute
public class RequestLoggingFilterAttribute : ActionFilterAttribute
{
    // ActionFilterAttribute implements IActionFilter (sync) and IAsyncActionFilter (async)

    public override void OnActionExecuting(ActionExecutingContext context)
    {
        // => Called BEFORE the action method runs
        // => context.ActionArguments contains bound parameters
        // => context.HttpContext has the full request
        var method = context.HttpContext.Request.Method;
        var path = context.HttpContext.Request.Path;
        Console.WriteLine($"[BEFORE] {method} {path}");
        // => Output: [BEFORE] GET /api/products/42

        // Short-circuit: set Result to skip action execution
        // context.Result = new BadRequestResult();
        // => If set here, action method never runs
    }

    public override void OnActionExecuted(ActionExecutedContext context)
    {
        // => Called AFTER the action method runs
        // => context.Result contains the action's return value
        // => context.Exception has exception if action threw
        var statusCode = (context.Result as ObjectResult)?.StatusCode;
        Console.WriteLine($"[AFTER] Status: {statusCode}");
        // => Output: [AFTER] Status: 200
    }
}

// Endpoint filter for minimal APIs (similar to action filter)
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();

// Endpoint filter on a single route
app.MapGet("/api/data", () => Results.Ok("data"))
    .AddEndpointFilter(async (context, next) =>
    {
        // => Endpoint filter wraps minimal API handlers
        Console.WriteLine("Before handler");
        // => Runs before the route handler
        var result = await next(context);
        // => Calls the actual route handler
        Console.WriteLine("After handler");
        // => Runs after the handler returns
        return result;
    });

app.MapControllers();
app.Run();

// Apply filter to controller or action
[ApiController]
[Route("api/[controller]")]
[RequestLoggingFilter] // => Applies to all actions in this controller
public class OrdersController : ControllerBase
{
    [HttpGet("{id:int}")]
    [RequestLoggingFilter] // => Can also apply to specific action
    public IActionResult GetOrder(int id) => Ok(new { Id = id });
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

// Result filter - transforms response before serialization
public class ApiResponseWrapperFilter : IResultFilter
{
    public void OnResultExecuting(ResultExecutingContext context)
    {
        // => Called BEFORE result is serialized and written to response
        if (context.Result is ObjectResult objectResult)
        {
            // => Wrap successful responses in a standard envelope
            objectResult.Value = new
            {
                Success = true,
                Data = objectResult.Value,
                Timestamp = DateTime.UtcNow
            };
            // => Transform: {"id":1} => {"success":true,"data":{"id":1},"timestamp":"..."}
        }
    }

    public void OnResultExecuted(ResultExecutedContext context)
    {
        // => Called AFTER result is written to response
        // => Response has been sent; cannot modify it here
    }
}

// Exception filter - catches exceptions from controller scope
public class ValidationExceptionFilterAttribute : ExceptionFilterAttribute
{
    public override void OnException(ExceptionContext context)
    {
        if (context.Exception is ArgumentException argEx)
        {
            // => Catch ArgumentException and return 400
            context.Result = new BadRequestObjectResult(new
            {
                Error = argEx.Message
                // => argEx.Message is the exception message string
            });
            context.ExceptionHandled = true;
            // => ExceptionHandled = true prevents further exception propagation
            // => Without this, exception bubbles up to global handler
        }
        // => Unhandled exception types bubble to UseExceptionHandler
    }
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers(options =>
{
    options.Filters.Add<ApiResponseWrapperFilter>();
    // => Global filter applies to ALL controller actions
    // => Registered by type - DI resolves dependencies
});
var app = builder.Build();
app.MapControllers();
app.Run();

[ApiController]
[Route("api/[controller]")]
[ValidationExceptionFilter] // => Exception filter scoped to this controller
public class DataController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(string id)
    {
        if (id == "invalid")
            throw new ArgumentException("ID cannot be 'invalid'");
        // => ValidationExceptionFilter catches this => 400 Bad Request
        return Ok(new { Id = id });
        // => ApiResponseWrapperFilter wraps this => {"success":true,"data":{"id":"..."}}
    }
}

// Install: dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

// JWT configuration from appsettings.json
var jwtKey = builder.Configuration["Jwt:Key"] ?? "dev-key-minimum-32-chars-long!!";
// => Use a strong secret key (256+ bits) in production
// => Never hardcode in source; use secrets management

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    // => Sets JWT Bearer as the default authentication scheme
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            // => Verify token was signed with our secret key
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtKey)),
            // => Secret key for HMAC-SHA256 signing
            ValidateIssuer = true,
            ValidIssuer = "https://api.myapp.com",
            // => Token must have matching iss claim
            ValidateAudience = true,
            ValidAudience = "myapp-clients",
            // => Token must have matching aud claim
            ValidateLifetime = true,
            // => Reject expired tokens (checks exp claim)
            ClockSkew = TimeSpan.FromMinutes(1)
            // => Allow 1-minute clock difference between servers
        };
    });

builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication(); // => Must be before UseAuthorization
app.UseAuthorization();

// Login endpoint - generates JWT
app.MapPost("/auth/login", (LoginRequest request) =>
{
    // => In production: verify password hash against database
    if (request.Username != "alice" || request.Password != "secret")
        return Results.Unauthorized();
    // => Returns 401 if credentials invalid

    var claims = new[]
    {
        new Claim(ClaimTypes.NameIdentifier, "user-123"),
        // => Subject claim - user's unique identifier
        new Claim(ClaimTypes.Name, request.Username),
        // => Name claim - display name
        new Claim(ClaimTypes.Role, "user"),
        // => Role claim - used by [Authorize(Roles = "admin")]
    };

    var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(jwtKey));
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
    // => HMAC-SHA256 signing algorithm

    var token = new JwtSecurityToken(
        issuer: "https://api.myapp.com",
        audience: "myapp-clients",
        claims: claims,
        expires: DateTime.UtcNow.AddHours(1),
        // => Token valid for 1 hour
        signingCredentials: creds
    );

    var tokenString = new JwtSecurityTokenHandler().WriteToken(token);
    // => tokenString = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    return Results.Ok(new { Token = tokenString });
});

// Protected endpoint requiring authentication
app.MapGet("/profile", (ClaimsPrincipal user) =>
{
    // => ClaimsPrincipal injected when UseAuthentication is configured
    // => Contains claims from validated JWT
    var userId = user.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    // => userId = "user-123" from JWT claim
    var username = user.FindFirst(ClaimTypes.Name)?.Value;
    // => username = "alice"
    return Results.Ok(new { UserId = userId, Username = username });
})
.RequireAuthorization();
// => .RequireAuthorization() applies [Authorize] equivalent to minimal API route
// => Returns 401 if no valid JWT provided

record LoginRequest(string Username, string Password);

app.Run();

using Microsoft.AspNetCore.Authentication.Cookies;
using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.Cookie.Name = ".AppAuth";
        // => Cookie name visible in browser dev tools
        options.Cookie.HttpOnly = true;
        // => HttpOnly prevents JavaScript from reading the cookie
        // => Critical security setting - prevents XSS token theft
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        // => Secure flag - cookie only sent over HTTPS
        // => Use CookieSecurePolicy.SameAsRequest in development
        options.Cookie.SameSite = SameSiteMode.Lax;
        // => Lax: sent on same-site requests and top-level navigations
        // => Strict: only same-site requests (breaks OAuth redirects)
        options.SlidingExpiration = true;
        // => Reset expiration on each authenticated request
        // => Keeps active users logged in
        options.ExpireTimeSpan = TimeSpan.FromHours(8);
        // => Cookie expires after 8 hours of inactivity (with sliding)
        options.LoginPath = "/login";
        // => Redirect unauthenticated requests to /login
        options.AccessDeniedPath = "/access-denied";
        // => Redirect authorized-but-forbidden requests here
    });

builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapPost("/login", async (LoginRequest request, HttpContext context) =>
{
    // => In production: validate against database
    if (request.Username != "alice" || request.Password != "secret")
        return Results.Redirect("/login?error=1");

    var claims = new List<Claim>
    {
        new(ClaimTypes.NameIdentifier, "user-123"),
        new(ClaimTypes.Name, request.Username),
        new(ClaimTypes.Role, "user")
    };

    var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
    // => ClaimsIdentity creates an identity for the given scheme
    var principal = new ClaimsPrincipal(identity);
    // => ClaimsPrincipal wraps one or more identities

    await context.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, principal);
    // => SignInAsync creates the encrypted auth cookie and sets it in response
    // => Cookie: .AppAuth=CfDJ8... (encrypted, tamper-proof)

    return Results.Redirect("/dashboard");
});

app.MapPost("/logout", async (HttpContext context) =>
{
    await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    // => SignOutAsync clears the auth cookie from response
    return Results.Redirect("/login");
});

app.MapGet("/dashboard", (ClaimsPrincipal user) =>
    Results.Ok(new { Message = $"Welcome, {user.Identity?.Name}" }))
    .RequireAuthorization();
// => Returns 401/redirect to /login if not authenticated

record LoginRequest(string Username, string Password);
app.Run();

using Microsoft.AspNetCore.Authorization;

// Custom authorization requirement
public class MinimumAgeRequirement : IAuthorizationRequirement
{
    public int MinimumAge { get; }
    public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
    // => MinimumAge stored as requirement parameter
}

// Handler that evaluates the requirement against the user
public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        MinimumAgeRequirement requirement)
    {
        var ageClaim = context.User.FindFirst("age");
        // => Look for "age" claim in user's JWT or cookie identity
        if (ageClaim is not null && int.TryParse(ageClaim.Value, out int age))
        {
            if (age >= requirement.MinimumAge)
            {
                context.Succeed(requirement);
                // => Succeed marks this requirement as met
                // => All requirements must succeed for policy to pass
            }
        }
        // => If Succeed not called, requirement is not met
        return Task.CompletedTask;
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
    // AddAuthorizationBuilder: fluent API for policy registration

    .AddPolicy("AdminOnly", policy =>
        policy.RequireRole("admin"))
    // => RequireRole checks ClaimTypes.Role claim

    .AddPolicy("ActiveUser", policy =>
        policy.RequireClaim("status", "active"))
    // => RequireClaim checks for specific claim with specific value

    .AddPolicy("AdultContent", policy =>
        policy.Requirements.Add(new MinimumAgeRequirement(18)))
    // => Custom requirement evaluated by MinimumAgeHandler

    .AddPolicy("PremiumApi", policy =>
        policy.RequireAuthenticatedUser()
              .RequireRole("premium", "enterprise")
              .RequireClaim("subscription", "active"));
    // => Chain multiple requirements - all must pass

builder.Services.AddScoped<IAuthorizationHandler, MinimumAgeHandler>();
// => Register handler - DI resolves it when policy is evaluated
builder.Services.AddAuthentication().AddJwtBearer(/* options */);

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/admin", () => "Admin area")
    .RequireAuthorization("AdminOnly");
// => Only users with role "admin" can access

app.MapGet("/adult-content", () => "Adult content")
    .RequireAuthorization("AdultContent");
// => Only users with age claim >= 18 can access

app.MapGet("/premium-api", () => "Premium API response")
    .RequireAuthorization("PremiumApi");
// => Must be authenticated + premium/enterprise role + active subscription

app.Run();

// Install: dotnet add package Microsoft.EntityFrameworkCore.SqlServer
// Or: dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
using Microsoft.EntityFrameworkCore;

// Entity class - maps to a database table
public class Product
{
    public int Id { get; set; }
    // => By convention, Id is the primary key (EF Core convention)
    public string Name { get; set; } = "";
    // => Required: non-nullable string maps to NOT NULL column
    public decimal Price { get; set; }
    // => decimal maps to SQL decimal(18,2) by default
    public bool IsActive { get; set; } = true;
    // => Default value set in entity; also set in migration
    public DateTime CreatedAt { get; set; }
    // => DateTime maps to datetime2 (SQL Server) or timestamp (PostgreSQL)
}

// DbContext - unit of work for EF Core
public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options)
    {
        // => Pass options from DI to base DbContext
        // => options contains connection string and provider configuration
    }

    public DbSet<Product> Products { get; set; }
    // => DbSet<T> represents the Products table
    // => Provides LINQ query, Add, Update, Remove operations

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // => Fluent API configuration - runs once when model is built
        modelBuilder.Entity<Product>(entity =>
        {
            entity.Property(p => p.Name)
                .HasMaxLength(200)
                // => Maps to NVARCHAR(200) / VARCHAR(200)
                .IsRequired();
                // => NOT NULL constraint

            entity.Property(p => p.Price)
                .HasColumnType("decimal(10,2)");
                // => Explicit decimal precision: 10 digits, 2 after point

            entity.HasIndex(p => p.Name)
                .IsUnique();
            // => Unique index on Name column
        });
    }
}

var builder = WebApplication.CreateBuilder(args);

// Register DbContext with PostgreSQL
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));
// => AddDbContext registers AppDbContext as Scoped by default
// => Scoped: one DbContext instance per HTTP request (prevents threading issues)
// => Connection string from appsettings.json: "ConnectionStrings": {"DefaultConnection": "..."}

var app = builder.Build();

// Apply migrations on startup (development helper - use CI/CD in production)
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
    // => Applies pending migrations to the database
    // => Creates database if it does not exist
}

app.Run();

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseInMemoryDatabase("TestDb")); // In-memory for demo; use real DB in production
var app = builder.Build();

// CREATE - add a new entity
app.MapPost("/products", async (Product product, AppDbContext db) =>
{
    product.CreatedAt = DateTime.UtcNow;
    // => Set server-side timestamp before saving
    db.Products.Add(product);
    // => Marks entity as Added in change tracker
    // => No SQL executed yet
    await db.SaveChangesAsync();
    // => Executes INSERT INTO Products ... SQL
    // => product.Id is populated by database after insert
    return Results.Created($"/products/{product.Id}", product);
    // => product.Id = database-assigned identity value (e.g., 1)
});

// READ ALL - return all records
app.MapGet("/products", async (AppDbContext db) =>
{
    var products = await db.Products
        .Where(p => p.IsActive)
        // => Adds WHERE IsActive = true to SQL
        .OrderBy(p => p.Name)
        // => Adds ORDER BY Name to SQL
        .ToListAsync();
        // => Executes SQL and materializes result into List<Product>
    return Results.Ok(products);
});

// READ ONE - find by primary key
app.MapGet("/products/{id:int}", async (int id, AppDbContext db) =>
{
    var product = await db.Products.FindAsync(id);
    // => FindAsync checks identity map first (no SQL if already tracked)
    // => If not tracked: SELECT ... WHERE Id = @id
    return product is null ? Results.NotFound() : Results.Ok(product);
    // => Results.NotFound() returns 404, Results.Ok(product) returns 200
});

// UPDATE - modify existing entity
app.MapPut("/products/{id:int}", async (int id, Product updated, AppDbContext db) =>
{
    var product = await db.Products.FindAsync(id);
    if (product is null) return Results.NotFound();

    product.Name = updated.Name;
    product.Price = updated.Price;
    // => Modifying tracked entity properties marks them as Modified
    // => Change tracker records only changed properties

    await db.SaveChangesAsync();
    // => Executes UPDATE Products SET Name=@name, Price=@price WHERE Id=@id
    return Results.Ok(product);
});

// DELETE - remove entity
app.MapDelete("/products/{id:int}", async (int id, AppDbContext db) =>
{
    var product = await db.Products.FindAsync(id);
    if (product is null) return Results.NotFound();

    db.Products.Remove(product);
    // => Marks entity as Deleted in change tracker
    await db.SaveChangesAsync();
    // => Executes DELETE FROM Products WHERE Id=@id
    return Results.NoContent();
});

app.Run();

using Microsoft.EntityFrameworkCore;

// Entities with a one-to-many relationship
public class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public List<Product> Products { get; set; } = new();
    // => Navigation property - EF Core loads related products
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    public int CategoryId { get; set; }
    // => Foreign key - convention: navigation property name + "Id"
    public Category? Category { get; set; }
    // => Navigation property for the parent category
}

public class ShopDbContext : DbContext
{
    public ShopDbContext(DbContextOptions<ShopDbContext> opt) : base(opt) {}
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Category> Categories => Set<Category>();
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ShopDbContext>(opt => opt.UseInMemoryDatabase("Shop"));
var app = builder.Build();

// Include - eager load related entities
app.MapGet("/categories/{id:int}/products", async (int id, ShopDbContext db) =>
{
    var category = await db.Categories
        .Include(c => c.Products)
        // => Include generates JOIN to load Products with Category
        // => Without Include: c.Products would be null (lazy loading off by default)
        .FirstOrDefaultAsync(c => c.Id == id);
        // => FirstOrDefaultAsync executes SQL and returns null if not found
    return category is null ? Results.NotFound() : Results.Ok(category);
});

// Projection - select specific fields to avoid over-fetching
app.MapGet("/products/summary", async (ShopDbContext db) =>
{
    var summaries = await db.Products
        .Select(p => new
        {
            p.Id,
            p.Name,
            CategoryName = p.Category!.Name
            // => Navigates to related Category in projection
            // => EF Core generates JOIN automatically for this projection
        })
        .ToListAsync();
    // => SQL: SELECT p.Id, p.Name, c.Name FROM Products p JOIN Categories c ON p.CategoryId = c.Id
    return Results.Ok(summaries);
});

// Filtering, ordering, pagination
app.MapGet("/products", async (
    string? search,
    decimal? minPrice,
    int page = 1,
    int pageSize = 20,
    ShopDbContext db) =>
{
    var query = db.Products.AsQueryable();
    // => AsQueryable() allows conditional query building

    if (search is not null)
        query = query.Where(p => EF.Functions.Like(p.Name, $"%{search}%"));
    // => EF.Functions.Like generates SQL LIKE operator
    // => Translates to: WHERE Name LIKE '%widget%'

    if (minPrice.HasValue)
        query = query.Where(p => p.Price >= minPrice.Value);
    // => Conditions are chained - all applied in one SQL query

    var total = await query.CountAsync();
    // => COUNT(*) query before pagination for total count
    var items = await query
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync();
    // => OFFSET/FETCH NEXT for pagination
    // => (page=2, pageSize=20) => OFFSET 20 ROWS FETCH NEXT 20 ROWS ONLY

    return Results.Ok(new { Total = total, Items = items, Page = page });
});

app.Run();

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder(args);

// Configure upload limits
builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 50 * 1024 * 1024; // 50MB
    // => Maximum allowed total multipart body size
    // => Default is 128MB; reduce for tighter control
});

var app = builder.Build();

// Single file upload
app.MapPost("/upload", async (IFormFile file) =>
{
    // => IFormFile represents an uploaded file in a multipart request
    // => Content-Type: multipart/form-data; boundary=...

    if (file.Length == 0)
        return Results.BadRequest("Empty file");

    if (file.Length > 10 * 1024 * 1024) // 10MB
        return Results.BadRequest("File exceeds 10MB limit");

    var allowedTypes = new[] { "image/jpeg", "image/png", "application/pdf" };
    if (!allowedTypes.Contains(file.ContentType))
        return Results.BadRequest($"File type {file.ContentType} not allowed");
    // => Validate Content-Type header (client-provided, can be spoofed)
    // => Also validate file magic bytes in production

    // Generate safe filename - never use client-provided filename directly
    var extension = Path.GetExtension(file.FileName).ToLowerInvariant();
    // => extension = ".jpg" (from FileName like "photo.jpg")
    var safeFilename = $"{Guid.NewGuid()}{extension}";
    // => safeFilename = "3fa85f64-5717-4562-b3fc-2c963f66afa6.jpg"
    // => GUID prevents path traversal and collision attacks

    var uploadsPath = Path.Combine("uploads", safeFilename);
    Directory.CreateDirectory("uploads"); // Ensure directory exists

    using var stream = File.Create(uploadsPath);
    await file.CopyToAsync(stream);
    // => CopyToAsync writes file content to disk asynchronously
    // => using ensures stream is disposed (file handle released)

    return Results.Ok(new
    {
        FileName = safeFilename,
        OriginalName = file.FileName,
        // => file.FileName is the client-provided name (for display only)
        ContentType = file.ContentType,
        Size = file.Length
    });
    // => Response: {"fileName":"3fa8....jpg","originalName":"photo.jpg","size":45678}
});

// Multiple file upload
app.MapPost("/upload/multiple", async (IFormFileCollection files) =>
{
    // => IFormFileCollection binds all files from multipart form
    var results = new List<object>();

    foreach (var file in files)
    {
        if (file.Length > 0)
        {
            var filename = $"{Guid.NewGuid()}{Path.GetExtension(file.FileName)}";
            using var stream = File.Create(Path.Combine("uploads", filename));
            await file.CopyToAsync(stream);
            results.Add(new { filename, file.ContentType, file.Length });
        }
    }

    return Results.Ok(results);
});

app.Run();

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors(options =>
{
    // Named policy for development - permissive
    options.AddPolicy("DevelopmentPolicy", policy =>
        policy.WithOrigins("http://localhost:3000", "http://localhost:4200")
        // => WithOrigins explicitly allows listed origins
        // => Avoids AllowAnyOrigin which can expose APIs to malicious sites
              .AllowAnyMethod()
        // => Allows GET, POST, PUT, DELETE, PATCH, OPTIONS
              .AllowAnyHeader()
        // => Allows all request headers including custom ones
              .AllowCredentials());
    // => AllowCredentials allows cookies and auth headers
    // => CANNOT combine with AllowAnyOrigin - security restriction

    // Named policy for production - restrictive
    options.AddPolicy("ProductionPolicy", policy =>
        policy.WithOrigins("https://app.mycompany.com", "https://admin.mycompany.com")
        // => Explicitly enumerate production origins
              .WithMethods("GET", "POST", "PUT", "DELETE")
        // => Enumerate allowed verbs
              .WithHeaders("Content-Type", "Authorization", "X-Request-Id")
        // => Enumerate allowed headers
              .SetPreflightMaxAge(TimeSpan.FromHours(1)));
    // => Cache preflight OPTIONS response for 1 hour
    // => Reduces preflight requests for complex CORS scenarios
});

var app = builder.Build();

// Apply CORS policy based on environment
if (app.Environment.IsDevelopment())
    app.UseCors("DevelopmentPolicy");
else
    app.UseCors("ProductionPolicy");

// Per-endpoint CORS override
app.MapGet("/public-data", () => "Public data accessible to any origin")
    .RequireCors(policy => policy.AllowAnyOrigin().AllowAnyMethod());
// => Override global policy for specific public endpoints

app.MapGet("/private-data", () => "Private data - restricted to configured origins")
    .RequireAuthorization();
// => Global CORS policy applies here

app.Run();

using System.Net.WebSockets;
using System.Text;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Enable WebSocket support
app.UseWebSockets(new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromSeconds(30)
    // => Send ping frames every 30 seconds to detect dead connections
    // => Prevents silent connection drops from firewalls and load balancers
});

// Simple echo WebSocket server
app.MapGet("/ws", async (HttpContext context) =>
{
    if (!context.WebSockets.IsWebSocketRequest)
    {
        context.Response.StatusCode = 400;
        // => Reject non-WebSocket requests on this endpoint
        return;
    }

    using var ws = await context.WebSockets.AcceptWebSocketAsync();
    // => AcceptWebSocketAsync upgrades HTTP to WebSocket connection
    // => Returns WebSocket object for send/receive operations

    Console.WriteLine("WebSocket connected");
    // => A new WebSocket connection is established

    var buffer = new byte[1024 * 4]; // 4KB receive buffer

    while (ws.State == WebSocketState.Open)
    {
        var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
        // => ReceiveAsync waits for next message from client
        // => result.MessageType: Text, Binary, or Close

        if (result.MessageType == WebSocketMessageType.Close)
        {
            await ws.CloseAsync(WebSocketCloseStatus.NormalClosure, "Closing", CancellationToken.None);
            // => CloseAsync sends close frame and waits for acknowledgment
            Console.WriteLine("WebSocket closed cleanly");
        }
        else if (result.MessageType == WebSocketMessageType.Text)
        {
            var message = Encoding.UTF8.GetString(buffer, 0, result.Count);
            // => Decode received bytes to string
            // => message = "Hello from client"
            Console.WriteLine($"Received: {message}");

            var echo = $"Echo: {message}";
            var echoBytes = Encoding.UTF8.GetBytes(echo);
            await ws.SendAsync(
                new ArraySegment<byte>(echoBytes),
                WebSocketMessageType.Text,
                endOfMessage: true,
                CancellationToken.None);
            // => SendAsync sends text frame back to client
            // => endOfMessage: true - this is the complete message (not fragmented)
        }
    }
    // => Loop exits when connection closes or errors
});

app.Run();

using Microsoft.AspNetCore.SignalR;

// Hub class - defines server-side methods clients can call,
// and client-side methods the server can invoke
public class ChatHub : Hub
{
    // Server-side method - clients call this via hub proxy
    public async Task SendMessage(string user, string message)
    {
        // => Clients.All broadcasts to every connected client
        await Clients.All.SendAsync("ReceiveMessage", user, message);
        // => "ReceiveMessage" matches method name in client JS code
        // => All connected clients receive this message
        // => JavaScript: connection.on("ReceiveMessage", (user, msg) => ...)
    }

    // Join a group - useful for chat rooms, game rooms
    public async Task JoinGroup(string groupName)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, groupName);
        // => Context.ConnectionId is the unique identifier for this connection
        // => AddToGroupAsync adds connection to named group
        await Clients.Group(groupName).SendAsync("UserJoined", Context.ConnectionId);
        // => Clients.Group(name) sends only to connections in that group
    }

    // Leave a group
    public async Task LeaveGroup(string groupName)
    {
        await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName);
        await Clients.Group(groupName).SendAsync("UserLeft", Context.ConnectionId);
    }

    // Send to a specific connection
    public async Task SendPrivate(string connectionId, string message)
    {
        await Clients.Client(connectionId).SendAsync("PrivateMessage", message);
        // => Clients.Client(id) targets a single connection
        // => Use for direct messages or targeted notifications
    }

    // Override connection lifecycle events
    public override async Task OnConnectedAsync()
    {
        await Clients.Others.SendAsync("UserConnected", Context.ConnectionId);
        // => Clients.Others = all connections except the current one
        await base.OnConnectedAsync();
        // => Must call base to complete connection setup
    }

    public override async Task OnDisconnectedAsync(Exception? exception)
    {
        await Clients.Others.SendAsync("UserDisconnected", Context.ConnectionId);
        await base.OnDisconnectedAsync(exception);
        // => exception is null for clean disconnects, error for drops
    }
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSignalR();
// => AddSignalR registers hub infrastructure, WebSocket handler, and backplane

var app = builder.Build();
app.MapHub<ChatHub>("/chat");
// => WebSocket endpoint at /chat
// => Client connects with: new signalR.HubConnectionBuilder().withUrl("/chat").build()

app.Run();

// Install: dotnet add package Microsoft.AspNetCore.Mvc.Testing
using Microsoft.AspNetCore.Mvc.Testing;
using System.Net.Http.Json;
using Xunit;

// Application startup class (or use Program with partial class trick)
// In modern .NET: add "var app = ..." before app.Run() and expose as partial

// Test class using WebApplicationFactory
public class ProductsApiTests : IClassFixture<WebApplicationFactory<Program>>
{
    // IClassFixture<T>: creates one factory instance per test class
    private readonly WebApplicationFactory<Program> _factory;
    private readonly HttpClient _client;

    public ProductsApiTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory;
        _client = factory.CreateClient();
        // => CreateClient() creates HttpClient pointing at in-process test server
        // => No real network, no port binding needed
    }

    [Fact]
    public async Task GetProducts_ReturnsOkWithProducts()
    {
        // Arrange - nothing needed; client is ready

        // Act - make HTTP request to test server
        var response = await _client.GetAsync("/products");
        // => Sends GET /products to in-process ASP.NET Core server

        // Assert
        response.EnsureSuccessStatusCode();
        // => Throws if status code is not 2xx
        Assert.Equal(System.Net.HttpStatusCode.OK, response.StatusCode);
        // => Verify specific 200 status code

        var products = await response.Content.ReadFromJsonAsync<List<ProductDto>>();
        // => Deserialize JSON response body
        Assert.NotNull(products);
        Assert.True(products.Count > 0);
        // => Verify at least one product returned
    }

    [Fact]
    public async Task CreateProduct_WithValidData_ReturnsCreated()
    {
        // Arrange
        var newProduct = new { Name = "Test Widget", Price = 9.99, Stock = 50 };

        // Act
        var response = await _client.PostAsJsonAsync("/products", newProduct);
        // => PostAsJsonAsync serializes object to JSON and sends POST

        // Assert
        Assert.Equal(System.Net.HttpStatusCode.Created, response.StatusCode);
        // => 201 Created expected
        Assert.NotNull(response.Headers.Location);
        // => Location header should be present on Created responses
    }
}

// Override services for testing (inject test doubles)
public class ProductsApiWithMockTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductsApiWithMockTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                // Replace real service with test double
                services.AddScoped<IProductRepository, FakeProductRepository>();
                // => FakeProductRepository returns predictable test data
                // => Real DbContext is not used in these tests
            });
        }).CreateClient();
    }
}

record ProductDto(int Id, string Name, decimal Price);

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.AspNetCore.TestHost;
using System.Security.Claims;
using Xunit;

// Test authentication handler that auto-authenticates requests
public class TestAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    public TestAuthHandler(
        IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder)
        : base(options, logger, encoder) {}

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // => Called for every request - returns success with test user
        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, "test-user-123"),
            new Claim(ClaimTypes.Name, "Test User"),
            new Claim(ClaimTypes.Role, "admin"),
            // => Add any claims needed for the endpoints being tested
        };
        var identity = new ClaimsIdentity(claims, "Test");
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, "Test");
        return Task.FromResult(AuthenticateResult.Success(ticket));
        // => AuthenticateResult.Success with test ticket bypasses real auth
    }
}

public class AuthenticatedApiTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;

    public AuthenticatedApiTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory;
    }

    private HttpClient CreateAuthenticatedClient()
    {
        return _factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                // Replace real authentication with test handler
                services.AddAuthentication("Test")
                    .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>("Test", _ => {});
                // => "Test" scheme auto-authenticates all requests
            });
        }).CreateClient();
    }

    [Fact]
    public async Task GetProfile_WithAuthenticatedUser_ReturnsUserInfo()
    {
        var client = CreateAuthenticatedClient();

        var response = await client.GetAsync("/profile");
        // => TestAuthHandler sets user claims; /profile is accessible

        response.EnsureSuccessStatusCode();
        // => Should return 200 with test user info
    }

    [Fact]
    public async Task AdminEndpoint_WithAdminRole_ReturnsOk()
    {
        var client = CreateAuthenticatedClient();
        // => Test user has "admin" role from TestAuthHandler

        var response = await client.GetAsync("/admin");
        response.EnsureSuccessStatusCode();
        // => Admin endpoint accessible because test user has admin role
    }
}

// Install: dotnet add package AspNetCore.HealthChecks.NpgSql (for PostgreSQL)
using Microsoft.Extensions.Diagnostics.HealthChecks;

// Custom health check implementation
public class DiskSpaceHealthCheck : IHealthCheck
{
    private readonly long _minimumFreeSpaceBytes;

    public DiskSpaceHealthCheck(long minimumFreeSpaceBytes = 500 * 1024 * 1024) // 500MB
    {
        _minimumFreeSpaceBytes = minimumFreeSpaceBytes;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var drive = new DriveInfo("/");
        // => Check root drive free space
        var freeSpace = drive.AvailableFreeSpace;
        // => freeSpace = available bytes on root filesystem

        if (freeSpace >= _minimumFreeSpaceBytes)
            return Task.FromResult(HealthCheckResult.Healthy(
                $"Disk space OK: {freeSpace / 1024 / 1024}MB free"));
        // => HealthCheckResult.Healthy = everything is fine
        // => Description provides context for monitoring tools

        return Task.FromResult(HealthCheckResult.Degraded(
            $"Low disk space: {freeSpace / 1024 / 1024}MB free (minimum: {_minimumFreeSpaceBytes / 1024 / 1024}MB)"));
        // => HealthCheckResult.Degraded = working but degraded
        // => Between Healthy and Unhealthy - may indicate approaching failure
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
    .AddCheck("self", () => HealthCheckResult.Healthy())
    // => Trivial liveness check - if this runs, process is alive
    .AddNpgSql(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection")!,
        name: "database",
        tags: new[] { "db", "ready" })
    // => PostgreSQL connectivity check - requires real database
    // => Tags used to filter checks for different probes
    .AddCheck<DiskSpaceHealthCheck>("disk-space", tags: new[] { "ready" });
    // => Register custom health check with DI

var app = builder.Build();

// Liveness probe - just checks the process is running
app.MapHealthChecks("/health/live", new Microsoft.AspNetCore.Diagnostics.HealthChecks.HealthCheckOptions
{
    Predicate = _ => false
    // => Predicate false: no checks run, always returns Healthy
    // => Purpose: confirm the process is alive and accepting connections
});

// Readiness probe - checks all "ready"-tagged dependencies
app.MapHealthChecks("/health/ready", new Microsoft.AspNetCore.Diagnostics.HealthChecks.HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
    // => Only runs checks tagged "ready" (database, cache, disk)
    // => Returns Unhealthy if any dependency is unavailable
});

// Full health report for monitoring dashboards
app.MapHealthChecks("/health", new Microsoft.AspNetCore.Diagnostics.HealthChecks.HealthCheckOptions
{
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";
        var result = System.Text.Json.JsonSerializer.Serialize(new
        {
            Status = report.Status.ToString(),
            Checks = report.Entries.Select(e => new
            {
                Name = e.Key,
                Status = e.Value.Status.ToString(),
                Description = e.Value.Description
            })
        });
        await context.Response.WriteAsync(result);
    }
});

app.Run();

using Microsoft.Extensions.Hosting;

// Background service using BackgroundService base class
public class OrderProcessingService : BackgroundService
{
    private readonly ILogger<OrderProcessingService> _logger;
    private readonly IServiceProvider _serviceProvider;
    // => IServiceProvider used to create scoped services inside singleton

    public OrderProcessingService(
        ILogger<OrderProcessingService> logger,
        IServiceProvider serviceProvider)
    {
        _logger = logger;
        _serviceProvider = serviceProvider;
        // => Background services are Singleton lifetime
        // => Cannot inject Scoped services directly (captive dependency bug)
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // => ExecuteAsync runs when host starts and stops when host stops
        // => stoppingToken is cancelled when application is shutting down
        _logger.LogInformation("Order processing service starting");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await ProcessPendingOrdersAsync(stoppingToken);
                // => Do work in each iteration
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                // => Expected: application is shutting down
                break;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing orders");
                // => Log but don't crash the service; retry next interval
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
            // => Wait 30 seconds between processing batches
            // => stoppingToken cancellation exits this delay immediately
        }

        _logger.LogInformation("Order processing service stopped");
    }

    private async Task ProcessPendingOrdersAsync(CancellationToken ct)
    {
        // Create a scope to resolve Scoped services
        using var scope = _serviceProvider.CreateScope();
        // => CreateScope creates a new DI scope for this operation
        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        // => Get Scoped DbContext from the scope
        // => This is the correct way to use Scoped services from Singleton

        // Process orders using the scoped DbContext
        _logger.LogDebug("Processing pending orders...");
        await Task.Delay(100, ct); // Simulates DB work
        // => In production: query pending orders, process, save changes
    }
}

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(opt => opt.UseInMemoryDatabase("bg"));

// Register the background service
builder.Services.AddHostedService<OrderProcessingService>();
// => AddHostedService registers the service and starts it with the host
// => Service runs until IHostApplicationLifetime.ApplicationStopped

var app = builder.Build();
app.MapGet("/", () => "Web server running alongside background service");
app.Run();

using Microsoft.Extensions.Caching.Memory;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMemoryCache();
// => Registers IMemoryCache singleton in DI container
// => In-process cache; not shared between server instances

var app = builder.Build();

app.MapGet("/products/{id:int}", async (int id, IMemoryCache cache) =>
{
    var cacheKey = $"product:{id}";
    // => Consistent key naming prevents collision with other cached items

    if (cache.TryGetValue(cacheKey, out ProductDto? product))
    {
        // => TryGetValue returns true if key exists and not expired
        // => product is populated with cached value
        Console.WriteLine($"Cache HIT for product {id}");
        return Results.Ok(product);
    }
    // => Cache MISS: fetch from database

    Console.WriteLine($"Cache MISS for product {id}, fetching from DB");
    // Simulate database fetch
    product = new ProductDto(id, $"Product {id}", id * 9.99m);
    // => In production: await db.Products.FindAsync(id)

    var cacheOptions = new MemoryCacheEntryOptions
    {
        AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5),
        // => Cache expires 5 minutes after being added (regardless of access)
        SlidingExpiration = TimeSpan.FromMinutes(2),
        // => Reset expiration on each access within absolute window
        // => Absolute expiration wins: entry expires at min(absolute, last-access + sliding)
        Priority = CacheItemPriority.Normal,
        // => Priority controls which items are evicted under memory pressure
        // => Low, Normal, High, NeverRemove
        Size = 1
        // => Relative size for cache size limits; requires setting cache size limit
    };

    cache.Set(cacheKey, product, cacheOptions);
    // => Store in cache with configured expiration and priority

    return Results.Ok(product);
});

// Cache invalidation
app.MapDelete("/products/{id:int}/cache", (int id, IMemoryCache cache) =>
{
    cache.Remove($"product:{id}");
    // => Remove immediately evicts the entry
    // => Call after product update to prevent stale cache
    return Results.NoContent();
});

// GetOrCreate - atomic get-or-create pattern
app.MapGet("/categories", async (IMemoryCache cache) =>
{
    var categories = await cache.GetOrCreateAsync("all-categories", async entry =>
    {
        entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30);
        // => Set expiration inside factory
        // Simulate DB fetch
        return new[] { "Electronics", "Clothing", "Books" };
    });
    // => GetOrCreateAsync: if key exists, return cached value
    // => If missing: execute factory, cache result, return it
    // => Thread-safe: factory runs once even under concurrent cache misses
    return Results.Ok(categories);
});

record ProductDto(int Id, string Name, decimal Price);
app.Run();