DEV Community: Chethan Ramaswamy

ASP.NET Core Authentication & Authorization Explained: What to Use, When, and How to Ship It Safely

Chethan Ramaswamy — Mon, 02 Nov 2026 01:22:15 +0000

Picture this. Your API has [Authorize] on every controller. Login works. Tokens validate. The security review is green.

Then a curious user changes /invoices/1042 to /invoices/1043 in the URL and reads a stranger's invoice.

Nothing was "broken". Authentication did its job. Authorization just never asked the right question.

ASP.NET Core gives you a powerful, pluggable security system, and that flexibility is exactly why it feels overwhelming: cookies, JWTs, OAuth 2.0, OpenID Connect, Identity, schemes, policies, requirements, handlers. This guide is the map I wish I had when I started.

What you'll get:

A plain-English mental model of how ASP.NET Core security works
Every authentication option, with clear "use it when / avoid it when" guidance
Every authorization style, from [Authorize] up to resource-based checks
A recommended architecture for each common scenario
A production checklist of the things that bite teams after launch

Examples target .NET 10 (LTS). Most of it works on .NET 8 and later, and I flag version-specific behavior where it matters.

TL;DR

Don't build your own identity provider. Use Entra ID, Auth0, Okta, Keycloak, Duende, or OpenIddict.

Browser apps: cookies (and a BFF for SPAs).

APIs: JWT Bearer.

Machines: client credentials, managed identity, or mTLS.

Own your users? ASP.NET Core Identity, with lockout, MFA, and passkeys (.NET 10).

Authorization: fallback policy first, named policies next, resource-based checks for anything with an ID in the URL.

Production: persist Data Protection keys, validate every token field, keep tokens short-lived, rate-limit login endpoints, and test your access rules.

1. Two questions, two jobs

Think of an airport.

Passport control checks who you are. That is authentication.
The gate agent checks whether your boarding pass lets you on this flight. That is authorization.
Passing the first says nothing about the second. And even with a valid boarding pass, you still can't sit in someone else's seat. That last check is resource-based authorization, and it is the one most apps forget.

	Authentication (AuthN)	Authorization (AuthZ)
Question	Who are you?	What are you allowed to do?
Result	A `ClaimsPrincipal`	Allowed, challenged (401), or forbidden (403)
Middleware	`UseAuthentication()`	`UseAuthorization()`
Configured with	Schemes and handlers	Policies, requirements, handlers

The HTTP status codes follow the same split:

401 Unauthorized means "I don't know who you are." (Not authenticated.)
403 Forbidden means "I know who you are, and the answer is no." (Not authorized.)

2. The vocabulary, in plain English

You will see these terms constantly. Here is what they mean without the jargon.

Term	Plain-English meaning
Claim	One fact about a user: `email = ada@example.com`, `role = Admin`
ClaimsPrincipal	The "user object" in ASP.NET Core. A bag of claims, available as `HttpContext.User`
Authentication scheme	A named way of proving identity: `"Cookies"`, `"Bearer"`, `"OpenIdConnect"`
Authentication handler	The code behind a scheme that reads the request and builds the principal
Policy	A named rule, such as `"CanRefund"`, that decides if a user may proceed
Identity provider (IdP)	A dedicated service that logs users in and issues tokens (Entra ID, Auth0, Keycloak...)
Access token	A short-lived "key card" the client shows to an API
JWT	A common token format: signed JSON that an API can verify without calling anyone
OAuth 2.0 / OIDC	OAuth 2.0 delegates access. OpenID Connect adds login (who the user is) on top
PKCE	A protection that makes the authorization-code flow safe for browsers and mobile apps
BFF	Backend-for-Frontend: a small server that keeps tokens away from the browser

3. How it fits together in ASP.NET Core

Every secured app has the same skeleton:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(/* default scheme */)
    .AddXxx(/* handler options */);

builder.Services.AddAuthorization(/* policies */);

var app = builder.Build();

app.UseHttpsRedirection();
app.UseCors();            // before auth, or preflight requests fail
app.UseAuthentication();  // who are you?
app.UseAuthorization();   // what can you do?

app.MapGet("/secure", () => "hi").RequireAuthorization();
app.Run();

Order matters. UseAuthentication() must run before UseAuthorization(), and both must run before the endpoints they protect. Swap them and everything looks anonymous.

A scheme can play several roles:

Authenticate: build the user from the request
Challenge: respond to an anonymous user hitting a protected resource (cookies redirect to a login page; JWT returns 401)
Forbid: respond to a known user who lacks permission (403)
SignIn / SignOut: create or clear the session (cookies)

4. Pick your approach in 60 seconds

Start with one question: who is calling?

Who is calling?
|
+-- A person in a browser
|     +-- Server-rendered pages (MVC, Razor Pages, Blazor Server)
|     |        --> Cookie (+ Identity if you own the users, or OIDC for SSO)
|     +-- A SPA (React, Angular, Vue, Blazor WebAssembly)
|              --> BFF: cookie to the browser, OIDC behind it
|
+-- A mobile or desktop app
|        --> OIDC authorization code + PKCE, then JWT to your API
|
+-- Another service (no user involved)
|        --> Client credentials or managed identity (+ mTLS for high trust)
|
+-- A third-party developer
         --> OAuth client credentials (or API keys if you need it simple)

And the same thing as a table:

Scenario	Recommended approach
Server-rendered app, you own the user database	Cookie + ASP.NET Core Identity
Server-rendered app in a company with SSO	Cookie + OpenID Connect
SPA with your own backend	BFF: HttpOnly cookie to the browser, OIDC (code + PKCE) to the IdP
Mobile / native app	OIDC code + PKCE in the system browser; bearer tokens to the API
Web API consumed by your apps	JWT Bearer, validated against your IdP
Service-to-service	OAuth 2.0 client credentials, or managed / workload identity in the cloud
High-trust internal services	mTLS (client certificates), often alongside tokens
Public API for third parties	Client credentials; API keys for simple cases
Windows intranet	Negotiate (Kerberos / NTLM)
Passwordless for end users	Passkeys (built into Identity since .NET 10)
Inbound webhooks	HMAC signature verification (this is request verification, not user auth)

The single most important recommendation

Do not build your own token issuer unless identity is your product.

Use a dedicated identity provider:

Managed: Microsoft Entra ID / Entra External ID, Auth0, Okta, AWS Cognito, Firebase Auth
Self-hosted: Keycloak, Duende IdentityServer (commercial licensing), OpenIddict (open source)

IdentityServer4 is no longer maintained, so don't start new projects on it.

Why this matters: your apps become clients and resource servers of the IdP. That is a much smaller attack surface than being the IdP, which means owning password storage, MFA, token signing, key rotation, and account recovery.

5. Authentication mechanisms, one by one

5.1 Cookie authentication

After login, the server issues an encrypted, signed cookie that holds the user's claims. The browser sends it back automatically on every request.

✅ Use it when: your UI is served by the same site (MVC, Razor Pages, Blazor Server, or a BFF)
❌ Avoid it when: you are building an API for third-party or mobile clients

builder.Services
    .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.Cookie.Name = "__Host-myapp";            // __Host- prefix: Secure, Path=/, no Domain
        options.Cookie.HttpOnly = true;                    // JavaScript can't read it
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        options.Cookie.SameSite = SameSiteMode.Lax;        // good default; Strict can break login redirects

        options.ExpireTimeSpan = TimeSpan.FromHours(8);
        options.SlidingExpiration = true;

        options.LoginPath = "/account/login";
        options.AccessDeniedPath = "/account/denied";
    });

SecurePolicy.Always means the cookie only travels over HTTPS. Run your dev server with HTTPS (dotnet dev-certs https --trust) so local testing matches production.

Signing a user in manually:

var claims = new List<Claim>
{
    new(ClaimTypes.NameIdentifier, user.Id),
    new(ClaimTypes.Name, user.Email),
    new(ClaimTypes.Role, "Admin")
};

var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
await HttpContext.SignInAsync(
    new ClaimsPrincipal(identity),
    new AuthenticationProperties { IsPersistent = true });

Production tips

Add antiforgery protection for state-changing requests (app.UseAntiforgery() in .NET 8+, and AutoValidateAntiforgeryToken in MVC).
With multiple instances you must persist Data Protection keys (see the checklist), or users get logged out at random.
The whole principal is serialized into the cookie, so keep claims lean. For large claim sets, use a server-side session store (ITicketStore).

.NET 10 behavior change you should know about. For known API endpoints, the cookie handler now returns 401/403 instead of redirecting to the login page. Known API endpoints are [ApiController] endpoints, minimal API endpoints that read or write JSON, endpoints returning TypedResults, and SignalR endpoints. Regular pages still redirect. The 401/403 response still carries a Location header with the login URL, and there is an opt-out (AllowCookieRedirect) if you rely on the old behavior. Check any browser code that used to follow those redirects.

5.2 ASP.NET Core Identity

Identity is a full membership system: a user store (usually EF Core), password hashing, roles, claims, lockout, email confirmation, password reset, external logins, two-factor authentication (2FA), and, from .NET 10, passkeys.

✅ Use it when: you own the user database and need standard account management
❌ Avoid it when: your users live in an external IdP. In that case you only need OIDC, not a user store.

builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

builder.Services
    .AddIdentity<AppUser, IdentityRole>(options =>
    {
        options.Password.RequiredLength = 12;
        options.Password.RequireNonAlphanumeric = false;   // length beats complexity rules
        options.User.RequireUniqueEmail = true;
        options.SignIn.RequireConfirmedEmail = true;

        options.Lockout.MaxFailedAccessAttempts = 5;
        options.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
        options.Lockout.AllowedForNewUsers = true;
    })
    .AddEntityFrameworkStores<AppDbContext>()
    .AddDefaultTokenProviders();

builder.Services.ConfigureApplicationCookie(options =>
{
    options.Cookie.HttpOnly = true;
    options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    options.ExpireTimeSpan = TimeSpan.FromHours(8);
    options.SlidingExpiration = true;
});

AddIdentity gives you users and roles. If you only need the core services (for example, in an API), AddIdentityCore is the lighter option.

Logging in with lockout turned on:

var result = await signInManager.PasswordSignInAsync(
    email, password, isPersistent: false, lockoutOnFailure: true);

if (result.RequiresTwoFactor) { /* send the user to the 2FA page */ }
if (result.IsLockedOut)       { /* show a lockout message */ }

Worth knowing

Passwords are hashed with PBKDF2 by default. Never write your own hashing.
2FA (TOTP) is built in: authenticator-app codes plus recovery codes.
Passkeys (.NET 10): Identity now supports passkey (WebAuthn/FIDO2) registration and sign-in, and the Blazor Web App template ships with it. Passkeys use public-key cryptography tied to your site's origin, so there is no password to phish. Adopting them needs a database migration for the passkey table. Note that the default template still asks users to create a password first. That is a template choice, not an Identity limitation.
MapIdentityApi<TUser>() (.NET 8+) gives you ready-made register, login, and refresh endpoints. The tokens it issues are Identity's own bearer tokens, not JWTs, and it is not a full OAuth/OIDC server. It is great for demos and simple single-client backends. For multiple clients or third parties, use a real IdP.

5.3 JWT Bearer authentication

The client sends Authorization: Bearer <jwt>. The API verifies the signature, issuer, audience, and expiry, then builds a principal from the token's claims. There is no server-side session.

✅ Use it when: you are protecting a Web API called by mobile apps, other services, or a BFF
❌ Avoid it when: you would be tempted to store the token in browser localStorage (use a BFF instead)

The right way is to validate tokens issued by your IdP. Set Authority, and ASP.NET Core downloads the signing keys and handles key rotation for you.

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.example.com/";   // IdP issuer URL
        options.Audience  = "orders-api";                   // this API's identifier
        options.MapInboundClaims = false;                   // keep original claim names ("sub", "role", ...)

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromSeconds(30),           // default is 5 minutes; tighten it
            NameClaimType = "name",
            RoleClaimType = "role"
        };

        options.RequireHttpsMetadata = true;                // never disable in production
    });

Production tips

Never set ValidateIssuer, ValidateAudience, or ValidateLifetime to false to "make it work". That is how authentication bypasses happen. If validation fails, fix the configuration.
Keep access tokens short-lived: minutes, not days. Use refresh tokens with rotation in a client that can store them safely.
A JWT cannot be revoked before it expires (unless you add introspection or a deny-list). Short lifetimes are your safety net.
A JWT is signed, not encrypted. Anyone holding it can read it, so never put secrets in it.
Prefer asymmetric signing (RS256 / ES256), so APIs only need a public key.
If you must issue your own JWTs, keep signing keys in a vault (Key Vault, KMS, Secrets Manager, HashiCorp Vault), rotate them, and publish a JWKS endpoint.

5.4 OpenID Connect (OIDC) and OAuth 2.0

OAuth 2.0 handles delegated access (access tokens). OIDC sits on top and adds login (the ID token and standard user claims). For interactive login against an external IdP, you want OIDC.

✅ Use it when: you want SSO, enterprise login, or social login
Flow to use: authorization code + PKCE. The implicit flow and the password (ROPC) flow are discouraged by current security guidance and removed in OAuth 2.1, so avoid them.

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        options.Authority = "https://login.example.com/";
        options.ClientId = builder.Configuration["Oidc:ClientId"];
        options.ClientSecret = builder.Configuration["Oidc:ClientSecret"];  // from a vault, not appsettings.json
        options.ResponseType = "code";
        options.UsePkce = true;

        options.Scope.Clear();
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("email");
        options.Scope.Add("offline_access");   // lets you get refresh tokens
        options.Scope.Add("orders-api");       // your API scope (the name depends on your IdP)

        options.SaveTokens = true;             // keep the tokens with the session
        options.GetClaimsFromUserInfoEndpoint = true;
        options.MapInboundClaims = false;
    });

If you use Microsoft Entra ID, the Microsoft.Identity.Web library wraps all of this, including token acquisition, caching, and downstream API calls. Pick the one that matches your app:

// A web app that signs users in
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));

// OR a web API that validates tokens
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

Social logins are OAuth/OIDC handlers added with calls like .AddGoogle(), .AddMicrosoftAccount(), and .AddFacebook(), usually combined with Identity's external-login flow. Providers such as GitHub are not built in, but community packages (for example AspNet.Security.OAuth.GitHub) add them.

Production tips

Keep client secrets out of source control. Prefer certificates or managed identity where your IdP supports them.
Register exact redirect URIs. No wildcards.
Behind a reverse proxy or load balancer, configure forwarded headers so redirect URIs use the public scheme and host. Forgetting this is the classic cause of redirect_uri_mismatch.

5.5 The BFF pattern for SPAs (recommended)

Storing tokens in localStorage or sessionStorage means any XSS bug can steal them. The current best practice for browser apps is the Backend-for-Frontend (BFF):

 Browser ---(HttpOnly cookie)---> BFF (ASP.NET Core) ---(access token)---> Your APIs
                                     |
                                     +---(OIDC: code + PKCE)---> Identity Provider

The BFF is a confidential OIDC client. Tokens never reach the browser.
The browser only holds a session cookie.
The BFF attaches the access token when it forwards API calls (for example with YARP or Duende BFF).
Add CSRF protection for the cookie-authenticated endpoints, such as requiring a custom header (X-CSRF: 1) together with SameSite cookies.

✅ Use it when you have a SPA (including Blazor WebAssembly) handling sensitive data and you control the backend. It adds a moving part, but it removes the biggest browser-side token risk.

5.6 Service-to-service: client credentials, managed identity, mTLS

For backend callers with no user, use the OAuth 2.0 client credentials flow. The calling service gets a token from the IdP using its own credentials and sends it as a Bearer token. The receiving API validates it with plain JWT Bearer, as above.

In the cloud, prefer managed identity / workload identity so there is no secret to leak.

For mutual TLS (client certificates):

builder.Services
    .AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.AllowedCertificateTypes = CertificateTypes.Chained;
        options.RevocationMode = X509RevocationMode.Online;
        options.Events = new CertificateAuthenticationEvents
        {
            OnCertificateValidated = ctx =>
            {
                // Check thumbprint/subject against an allow-list, then build the principal.
                // BuildPrincipalFrom is your own helper.
                ctx.Principal = BuildPrincipalFrom(ctx.ClientCertificate);
                ctx.Success();
                return Task.CompletedTask;
            }
        };
    });

builder.WebHost.ConfigureKestrel(k =>
    k.ConfigureHttpsDefaults(h => h.ClientCertificateMode = ClientCertificateMode.AllowCertificate));

Careful with RequireCertificate. Setting it globally forces every client, browsers included, to present a certificate. If the same app serves browsers, use AllowCertificate (as above) and protect only the machine-to-machine endpoints, or run the mTLS API on its own port or host.

If TLS ends at a proxy (NGINX, Application Gateway, Envoy), use the certificate-forwarding middleware (AddCertificateForwarding) and only trust the forwarded certificate from your known proxy.

5.7 API keys

ASP.NET Core has no built-in API key scheme, but a custom handler is short. API keys are acceptable for simple server-to-server integrations, but remember: they are static bearer secrets with no built-in expiry, scopes, or user identity. Prefer OAuth client credentials when you can.

public sealed class ApiKeyHandler(
    IOptionsMonitor<AuthenticationSchemeOptions> options,
    ILoggerFactory logger,
    UrlEncoder encoder,
    IApiKeyStore store)
    : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
    public const string SchemeName = "ApiKey";

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue("X-Api-Key", out var values))
            return AuthenticateResult.NoResult();   // not our scheme; let others try

        // The store hashes the incoming key and looks it up by hash.
        var client = await store.ValidateAsync(values.ToString(), Context.RequestAborted);
        if (client is null)
            return AuthenticateResult.Fail("Invalid API key");

        var identity = new ClaimsIdentity(new[]
        {
            new Claim(ClaimTypes.NameIdentifier, client.Id),
            new Claim("client_name", client.Name),
            new Claim("scope", string.Join(' ', client.Scopes))
        }, SchemeName);

        var ticket = new AuthenticationTicket(new ClaimsPrincipal(identity), SchemeName);
        return AuthenticateResult.Success(ticket);
    }
}

// Registration
builder.Services.AddAuthentication()
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>(ApiKeyHandler.SchemeName, _ => { });

Production tips

Generate keys with a cryptographically secure random generator (at least 32 bytes).
Show the key to the owner once, and store only a hash. Because these keys are long and random, a fast hash such as SHA-256 is fine (unlike passwords, which need a slow hash).
Support rotation and revocation, rate-limit per key, and send keys in a header, never in the query string (URLs end up in logs).

5.8 Windows / Negotiate

For intranet apps on Active Directory, the Microsoft.AspNetCore.Authentication.Negotiate package gives you Kerberos/NTLM single sign-on:

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme).AddNegotiate();

✅ Use it only when everyone is on a domain-joined network. For internet-facing or hybrid apps, use OIDC with Entra ID instead.

5.9 Basic authentication

Username and password in every request. It is only acceptable over HTTPS, for legacy integrations, with strict limits. For anything new, use tokens.

5.10 Combining multiple schemes

Real systems often need cookies for the UI, JWT for the API, and an API key for partners, all in one app. You have two options.

Option A: choose the scheme per endpoint. Explicit and easy to reason about:

app.MapGet("/api/orders", GetOrders)
   .RequireAuthorization(new AuthorizeAttribute
   {
       AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme
   });

Option B: a policy scheme that forwards each request to the right handler:

builder.Services.AddAuthentication("Smart")
    .AddPolicyScheme("Smart", displayName: null, options =>
    {
        options.ForwardDefaultSelector = ctx =>
        {
            if (ctx.Request.Headers.ContainsKey("X-Api-Key"))
                return ApiKeyHandler.SchemeName;

            var auth = ctx.Request.Headers.Authorization.ToString();
            if (auth.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase))
                return JwtBearerDefaults.AuthenticationScheme;

            return CookieAuthenticationDefaults.AuthenticationScheme;
        };
    })
    .AddCookie()
    .AddJwtBearer(/* ... */)
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>(ApiKeyHandler.SchemeName, _ => { });

If one app mixes UI and API, remember that page challenges redirect while API challenges return 401. APIs should never redirect to a login page.

5.11 Passkeys (passwordless)

Passkeys (WebAuthn/FIDO2) replace passwords with public-key credentials stored on the user's device or password manager. Because there is no shared secret, phishing and credential stuffing largely stop working against passkey logins.

With .NET 10, ASP.NET Core Identity has built-in passkey registration and sign-in, so if you own the user store, this is now the lowest-friction way to offer passwordless login. If you use an external IdP, enable passkeys there instead.

Always keep a recovery path (verified email, recovery codes) so users aren't locked out when they lose a device. Remember that recovery flows can become the weakest link, so protect them as carefully as the login itself.

6. Authorization: a ladder, not a menu

Authorization decides what a known (or anonymous) user may do. The options below are a ladder. Climb only as high as your problem needs, but don't stop too low.

Rung 0: Make "secure by default" your baseline

Require authentication everywhere, then opt out on purpose. This prevents the classic "I forgot [Authorize]" bug.

builder.Services.AddAuthorizationBuilder()
    .SetFallbackPolicy(new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build());

// Opt out explicitly
app.MapGet("/health", () => "ok").AllowAnonymous();

Rung 1: Simple `[Authorize]`

[Authorize]                       // any signed-in user
public class OrdersController : ControllerBase { /* ... */ }

[AllowAnonymous]                  // overrides at action level
public IActionResult Ping() => Ok();

Minimal APIs:

app.MapGet("/orders", GetOrders).RequireAuthorization();

var api = app.MapGroup("/api").RequireAuthorization();   // protects the whole group

Rung 2: Roles (RBAC)

[Authorize(Roles = "Admin,Manager")]    // Admin OR Manager
public IActionResult Reports() => Ok();

[Authorize(Roles = "Admin")]
[Authorize(Roles = "Auditor")]          // stacked attributes mean AND: both required
public IActionResult Sensitive() => Ok();

✅ Good for: coarse, stable groups (Admin, User)
❌ Breaks down when: roles multiply ("Manager-EMEA-ReadOnly"). Move to policies.

Rung 3: Claims and policies (your default workhorse)

A policy gives a rule a name, so your endpoints say what is needed, not how it is computed.

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("AdminOnly", p => p.RequireRole("Admin"))
    .AddPolicy("EmployeeOnly", p => p.RequireClaim("employee_id"))
    .AddPolicy("CanRefund", p => p.RequireAssertion(ctx =>
        HasScope(ctx.User, "orders.refund")));

static bool HasScope(ClaimsPrincipal user, string scope) =>
    user.FindAll("scope")
        .SelectMany(c => c.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        .Contains(scope);

[Authorize(Policy = "CanRefund")]
[HttpPost("{id}/refund")]
public IActionResult Refund(int id) => Ok();

// Minimal API
app.MapPost("/orders/{id}/refund", Refund).RequireAuthorization("CanRefund");

Gotcha: the OAuth scope is usually one claim holding a space-separated string ("orders.read orders.refund"). RequireClaim("scope", "orders.refund") will not match it, which is why the example splits it first. Also check what your IdP emits: Microsoft Entra ID uses scp for delegated scopes and roles for app roles.

Rung 4: Custom requirements and handlers

When a rule needs real logic or services (a database, another API), write a requirement and a handler.

public sealed record MinimumAgeRequirement(int Age) : IAuthorizationRequirement;

public sealed class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context, MinimumAgeRequirement requirement)
    {
        var claim = context.User.FindFirst("date_of_birth")?.Value;
        if (DateOnly.TryParse(claim, out var birthDate))
        {
            var today = DateOnly.FromDateTime(DateTime.UtcNow);
            var age = today.Year - birthDate.Year;
            if (birthDate > today.AddYears(-age)) age--;     // birthday hasn't happened yet this year

            if (age >= requirement.Age)
                context.Succeed(requirement);
        }
        return Task.CompletedTask;   // not calling Succeed means the requirement is not met
    }
}

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
builder.Services.AddAuthorizationBuilder()
    .AddPolicy("Adult", p => p.AddRequirements(new MinimumAgeRequirement(18)));

Three rules worth memorizing:

Several handlers for one requirement are OR'd. Any Succeed wins.
Several requirements in one policy are AND'd. All must succeed.
Call context.Fail() only when you need to veto the request regardless of other handlers.

Rung 5: Resource-based authorization (the one people skip)

Roles and policies answer "can this **type* of user do this kind of thing?"* They cannot answer "can **this user* edit this document?"* That depends on the resource.

Skipping this rung is how broken object-level authorization (BOLA / IDOR) happens, the number-one risk in the OWASP API Security Top 10, and the invoice story from the start of this article.

public static class Operations
{
    public static readonly OperationAuthorizationRequirement Read   = new() { Name = nameof(Read) };
    public static readonly OperationAuthorizationRequirement Update = new() { Name = nameof(Update) };
}

public sealed class DocumentAuthorizationHandler
    : AuthorizationHandler<OperationAuthorizationRequirement, Document>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        OperationAuthorizationRequirement requirement,
        Document resource)
    {
        var userId = context.User.FindFirstValue("sub");
        var isOwner = resource.OwnerId == userId;

        if (requirement.Name == Operations.Read.Name && (isOwner || resource.IsPublic))
            context.Succeed(requirement);

        if (requirement.Name == Operations.Update.Name && isOwner)
            context.Succeed(requirement);

        return Task.CompletedTask;
    }
}

builder.Services.AddSingleton<IAuthorizationHandler, DocumentAuthorizationHandler>();

Using it in an endpoint:

app.MapPut("/documents/{id:int}", async (
    int id, UpdateDocumentDto dto,
    ClaimsPrincipal user, IAuthorizationService authz, AppDbContext db) =>
{
    var doc = await db.Documents.FindAsync(id);
    if (doc is null) return Results.NotFound();

    var result = await authz.AuthorizeAsync(user, doc, Operations.Update);
    if (!result.Succeeded) return Results.Forbid();

    // ... perform the update
    return Results.NoContent();
}).RequireAuthorization();

Two extra habits:

Filter queries by owner or tenant at the data layer too (for example, EF Core global query filters) as a second line of defense.
For sensitive data, consider returning 404 instead of 403, so you don't confirm that someone else's record exists.

Rung 6: Permission-based authorization (fine-grained, at scale)

With dozens of permissions (orders.read, orders.refund, users.invite), don't register dozens of policies by hand. Create them on demand with a custom IAuthorizationPolicyProvider.

public sealed class PermissionAttribute(string permission) : AuthorizeAttribute($"perm:{permission}");

public sealed class PermissionRequirement(string permission) : IAuthorizationRequirement
{
    public string Permission { get; } = permission;
}

public sealed class PermissionPolicyProvider(IOptions<AuthorizationOptions> options)
    : DefaultAuthorizationPolicyProvider(options)
{
    public override async Task<AuthorizationPolicy?> GetPolicyAsync(string policyName)
    {
        if (policyName.StartsWith("perm:", StringComparison.Ordinal))
        {
            return new AuthorizationPolicyBuilder()
                .RequireAuthenticatedUser()
                .AddRequirements(new PermissionRequirement(policyName["perm:".Length..]))
                .Build();
        }
        return await base.GetPolicyAsync(policyName);
    }
}

public sealed class PermissionHandler : AuthorizationHandler<PermissionRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context, PermissionRequirement requirement)
    {
        if (context.User.HasClaim("permission", requirement.Permission))
            context.Succeed(requirement);
        return Task.CompletedTask;
    }
}

// Registration
builder.Services.AddSingleton<IAuthorizationPolicyProvider, PermissionPolicyProvider>();
builder.Services.AddSingleton<IAuthorizationHandler, PermissionHandler>();

// Usage
[Permission("orders.refund")]
public IActionResult Refund() => Ok();

Where do the permission claims come from? Either from your IdP (roles, scopes, or groups), or from a claims transformation that loads them from your database:

public sealed class PermissionClaimsTransformation(IPermissionService permissions) : IClaimsTransformation
{
    public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
    {
        if (principal.Identity is not ClaimsIdentity { IsAuthenticated: true } identity ||
            identity.HasClaim(c => c.Type == "permission"))
            return principal;   // not signed in, or already transformed

        var userId = principal.FindFirstValue("sub")!;
        foreach (var p in await permissions.GetForUserAsync(userId))
            identity.AddClaim(new Claim("permission", p));

        return principal;
    }
}

builder.Services.AddScoped<IClaimsTransformation, PermissionClaimsTransformation>();

TransformAsync can run more than once per request. Keep it idempotent (as above) and cache the lookups.

Rung 7: Attribute-based, multi-tenant, and external policy engines

ABAC (rules based on user attributes, resource attributes, and context such as time or IP): model each rule as a requirement and handler, as in Rungs 4 and 5.
Multi-tenant: carry a tenant_id claim and enforce it in handlers and in queries. Never trust a tenant ID that arrives only in the request body or route.
When rules outgrow C#, a dedicated engine (OPA, Cedar, OpenFGA, Cerbos) can be called from a handler.

Which rung do I need?

You need...	Use
"Must be signed in"	`[Authorize]` + fallback policy
A few stable groups	Roles
Rules based on claims or scopes	Policies
Rules needing services or custom logic	Requirements + handlers
"Can this user act on this object?"	Resource-based (`IAuthorizationService`)
Many fine-grained permissions	Permission-based policy provider
Complex, relationship-based rules	External policy engine

Recommended default: fallback policy + named policies + resource-based checks for object access. Use roles only for coarse grouping.

7. Reference architectures (what I would actually build)

A. Classic web app (MVC / Razor Pages / Blazor Server) with its own users

ASP.NET Core Identity (EF Core) with cookie auth
Lockout, email confirmation, 2FA, passkeys (.NET 10)
Policies and resource-based authorization
Persisted Data Protection keys, antiforgery, SameSite cookies

B. Enterprise web app with SSO

Cookie + OIDC (Entra ID via Microsoft.Identity.Web, or any OIDC IdP)
Roles and groups from the IdP mapped to policies
No local passwords at all

C. SPA + API

A BFF (ASP.NET Core) holds the OIDC session in an HttpOnly cookie
The API accepts JWT Bearer tokens
Scope-based policies plus resource-based checks in the API

D. Mobile app + API

OIDC code + PKCE through the system browser (AppAuth or MSAL), never an embedded WebView
The API validates JWT Bearer; short-lived access tokens and rotating refresh tokens

E. Microservices

One IdP issues tokens; each service validates JWTs (Authority + Audience)
Pass user context by token forwarding or token exchange (RFC 8693), not by trusting internal headers
Service-to-service: client credentials or managed identity, optionally mTLS
Each service enforces its own authorization. A gateway alone is not enough.

8. A production-flavored API example

This combines the main building blocks: JWT validation against an IdP, a secure-by-default fallback policy, scope policies, resource-based authorization, rate limiting, CORS, and basic security headers.

using System.Security.Claims;
using System.Threading.RateLimiting;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.HttpOverrides;
using Microsoft.AspNetCore.RateLimiting;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

// ---------- Authentication ----------
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.Authority = builder.Configuration["Auth:Authority"];
        o.Audience  = builder.Configuration["Auth:Audience"];
        o.MapInboundClaims = false;
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30),
            NameClaimType = "name",
            RoleClaimType = "role"
        };
    });

// ---------- Authorization ----------
builder.Services.AddAuthorizationBuilder()
    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build())
    .AddPolicy("orders:read",  p => p.RequireAssertion(c => HasScope(c.User, "orders.read")))
    .AddPolicy("orders:write", p => p.RequireAssertion(c => HasScope(c.User, "orders.write")));

builder.Services.AddSingleton<IAuthorizationHandler, OrderOwnerHandler>();

// ---------- CORS (explicit origins only) ----------
builder.Services.AddCors(o => o.AddPolicy("web", p => p
    .WithOrigins("https://app.example.com")
    .WithHeaders("Authorization", "Content-Type")
    .WithMethods("GET", "POST", "PUT", "DELETE")));

// ---------- Rate limiting (per user, falling back to IP) ----------
builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("per-user", ctx => RateLimitPartition.GetFixedWindowLimiter(
        ctx.User.FindFirstValue("sub") ?? ctx.Connection.RemoteIpAddress?.ToString() ?? "anon",
        _ => new FixedWindowRateLimiterOptions
        {
            PermitLimit = 100,
            Window = TimeSpan.FromMinutes(1)
        }));
});

// Behind a proxy or load balancer
builder.Services.Configure<ForwardedHeadersOptions>(o =>
{
    o.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    // IMPORTANT: also configure your known proxies/networks so spoofed headers are ignored
});

var app = builder.Build();

app.UseForwardedHeaders();
if (!app.Environment.IsDevelopment()) app.UseHsts();
app.UseHttpsRedirection();

app.Use(async (ctx, next) =>
{
    ctx.Response.Headers["X-Content-Type-Options"] = "nosniff";
    ctx.Response.Headers["Cache-Control"] = "no-store";   // don't cache authenticated responses
    await next();
});

app.UseCors("web");
app.UseAuthentication();
app.UseRateLimiter();      // after authentication, so the limiter can see who the user is
app.UseAuthorization();

app.MapGet("/healthz", () => "ok").AllowAnonymous();

var orders = app.MapGroup("/api/orders").RequireRateLimiting("per-user");

orders.MapGet("/", (ClaimsPrincipal user) => Results.Ok(new { user = user.FindFirstValue("sub") }))
      .RequireAuthorization("orders:read");

orders.MapPut("/{id:int}", async (int id, ClaimsPrincipal user, IAuthorizationService authz, IOrderRepo repo) =>
{
    var order = await repo.FindAsync(id);
    if (order is null) return Results.NotFound();

    var result = await authz.AuthorizeAsync(user, order, Operations.Update);
    return result.Succeeded ? Results.NoContent() : Results.Forbid();
}).RequireAuthorization("orders:write");

app.Run();

static bool HasScope(ClaimsPrincipal user, string scope) =>
    user.FindAll("scope")
        .SelectMany(c => c.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        .Contains(scope);

public partial class Program { }   // lets integration tests reference the app

OrderOwnerHandler, IOrderRepo, and Operations follow the pattern from Rung 5, applied to an Order type instead of Document.

9. The production checklist

Auth code that works on your laptop can still fail in production. Walk through this list before you ship.

Transport and cookies

[ ] HTTPS everywhere, plus UseHsts() and UseHttpsRedirection()
[ ] Cookies: HttpOnly, Secure, the right SameSite, and a __Host- prefix where possible
[ ] Sensible cookie lifetime: sliding expiry for web apps, absolute limits for sensitive ones
[ ] Antiforgery on every cookie-authenticated, state-changing endpoint

Data Protection (the #1 multi-instance bug)

Cookies, antiforgery tokens, and Identity tokens are protected by the Data Protection system. By default its keys live on each server's local disk. With multiple instances, containers, or slot swaps, every instance has different keys, and users are randomly logged out or hit "antiforgery token invalid" errors.

builder.Services.AddDataProtection()
    .SetApplicationName("my-app")                                    // same name on every instance
    .PersistKeysToStackExchangeRedis(redis, "DataProtection-Keys")   // or Blob Storage / EF Core / a shared file system
    .ProtectKeysWithAzureKeyVault(new Uri(keyUri), new DefaultAzureCredential()); // encrypt keys at rest

Each of those lines comes from its own NuGet package (for example Microsoft.AspNetCore.DataProtection.StackExchangeRedis and Azure.Extensions.AspNetCore.DataProtection.Keys). If you use Redis, it must be durable storage, not a cache that can be wiped, because losing the keys logs everyone out.

Tokens

[ ] Access tokens are short-lived; refresh tokens rotate, with reuse detection
[ ] Authority and Audience are set and every validation flag is on
[ ] RequireHttpsMetadata = true
[ ] No tokens in localStorage; use a BFF for browser apps
[ ] Tokens and secrets are never logged and never placed in URLs

Secrets and keys

[ ] Client secrets, signing keys, and connection strings live in a vault, not in appsettings.json
[ ] Certificates or managed identity are preferred over shared secrets
[ ] You have a key-rotation plan that you have actually tested

Account security (if you use Identity)

[ ] Lockout enabled, and lockoutOnFailure: true on PasswordSignInAsync
[ ] Email confirmation, and short-lived password-reset tokens
[ ] MFA available (TOTP or passkeys) and required for admins
[ ] Minimum length of 12 or more, ideally with a breached-password check (such as the HIBP k-anonymity API)
[ ] Generic error messages on login and password reset, so you don't reveal which accounts exist

Abuse protection

[ ] Rate limiting (AddRateLimiter) on login, token, password-reset, and OTP endpoints, with stricter limits than normal APIs
[ ] CORS with explicit origins only. Never combine "allow every origin" patterns with credentials
[ ] Forwarded headers accepted only from known proxies

Authorization hygiene

[ ] A fallback policy requires authentication; [AllowAnonymous] is used deliberately
[ ] Resource-based checks on every endpoint that takes an object ID
[ ] Tenant or owner filters on every query
[ ] Authorization enforced inside each service, not only at the gateway
[ ] Automated tests for your access rules (next section)

Observability

[ ] Log sign-ins, failures, lockouts, and authorization denials, without secrets or unnecessary PII
[ ] Use the built-in authentication and authorization metrics added in .NET 10 (for example, a sign-in counter) plus Identity's user-lifecycle metrics, exported with OpenTelemetry
[ ] Alert on spikes in 401/403 responses and token-validation errors

10. Test your access rules

Security rules that aren't tested quietly rot. Use integration tests with a fake authentication handler, so you don't need a real IdP:

public sealed class TestAuthHandler(
    IOptionsMonitor<AuthenticationSchemeOptions> options,
    ILoggerFactory logger,
    UrlEncoder encoder)
    : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue("X-Test-User", out var user))
            return Task.FromResult(AuthenticateResult.NoResult());

        var claims = new[]
        {
            new Claim("sub", user.ToString()),
            new Claim("scope", Request.Headers["X-Test-Scope"].ToString())
        };
        var identity = new ClaimsIdentity(claims, "Test");
        var ticket = new AuthenticationTicket(new ClaimsPrincipal(identity), "Test");
        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

public class ApiFactory : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder) =>
        builder.ConfigureTestServices(services =>
        {
            // Register a NEW scheme and make it the default.
            // (Re-registering "Bearer" would throw "Scheme already exists".)
            services.AddAuthentication(options =>
            {
                options.DefaultScheme = "Test";
                options.DefaultAuthenticateScheme = "Test";
                options.DefaultChallengeScheme = "Test";
            })
            .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>("Test", _ => { });
        });
}

public class OrdersAuthTests(ApiFactory factory) : IClassFixture<ApiFactory>
{
    [Fact]
    public async Task Anonymous_gets_401()
    {
        var client = factory.CreateClient();
        var res = await client.GetAsync("/api/orders");
        Assert.Equal(HttpStatusCode.Unauthorized, res.StatusCode);
    }

    [Fact]
    public async Task Missing_scope_gets_403()
    {
        var client = factory.CreateClient();
        client.DefaultRequestHeaders.Add("X-Test-User", "user-1");
        client.DefaultRequestHeaders.Add("X-Test-Scope", "something.else");

        var res = await client.GetAsync("/api/orders");
        Assert.Equal(HttpStatusCode.Forbidden, res.StatusCode);
    }
}

Always include negative tests: user A must never be able to read or change user B's data.

11. Twelve mistakes I keep seeing in code reviews

Turning off token validation (ValidateAudience = false) to silence an error instead of fixing the audience.
Not persisting Data Protection keys in containers, then chasing "random logouts".
Using [Authorize] alone on endpoints with an {id} parameter, so there is no ownership check.
Claim name surprises. Default inbound claim mapping renames sub, role, and others to long URI-style names. Either set MapInboundClaims = false and use the raw names everywhere, or use the mapped names everywhere. Don't mix.
Treating scope as a normal claim. It is usually one space-separated string, so RequireClaim("scope", "x") silently fails.
Storing JWTs in localStorage, which turns any XSS bug into full account takeover.
Long-lived access tokens "for convenience" with no revocation story.
Trusting X-Forwarded-* or user-ID headers from the outside. Accept them only from known proxies.
Authorizing only in the UI or at the gateway. Hiding a button is not security.
CORS shortcuts. SetIsOriginAllowed(_ => true) combined with credentials effectively allows every origin.
Rolling your own crypto, password hashing, or token format when a maintained library exists.
Wrong middleware order: UseAuthorization before UseAuthentication, or CORS after auth.

12. Wrapping up

Security in ASP.NET Core looks big until you notice it is just a few decisions:

Who is calling? That picks your authentication method (section 4).
What may they touch? That picks your authorization rung (section 6).
Will it survive production? That is the checklist (section 9).

If you remember only one thing, make it this: authentication proves who someone is once. Authorization must be re-checked for every action on every resource.

Which scenario are you securing right now: a SPA, microservices, a multi-tenant SaaS? Drop it in the comments and I'll share a tailored setup. Happy coding! 🔐

I Tested Building an Enterprise LLMOps Pipeline on Microsoft Azure. Here’s What Surprised Me.

Chethan Ramaswamy — Sun, 01 Nov 2026 08:08:36 +0000

LLMOps on Microsoft Azure: A Practical Guide to Foundry, RAG, Evaluation, and Guardrails

Getting a Large Language Model (LLM) to answer questions on localhost takes about 10 minutes and a few lines of Python.

Getting that same model into production, where it doesn't invent company policy, leak user context, or run up a surprise API bill on a Tuesday night, is where things get real.

If your team builds on the Microsoft ecosystem, you've probably heard terms like Microsoft Foundry, Azure AI Search, and Agent Framework. This guide shows how those pieces fit together in a production-grade system, which parts have changed recently, and the traps worth avoiding.

Last verified: November 2026. Foundry changes quickly, so check model names, retirement dates, and feature status against the current Microsoft docs before you ship.

The core idea: MLOps is not LLMOps

If you come from classic MLOps, it's tempting to treat LLMOps as the same thing with extra steps. It isn't.

In traditional MLOps, your main artifact is a trained model, and you measure it with metrics like accuracy, F1, or MSE. In LLMOps, you usually consume a foundation model as a service. Much of your "code" becomes the prompt, the retrieval layer, the evaluation set, and the guardrails around the model.

+--------------------------------------------------------------+
|                  THE MODERN LLMOps PIPELINE                  |
+--------------------------------------------------------------+
| 1. Model selection -->  Foundry model catalog                |
| 2. Grounding (RAG) -->  Azure AI Search (hybrid + semantic)  |
| 3. Quality gates   -->  Foundry evaluators in CI             |
| 4. Guardrails      -->  Foundry guardrails (Content Safety)  |
| 5. Observability   -->  App Insights + OpenTelemetry         |
| 6. Cost control    -->  Budgets, quotas, token tracking      |
| 7. Lifecycle       -->  Retirement dates, version pinning    |
+--------------------------------------------------------------+

Quick comparison

Operational area	Traditional MLOps	Modern LLMOps
Primary code unit	Training scripts, feature pipelines	Prompts, system instructions, RAG and agent workflows
Data engine	Feature stores, SQL pipelines	Embeddings, hybrid search indexes
Customization	Training or retraining models	Prompting, RAG context, fine-tuning (including PEFT)
Testing strategy	Deterministic metrics (accuracy, loss)	LLM-as-judge, groundedness, and safety benchmarks
Main cost driver	GPU compute hours	Token volume, prompt size, and cache efficiency
Key latency metric	Batch or inference latency	Time to first token (TTFT) and tokens per second

The architecture: how the Microsoft pieces fit together

Azure AI Studio was renamed Azure AI Foundry and is now Microsoft Foundry. It is the umbrella for building, evaluating, and deploying generative AI apps and agents.

The core players

Microsoft Foundry: Your control plane for model deployments, playground testing, agents, evaluations, guardrails, and monitoring. Resources are organized into projects.
Foundry Models (including Azure OpenAI models): Managed model endpoints with enterprise networking and identity controls. Model names and versions change often, so keep the deployment name in configuration, not in code.
Azure AI Search: The retrieval engine behind your RAG pipeline. It combines keyword (BM25) search, vector similarity, and semantic reranking.
Microsoft Agent Framework and Semantic Kernel: Open-source SDKs you use to write orchestration code. They are build-time tools, not parts of the Foundry runtime. Microsoft recommends Agent Framework (GA since April 3, 2026) as the path forward for new orchestration work, so check its current guidance before choosing between the two.
Foundry Agent Service: The managed runtime and control plane for running, securing, observing, and publishing agents. It complements the SDKs: you design the agent with a framework and operate it in Agent Service.
Guardrails (Azure AI Content Safety): Filters and protections applied to model deployments and agents.
Application Insights: Telemetry and tracing across the app.

Note on Prompt flow: Older Microsoft LLMOps guides lean on Prompt flow. It is being retired on April 20, 2027 and is no longer recommended for new development. If you have existing flows, plan a migration to Agent Framework.

Five gotchas that bite in production

1. Traditional unit tests break down

You can't write assert response == "Hello World". LLM output is non-deterministic, and a prompt tweak can improve 90% of answers while silently breaking edge cases.

The fix: add LLM-as-judge evaluations to your pull request pipeline, scored against a small "golden" dataset of realistic questions. Foundry's built-in evaluators cover areas like:

Groundedness: Did the answer stick to the retrieved context?
Relevance: Did it answer what the user asked?
Coherence: Is the output well-structured and logical?
Safety: Does it avoid policy violations and jailbreak weaknesses?

Be explicit about what your threshold means. As far as I know, the built-in AI-assisted evaluators score on a 1-5 scale, so a gate like "0.85" has to be a pass rate (the share of test cases scoring at or above a per-item threshold), not a raw score.

# .github/workflows/llmops.yml (excerpt)
- name: Run evaluation gate
  run: |
    # Fails the build if fewer than 85% of golden-set answers
    # score at least 3 (on a 1-5 scale) for groundedness
    python scripts/run_eval.py \
      --dataset tests/gold_dataset.json \
      --min-item-score 3 \
      --min-pass-rate 0.85

A minimal sketch of the script (illustrative only; check the azure-ai-evaluation docs for current constructor arguments and result keys):

# scripts/run_eval.py (sketch)
import argparse, json, sys
from azure.ai.evaluation import GroundednessEvaluator

parser = argparse.ArgumentParser()
parser.add_argument("--dataset", required=True)
parser.add_argument("--min-item-score", type=float, default=3)
parser.add_argument("--min-pass-rate", type=float, default=0.85)
args = parser.parse_args()

# model_config points at the judge model deployment
evaluator = GroundednessEvaluator(model_config=load_model_config())

rows = json.load(open(args.dataset))
passed = 0
for row in rows:
    answer = call_my_app(row["query"])          # your application under test
    result = evaluator(query=row["query"], context=row["context"], response=answer)
    if result["groundedness"] >= args.min_item_score:
        passed += 1

pass_rate = passed / len(rows)
print(f"Groundedness pass rate: {pass_rate:.0%}")
sys.exit(0 if pass_rate >= args.min_pass_rate else 1)

Offline gates catch regressions before release. They don't tell you how the system behaves on real traffic, so also sample and score production conversations (see the checklist below).

2. Pure vector search is rarely enough

Many RAG prototypes embed text and query a vector index. In practice, pure vector search tends to struggle with product codes, exact names, and acronyms.

The fix: use hybrid search in Azure AI Search, combining keyword (BM25) and vector queries, with the semantic reranker on top. Measure retrieval quality on your own golden set so you know whether it helps for your data.

3. API keys in app settings are a risk (and managed identity has its own trap)

Hardcoded or loosely managed keys leak, and rotation is painful.

The fix: use Microsoft Entra ID and managed identities so your app authenticates without stored static keys.

// Keyless authentication with Semantic Kernel
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
    deploymentName: config["Llm:ChatDeployment"],      // keep in config, not code
    endpoint: config["Llm:Endpoint"],                  // https://<your-resource>.openai.azure.com/
    credentials: new DefaultAzureCredential());        // no API key required

var kernel = builder.Build();

Two details the "no keys!" pitch often skips:

Role assignment is required. Keyless auth fails with 401/403 errors until the app's identity has an appropriate role on the resource (for example, Cognitive Services OpenAI User). Grant the least privilege your app needs.
Be deliberate about the credential. DefaultAzureCredential is convenient for local development because it tries several sources. In production, many teams use a specific credential, such as ManagedIdentityCredential, so behavior is predictable.

4. Models get retired on a fixed clock

Model versions don't live forever. At the time of writing, Microsoft's schedule showed o3-mini deprecated with a retirement in August 2026, and a widely used gpt-4o version (2024-11-20) retiring in October 2026 for many deployment types. After retirement, calls to the old deployment fail instead of quietly falling back. Dates vary by version and deployment type, and they are not always extendable, so treat the current schedule as the source of truth.

The fix:

Keep deployment names and model versions in configuration.
Subscribe to Azure Service Health alerts for your resources.
Re-run your evaluation set whenever you change or auto-upgrade a model.
Review the retirement schedule on a regular cadence.

5. Costs creep up quietly

An unbounded prompt, a retry loop, or a chatty agent can burn through tokens fast.

The fix:

Set budgets and alerts in Azure Cost Management for the subscription or resource group.
Apply quotas and rate limits on deployments, and consider an API gateway for per-app or per-user limits.
Cap max_tokens (or the equivalent) and trim retrieved context to what the model needs.
Use prompt caching where supported, and route simple tasks to smaller, cheaper models.
Track token usage per user, per feature, and per model so you can see who and what drives spend.

Production checklist

If you're taking your first LLM app to production on Azure, keep this handy:

[ ] Model strategy: Are small models (such as the Phi family) handling simple routing and summarization, with larger reasoning models reserved for complex tasks?
[ ] Model lifecycle: Are deployment names and versions in config, with retirement dates tracked and alerts on?
[ ] Prompt version control: Are prompt templates stored and versioned in Git alongside your code?
[ ] Evaluation gate: Does a batch evaluation on a golden dataset run before merging, with a clearly defined score and pass-rate threshold?
[ ] Production evaluation: Do you sample real conversations and score them for groundedness and safety over time?
[ ] Prompt-attack protection: Are Prompt Shields (via Foundry guardrails and Azure AI Content Safety) enabled to detect jailbreak and indirect prompt attacks?
[ ] Harmful content and PII handling: Are harm-category filters configured, and is PII detection or redaction in place where your data requires it? (Verify where and how PII detection runs for your setup.)
[ ] Identity: Are you using managed identities with least-privilege role assignments instead of static keys?
[ ] Observability: Are OpenTelemetry and Application Insights tracking latency (including TTFT), errors, and token spend per user?
[ ] Cost controls: Are budgets, alerts, quotas, and token limits configured?

What's next

Building with LLMs feels like magic at first. LLMOps is what turns that magic into software engineering. Set up evaluation gates early, ground your models with solid retrieval, and plan for model and platform change from day one.

Over to you: Are you running automated LLM-as-judge evaluations in CI/CD, or still spot-checking answers in the playground? Share your setup in the comments.

OWASP Top 10 for ASP.NET Core Web API: A Practical Security Guide

Chethan Ramaswamy — Sat, 10 Oct 2026 15:35:01 +0000

OWASP reference: OWASP Top
10:2025

Security note: The OWASP Top 10 is an awareness document, not a
complete security standard or a substitute for threat modeling,
security testing, and your organization's controls. The examples below
are starting points; validate them against your application's
architecture and supported .NET version.

Introduction

An ASP.NET Core Web API can have clean code, good test coverage, and a
scalable architecture---and still expose sensitive data or business
operations if its security controls are incomplete.

Security is not just adding JWT authentication or enabling HTTPS. A
production API must verify who is calling, what that caller is allowed
to do, which inputs are trusted, how secrets are managed, how failures
are handled, and whether suspicious activity can be detected.

The OWASP Top 10:2025 identifies ten major categories of web
application security risk. This article translates each category into
practical ASP.NET Core Web API guidance, with C# examples and
implementation checks.

Security foundations for an ASP.NET Core API
A01:2025 --- Broken Access Control
A02:2025 --- Security Misconfiguration
A03:2025 --- Software Supply Chain Failures
A04:2025 --- Cryptographic Failures
A05:2025 --- Injection
A06:2025 --- Insecure Design
A07:2025 --- Authentication Failures
A08:2025 --- Software or Data Integrity Failures
A09:2025 --- Security Logging and Alerting Failures
A10:2025 --- Mishandling of Exceptional Conditions
A practical API security baseline
Security checklist for code reviews
Conclusion
References

Security foundations for an ASP.NET Core API

Before looking at individual risks, establish a few fundamentals:

Authentication answers: "Who is calling?"
Authorization answers: "What is this caller allowed to do?"
Input validation checks whether data meets the API's expected shape and business rules.
Output and error handling ensure that responses disclose only what the caller should see.
Observability makes security-relevant events detectable and actionable.

For a typical API protected by an identity provider, use a standard
OAuth 2.0/OpenID Connect flow and validate access tokens with ASP.NET
Core authentication middleware. For service-to-service access in Azure,
consider Microsoft Entra ID and managed identities where supported.

A minimal JWT bearer setup can look like this:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Identity:Authority"];
        options.Audience = builder.Configuration["Identity:Audience"];
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromMinutes(1)
        };
    });

builder.Services.AddAuthorization();
builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

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

Configure the authority and audience for your identity provider. Do not
disable issuer, audience, lifetime, or signing-key validation to "make
tokens work." In production, also confirm signing-key rollover,
scopes/roles, token lifetime, and identity-provider configuration.

A01:2025 --- Broken Access Control

Broken access control occurs when an authenticated caller can perform an
operation or access a resource they should not be allowed to access.
This is one of the most important risks for APIs because clients
frequently send object identifiers such as customerId, orderId, or
accountId.

Vulnerable pattern

[HttpGet("{id:int}")]
public async Task GetOrder(int id)
{
    var order = await _db.Orders.FindAsync(id);

    return order is null ? NotFound() : Ok(order);
}

The endpoint verifies neither ownership nor permission. A caller may
change /api/orders/100 to /api/orders/101 and access another
customer's order. This is commonly described as insecure direct object
reference (IDOR), a form of broken access control.

Safer approach: enforce access at the resource query

[Authorize]
[HttpGet("{id:int}")]
public async Task GetOrder(int id)
{
    var subject = User.FindFirst("sub")?.Value;

    if (string.IsNullOrWhiteSpace(subject))
        return Forbid();

    var order = await _db.Orders
        .Where(o => o.Id == id && o.OwnerSubject == subject)
        .Select(o => new OrderResponse(o.Id, o.Status, o.Total))
        .SingleOrDefaultAsync();

    return order is null ? NotFound() : Ok(order);
}

This assumes OwnerSubject stores a stable subject identifier from the
trusted identity provider. Adapt the claim and ownership model to your
identity design. For multi-tenant systems, include tenant boundaries in
the query and verify that the tenant claim is trusted and correctly
mapped.

Practical controls

Apply [Authorize] by default to protected controllers or endpoints.
Use policies for roles, scopes, and business permissions.
Check object-level authorization on every operation that reads or changes a resource.
Do not trust a tenant ID, owner ID, role, or price supplied by the client.
Restrict mass assignment by using request DTOs instead of binding persistence entities.
Test access using different users, tenants, roles, and resource owners.

For complex rules, ASP.NET Core resource-based authorization can
centralize policy decisions. A role check alone is not enough if
permission depends on the specific resource.

A02:2025 --- Security Misconfiguration

Security misconfiguration includes unsafe defaults, exposed diagnostics,
overly permissive CORS, unnecessary endpoints, and inconsistent security
settings across environments.

Common ASP.NET Core pitfalls

Running a production environment with the Developer Exception Page.
Allowing every origin, header, and method through CORS without a business need.
Exposing Swagger/OpenAPI UI publicly when it should be restricted.
Forgetting HTTPS redirection or secure proxy configuration.
Leaving unused middleware, sample controllers, health details, or administrative endpoints exposed.
Relying on a reverse proxy to enforce controls without confirming the API's own deployment assumptions.

Configure CORS deliberately

builder.Services.AddCors(options =>
{
    options.AddPolicy("Frontend", policy =>
    {
        policy
            .WithOrigins("https://app.example.com")
            .WithMethods("GET", "POST", "PUT", "DELETE")
            .WithHeaders("Authorization", "Content-Type");
    });
});

Apply the policy explicitly:

app.UseCors("Frontend");

CORS is a browser-enforced cross-origin policy, not authentication or
authorization. Non-browser clients can call an API regardless of CORS
rules. If cookies are used, configure credentials and anti-forgery
protections carefully; never combine credentialed requests with a
wildcard origin.

Production configuration checklist

Use environment-specific configuration and safe defaults.
Keep detailed exception pages and developer tools out of production.
Restrict API documentation to intended audiences and protect it when necessary.
Trust forwarded headers only from known proxies or networks; incorrect proxy configuration can affect scheme, host, and client-IP interpretation.
Set request body and upload limits appropriate to the endpoint.
Configure security headers at the correct layer for your deployment.
Review cloud network access, private endpoints, firewall rules, and ingress settings.
Verify health endpoints disclose no secrets, connection strings, or internal topology.

A03:2025 --- Software Supply Chain Failures

Modern .NET applications depend on NuGet packages, SDKs, container base
images, build tasks, GitHub Actions or Azure DevOps tasks, and
deployment artifacts. A vulnerable or compromised dependency or build
pipeline can undermine otherwise secure application code.

Reduce dependency risk

Run dependency and vulnerability checks as part of CI:

dotnet list package --vulnerable --include-transitive

Use this command with a supported SDK and package source configuration.
For automated pipelines, combine it with dependency scanning, repository
alerts, and a policy that fails builds for vulnerabilities that exceed
your organization's risk threshold.

Practical controls

Keep supported .NET SDKs, runtimes, NuGet packages, and container images patched.
Pin or centrally manage dependency versions; review updates rather than blindly accepting them.
Commit and review packages.lock.json where deterministic package restore is part of your process.
Use trusted package feeds and protect feed credentials.
Scan direct and transitive dependencies.
Protect CI/CD identities with least privilege and short-lived credentials where possible.
Restrict who can modify pipeline definitions, release environments, and production approvals.
Generate a software bill of materials (SBOM) where required, and retain provenance for build artifacts.
Sign and verify artifacts when supported by your release platform and threat model.

A clean local build does not prove the supply chain is trustworthy. The
build agent, dependencies, package feed, and artifact promotion path are
part of the security boundary.

A04:2025 --- Cryptographic Failures

Cryptographic failures happen when sensitive data is exposed because it
is not protected appropriately, weak algorithms or key handling are
used, or secrets are stored insecurely.

Common examples

Sending credentials or tokens over plain HTTP.
Storing passwords in plaintext or using a fast general-purpose hash.
Committing database passwords or signing keys to source control.
Logging bearer tokens, API keys, or personal data.
Using custom encryption instead of established platform libraries.
Keeping encryption keys next to the encrypted data without suitable access controls.

Protect secrets outside source code

For local development, use the .NET Secret Manager for development-only
secrets. It is not an encrypted production secret vault. In Azure,
prefer Key Vault and managed identity rather than storing long-lived
credentials in configuration files.

// Example: access a secret through configuration.
// The production configuration provider should retrieve it
// from an approved secret store such as Azure Key Vault.
var connectionString =
    builder.Configuration.GetConnectionString("OrdersDatabase");

if (string.IsNullOrWhiteSpace(connectionString))
{
    throw new InvalidOperationException(
        "The OrdersDatabase connection string is not configured.");
}

The example does not itself connect to Key Vault; configure the
appropriate provider and identity for your environment.

Practical controls

Enforce HTTPS and correctly configure TLS at the ingress and application layers.
Use platform password-hashing facilities such as ASP.NET Core Identity rather than inventing a password hash scheme.
Store keys and secrets in a dedicated secret-management service with access auditing and rotation.
Encrypt sensitive data at rest when required by the data classification and threat model.
Minimize the sensitive data you collect, return, and retain.
Redact credentials and personal data from logs, traces, and exception messages.
Use cryptographic libraries and algorithms recommended by current platform guidance.

Encryption is not a replacement for authorization. If an attacker can
legitimately retrieve decrypted data through an over-permissive API,
encryption at rest will not solve the access-control problem.

A05:2025 --- Injection

Injection occurs when untrusted input is interpreted as executable SQL,
a shell command, a query language expression, or another instruction.

SQL injection: unsafe string concatenation

// Do not do this.
var sql = $"SELECT * FROM Orders WHERE CustomerId = '{customerId}'";

If the input is incorporated into SQL syntax, an attacker may alter the
query's meaning.

Prefer parameterized queries

With EF Core, normal LINQ queries are parameterized:

var orders = await _db.Orders
    .Where(o => o.CustomerId == customerId)
    .ToListAsync();

For raw SQL, use parameterized APIs:

var orders = await _db.Orders
    .FromSqlInterpolated(
        $"SELECT * FROM Orders WHERE CustomerId = {customerId}")
    .ToListAsync();

FromSqlInterpolated parameterizes interpolated values. Do not replace
it with FromSqlRaw plus string concatenation. SQL parameters cannot
safely stand in for identifiers such as table names or sort directions;
map those choices to a fixed allowlist.

Validate input as well

public sealed record CreateOrderRequest(
    [property: Required] string CustomerReference,
    [property: Range(1, 100)] int Quantity);

Use request DTOs and server-side validation, but remember that
validation does not replace parameterized queries. Also:

Avoid building shell commands from request values.
Avoid unsafe dynamic expression construction.
Treat uploaded files, headers, query parameters, and message-queue payloads as untrusted.
Encode output appropriately when returning data to HTML-rendering clients.
Review XML parsers, template engines, and search/query DSLs for injection-specific settings.

ASP.NET Core APIs often return JSON rather than HTML, so classic
reflected XSS is less common in the API response itself. However, unsafe
content may later be rendered by a browser-based client. JSON does not
make untrusted content safe for every downstream consumer.

A06:2025 --- Insecure Design

Insecure design is a weakness in the system's requirements, workflows,
or trust assumptions---not merely a coding defect. A technically correct
endpoint can still implement an unsafe business process.

Example: trusting a client-supplied price

public sealed record CreateOrderRequest(
    int ProductId,
    int Quantity,
    decimal UnitPrice); // Do not trust this price from the client.

If the API accepts the price as authoritative, a caller may submit a
lower value than the real product price.

Instead, accept only the data the client is allowed to choose and
calculate authoritative values on the server:

public sealed record CreateOrderRequest(int ProductId, int Quantity);

[Authorize]
[HttpPost]
public async Task CreateOrder(
    CreateOrderRequest request,
    CancellationToken cancellationToken)
{
    if (request.Quantity is < 1 or > 100)
        return BadRequest("Quantity is outside the permitted range.");

    var product = await _db.Products
        .SingleOrDefaultAsync(
            p => p.Id == request.ProductId && p.IsActive,
            cancellationToken);

    if (product is null)
        return NotFound();

    var order = new Order
    {
        ProductId = product.Id,
        Quantity = request.Quantity,
        UnitPrice = product.CurrentPrice
    };

    _db.Orders.Add(order);
    await _db.SaveChangesAsync(cancellationToken);

    return CreatedAtAction(
        nameof(GetOrder),
        new { id = order.Id },
        new { order.Id, order.Quantity, order.UnitPrice });
}

This is illustrative; production code should also validate inventory,
currency, discounts, tax, concurrency, customer eligibility, and
transaction boundaries.

Design controls before coding

Threat-model important flows such as payments, account recovery, tenant administration, and bulk exports.
Define authorization rules for every operation and resource.
Set limits for pagination, batch size, file size, request rate, and expensive queries.
Make state transitions explicit and reject invalid transitions.
Use idempotency keys for operations where retries could create duplicate effects.
Require additional verification for high-impact actions when appropriate.
Design for abuse cases, not only expected user journeys.
Document trust boundaries between the API, identity provider, database, queues, and external services.

Security requirements should be acceptance criteria, not a last-minute
checklist after the feature is built.

A07:2025 --- Authentication Failures

Authentication failures include weak credential handling, incorrect
token validation, insecure authentication flows, and gaps in session or
account lifecycle controls.

Validate bearer tokens properly

Use the framework's JWT bearer middleware or a supported
identity-provider integration. Do not manually decode a JWT and treat
its claims as trusted without verifying the signature and relevant
validation rules.

For access tokens, verify at least:

Signature and signing key.
Issuer.
Audience.
Expiration and not-before timestamps.
Required scopes or roles for the API operation.
Token type and accepted algorithms as appropriate to the identity provider.

A valid token proves neither that the caller owns a specific record nor
that every operation is permitted.

Practical controls

Prefer established identity providers over custom authentication implementations.
Use authorization-code flow with PKCE for appropriate interactive clients; use client credentials for service-to-service access where appropriate.
Do not use the OAuth resource-owner-password credentials flow for new designs.
Apply rate limits and monitoring to login, password reset, OTP, and token-related endpoints.
Use MFA for privileged and high-risk accounts where applicable.
Avoid revealing whether a username or email exists in authentication and recovery responses.
Rotate and revoke credentials when compromise is suspected.
Keep access tokens out of URLs, logs, analytics, and error reports.
Use managed identities for supported Azure service-to-service access rather than embedded secrets.

Authorization is still separate

[Authorize(Policy = "Orders.Read")]
[HttpGet("{id:int}")]
public Task GetOrder(int id)
{
    // The policy checks a permission; the implementation must still
    // verify that the caller may access this particular order.
    throw new NotImplementedException();
}

Define the policy in the service configuration and adapt the claim type
to your identity provider:


 csharp
builder.

Abstract Class vs Interface in C#: Demystifying the Difference

Chethan Ramaswamy — Tue, 06 Oct 2026 16:51:02 +0000

Abstract Class vs Interface in C#: Demystifying the Difference

Introduction

Few C# interview questions create as much confusion as:

"What is the difference between an abstract class and an interface,
and when should I use each?"

Many developers memorize a comparison table:

Abstract class → can have implementation
Interface → defines a contract
Abstract class → supports fields
Interface → does not
Abstract class → single inheritance
Interface → multiple inheritance

These statements are useful, but they do not answer the most important
question:

Why would I choose one over the other when designing a real
application?

This article builds the answer from first principles.

The simplest way to remember it is:

An interface describes what a type can do. An abstract class
describes what a family of related types fundamentally is, while
allowing shared behavior.

That distinction is much more valuable than memorizing syntax.

1. Start With the Real Design Problem

Suppose we are building an application that sends notifications.

We may have:

Email notification
SMS notification
Push notification

All of them can send a notification.

That immediately suggests a contract:

public interface INotificationSender
{
    Task SendAsync(string message);
}

Now imagine that all notification providers also need:

Common logging
Common validation
A provider name
Shared retry behavior

That may suggest an abstract base class:

public abstract class NotificationSender
{
    protected readonly ILogger Logger;

    protected NotificationSender(ILogger logger)
    {
        Logger = logger;
    }

    public abstract Task SendAsync(string message);

    protected void LogSending(string message)
    {
        Logger.LogInformation("Sending notification: {Message}", message);
    }
}

The two abstractions solve different design problems.

The interface says:

"Anything implementing me promises that it can send a notification."

The abstract class says:

"These objects belong to the same conceptual family and can share
state and implementation."

That is the core distinction.

2. What Is an Interface?

An interface is a contract.

It defines capabilities that a type promises to provide.

public interface IPaymentProcessor
{
    Task ProcessPaymentAsync(decimal amount);
}

A class implements that contract:

public class StripePaymentProcessor : IPaymentProcessor
{
    public async Task ProcessPaymentAsync(decimal amount)
    {
        // Stripe-specific implementation
    }
}

Another implementation can provide a completely different
implementation:

public class RazorpayPaymentProcessor : IPaymentProcessor
{
    public async Task ProcessPaymentAsync(decimal amount)
    {
        // Razorpay-specific implementation
    }
}

The important point is:

The interface does not care how payment is processed.

It only defines the capability.

3. What Is an Abstract Class?

An abstract class is a base type that is incomplete by design.

It can contain:

Abstract methods
Concrete methods
Fields
Properties
Constructors
Protected members
Shared state
Static members

Example:

public abstract class PaymentProcessor
{
    protected readonly ILogger Logger;

    protected PaymentProcessor(ILogger logger)
    {
        Logger = logger;
    }

    public abstract Task ProcessPaymentAsync(decimal amount);

    protected void LogPayment(decimal amount)
    {
        Logger.LogInformation(
            "Processing payment of {Amount}",
            amount);
    }
}

A derived class must implement the abstract operation:

public class StripePaymentProcessor : PaymentProcessor
{
    public StripePaymentProcessor(ILogger logger)
        : base(logger)
    {
    }

    public override async Task ProcessPaymentAsync(decimal amount)
    {
        LogPayment(amount);

        // Stripe-specific implementation
    }
}

Here the base class provides common behavior and state, while
subclasses provide specialized behavior.

4. The Most Important Difference

The easiest mental model is:

Interface = Capability

Ask:

"What can this object do?"

Examples:

IEnumerable
IDisposable
IComparable
ILogger
IPaymentProcessor
INotificationSender

A class may support several unrelated capabilities.

For example:

public class OrderService :
    IOrderService,
    IDisposable,
    IAsyncDisposable
{
}

These interfaces describe capabilities/contracts.

Abstract Class = Family / Common Foundation

Ask:

"What is this object fundamentally, and what behavior should all
members of this family share?"

For example:

PaymentProcessor
    ├── StripePaymentProcessor
    ├── RazorpayPaymentProcessor
    └── PayPalPaymentProcessor

They share a common conceptual foundation.

Therefore an abstract class can make sense.

5. A Powerful Interview Rule

When deciding between them, ask two questions.

Question 1

Is this a capability that unrelated classes may need?

If yes, prefer an interface.

Example:

public interface IAuditable
{
    DateTime CreatedAt { get; }
}

A customer, order, invoice, or product could all be auditable.

They do not need to belong to the same inheritance hierarchy.

Question 2

Do these classes belong to the same conceptual family and need
shared state or implementation?

If yes, an abstract class may be appropriate.

Example:

DocumentProcessor
    ├── PdfProcessor
    ├── WordProcessor
    └── ExcelProcessor

All processors may share:

File validation
Logging
Configuration
Metrics
Common processing workflow

An abstract base class can encapsulate that common behavior.

6. Side-by-Side Comparison

Aspect	Difference
Purpose	Abstract class provides a common foundation. Interface defines a contract or capability.
Implementation	Abstract class can provide shared implementation. Interface can also provide default implementations in modern C#.
State	Abstract class can contain instance state. Interface cannot contain instance fields.
Constructors	Abstract class can have constructors. Interfaces cannot have instance constructors.
Inheritance	A class can inherit only one base class. A class can implement multiple interfaces.
Coupling	Abstract classes create a stronger relationship. Interfaces generally provide looser coupling.
Best use	Use for shared behavior, state, or workflow.
Typical example	`FileProcessor` → `PdfProcessor`, `ExcelProcessor`
Interface example	`INotificationSender` → `EmailSender`, `SmsSender`

7. Why Does C# Allow Multiple Interfaces but Only One Base Class?

Consider:

public class ReportService :
    IReportGenerator,
    IAuditable,
    IDisposable
{
}

A class can implement multiple interfaces.

Why?

Because these interfaces represent independent capabilities:

ReportService
 ├── IReportGenerator
 ├── IAuditable
 └── IDisposable

But C# allows only one class inheritance chain:

public class ReportService : BaseReportService
{
}

The reason is that inheriting implementation and state creates much
stronger relationships.

If multiple base classes were allowed, problems such as conflicting
implementations and state become much harder to reason about.

So C# deliberately separates:

Capability composition

from

Implementation inheritance

8. Real Example: Interface Is Better

Imagine a logging system.

public interface INotificationSender
{
    Task SendAsync(string recipient, string message);
}

Implementations:

public class EmailNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        // Send email
        return Task.CompletedTask;
    }
}

public class SmsNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        // Send SMS
        return Task.CompletedTask;
    }
}

Why interface?

Because email and SMS are not necessarily related by inheritance.

They simply share a capability:

They can send notifications.

The interface keeps the design loosely coupled.

9. Real Example: Abstract Class Is Better

Consider file processors.

public abstract class FileProcessor
{
    public async Task ProcessAsync(string filePath)
    {
        Validate(filePath);

        await ReadAsync(filePath);

        Log(filePath);
    }

    protected void Validate(string filePath)
    {
        if (string.IsNullOrWhiteSpace(filePath))
            throw new ArgumentException("Invalid file path.");
    }

    protected abstract Task ReadAsync(string filePath);

    protected void Log(string filePath)
    {
        Console.WriteLine($"Processed {filePath}");
    }
}

Now:

public class PdfProcessor : FileProcessor
{
    protected override Task ReadAsync(string filePath)
    {
        // PDF-specific logic
        return Task.CompletedTask;
    }
}

And:

public class ExcelProcessor : FileProcessor
{
    protected override Task ReadAsync(string filePath)
    {
        // Excel-specific logic
        return Task.CompletedTask;
    }
}

The abstract class provides a common workflow:

Validate
   ↓
Read
   ↓
Log

Only the specialized operation changes.

This is a classic use case for an abstract class.

10. Interface Does NOT Mean "No Implementation"

This is an important misconception.

Modern C# interfaces can contain default implementations.

For example:

public interface ILogger
{
    void Log(string message);

    void LogError(string message)
    {
        Log($"ERROR: {message}");
    }
}

So this statement is outdated:

"Interfaces cannot contain implementation."

A better statement is:

Interfaces primarily define contracts, but modern C# allows them to
provide default implementations as well.

However, that does not mean interfaces should become replacements for
abstract classes.

Default interface implementations solve specific versioning and
API-evolution scenarios. They do not provide instance state or turn an
interface into a normal stateful base class.

11. Abstract Class vs Interface in Dependency Injection

This is where interfaces are extremely common in .NET applications.

Example:

public interface IOrderRepository
{
    Task GetByIdAsync(int id);
}

Implementation:

public class SqlOrderRepository : IOrderRepository
{
    public Task GetByIdAsync(int id)
    {
        // Database implementation
        throw new NotImplementedException();
    }
}

builder.Services.AddScoped();

The application depends on:

IOrderRepository

instead of:

SqlOrderRepository

This provides loose coupling.

It also makes testing easier:

public class FakeOrderRepository : IOrderRepository
{
    // Test implementation
}

This is one reason interfaces are heavily used in enterprise .NET
applications.

12. Does That Mean We Should Always Use Interfaces?

No.

This is another common mistake.

Some developers create an interface for every single class:

CustomerService
ICustomerService

OrderService
IOrderService

ProductService
IProductService

without any real architectural reason.

This can produce unnecessary abstraction.

For example, if a class:

Has one implementation
Is internal to a small module
Does not need polymorphism
Does not represent a meaningful boundary

then creating an interface may add complexity without providing much
value.

The goal is not:

"Use interfaces everywhere."

The goal is:

Use abstraction where it creates a useful boundary.

13. When Should You Use an Interface?

Prefer an interface when:

1. You need a contract

public interface IPaymentProcessor
{
    Task ProcessAsync(decimal amount);
}

2. Multiple unrelated classes need the same capability

Order
Customer
Invoice
Product

could all implement:

IAuditable

3. You need multiple capabilities

public class Order :
    IAuditable,
    IValidatable,
    IExportable
{
}

4. You want loose coupling

Especially across application boundaries such as:

Controller
   ↓
Application Service
   ↓
Interface
   ↓
Implementation

5. You expect multiple implementations

For example:

IPaymentProcessor
    ├── StripePaymentProcessor
    ├── RazorpayPaymentProcessor
    └── MockPaymentProcessor

14. When Should You Use an Abstract Class?

Prefer an abstract class when:

1. There is a strong "is-a" relationship

PdfProcessor is a FileProcessor
ExcelProcessor is a FileProcessor

2. Subclasses need shared implementation

protected void Validate()
{
}

3. Subclasses need shared state

protected readonly ILogger Logger;

4. You want to enforce a common workflow

For example:

Validate
   ↓
Authenticate
   ↓
Process
   ↓
Audit

This is commonly implemented using the Template Method pattern.

5. You control the inheritance hierarchy

An abstract base class creates a stronger relationship than an
interface, so it should be used deliberately.

15. A Real Enterprise Example

Imagine an order-processing platform.

We might have:

IOrderProcessor

as the contract:

public interface IOrderProcessor
{
    Task ProcessAsync(Order order);
}

Different implementations:

OnlineOrderProcessor
StoreOrderProcessor
PartnerOrderProcessor

Now suppose every processor needs common behavior:

Validate order
Create correlation ID
Start telemetry
Execute processing
Audit result

An abstract class could provide that workflow:

public abstract class OrderProcessorBase
{
    public async Task ProcessAsync(Order order)
    {
        Validate(order);

        await ProcessCoreAsync(order);

        Audit(order);
    }

    protected virtual void Validate(Order order)
    {
        // Common validation
    }

    protected abstract Task ProcessCoreAsync(Order order);

    protected virtual void Audit(Order order)
    {
        // Common audit
    }
}

A concrete processor then implements only the variable portion:

public class OnlineOrderProcessor : OrderProcessorBase
{
    protected override Task ProcessCoreAsync(Order order)
    {
        // Online-order-specific logic
        return Task.CompletedTask;
    }
}

This gives us:

Common workflow
      ↓
Abstract base class
      ↓
Specialized implementations

If consumers should depend on a stable contract, we can additionally
expose an interface:

IOrderProcessor
       ↑
OrderProcessorBase
       ↑
OnlineOrderProcessor

The two mechanisms are not competitors.

They can work together.

16. Interface + Abstract Class Together

This is a powerful enterprise pattern.

public interface IFileProcessor
{
    Task ProcessAsync(string filePath);
}

Then:

public abstract class FileProcessorBase : IFileProcessor
{
    public async Task ProcessAsync(string filePath)
    {
        Validate(filePath);

        await ProcessCoreAsync(filePath);

        Audit(filePath);
    }

    protected abstract Task ProcessCoreAsync(string filePath);

    protected virtual void Validate(string filePath)
    {
        // Common validation
    }

    protected virtual void Audit(string filePath)
    {
        // Common auditing
    }
}

Concrete implementation:

public class PdfProcessor : FileProcessorBase
{
    protected override Task ProcessCoreAsync(string filePath)
    {
        // PDF processing
        return Task.CompletedTask;
    }
}

Now we have:

Interface

Defines the external contract

Abstract class

Provides reusable implementation

Concrete class

Provides specific behavior

This is often cleaner than trying to force one abstraction to do
everything.

17. The "Can Do" vs "Is A" Rule

A classic rule is:

Interface = can do

Abstract class = is a

For example:

Bird

A bird:

is a Bird

But:

IFlyable

means:

can fly

So:

public abstract class Bird
{
    public abstract void Eat();
}

and:

public interface IFlyable
{
    void Fly();
}

Then:

public class Eagle : Bird, IFlyable
{
    public override void Eat()
    {
    }

    public void Fly()
    {
    }
}

But be careful.

The "is-a / can-do" rule is a useful mental model, not an absolute law.

Modern software design often focuses more on:

Responsibilities
Coupling
Composition
Polymorphism
Reuse
Changeability

than on inheritance terminology alone.

18. Composition vs Inheritance

One of the most important design l

Agentic AI for Beginners: What Are AI Agents and How Do They Actually Work?

Chethan Ramaswamy — Wed, 30 Sep 2026 15:27:05 +0000

Agentic AI for Beginners: What Are AI Agents and How Do They Actually Work?

AI agents are not just chatbots with a fancy name. They can use AI models to understand goals, choose actions, use tools, observe results, and continue working until a task is completed.

Artificial Intelligence is moving beyond systems that simply generate text.

Traditional software follows instructions explicitly defined by developers.

Generative AI can understand natural language and generate text, code, images, and other content.

Agentic AI goes one step further: it enables software systems to use AI models to decide what actions should be taken to accomplish a goal.

This creates a new way of building software.

Instead of telling a system:

"Execute these five steps in this exact order."

we can give it:

"Achieve this goal."

The system can then determine which steps are necessary, which tools it needs, and when the task is complete.

However, this does not mean that AI agents should be given unlimited autonomy.

Production-grade agentic systems require clear boundaries, permissions, security, observability, cost controls, and often human approval.

This article explains Agentic AI from the ground up.

No previous AI knowledge is required.

1. Introduction

Let's start with a simple example.

Imagine you ask an AI assistant:

"Find my last three orders and tell me which one was delivered late."

A traditional chatbot may respond:

"I don't have access to your order system."

An AI agent could potentially:

Understand the request.
Identify that it needs order information.
Call the order-management API.
Retrieve the last three orders.
Analyze delivery dates.
Determine which order was late.
Return the result.

The important difference is not simply that the second system uses a more powerful AI model.

The important difference is that the system can take actions using tools.

A simplified view looks like this:

Traditional Chatbot

User
  |
  v
LLM
  |
  v
Response

An agent looks more like this:

User
  |
  v
AI Agent
  |
  +----> Reason
  |
  +----> Choose Tool
  |
  +----> Execute Action
  |
  +----> Observe Result
  |
  +----> Reason Again
  |
  v
Final Response

This ability to move from generating text to performing authorized actions is one of the important ideas behind Agentic AI.

2. What Is Generative AI?

Before understanding agents, we need to understand Generative AI.

Generative AI refers to AI systems that can generate new content based on an input.

The generated content could be:

Text
Code
Images
Audio
Video
Structured data

Large Language Models, commonly called LLMs, are a major component of modern Generative AI applications.

At a simplified level:

User Prompt
     |
     v
+-------------+
|     LLM     |
+-------------+
     |
     v
Generated Response

For example:

User:

Explain dependency injection in .NET.

The model can generate an explanation.

However, there is an important limitation.

An LLM does not automatically have direct access to:

Your database
Your CRM
Your ERP
Your internal APIs
Your payment system
Your monitoring platform
Your private documents

This is where tools and agentic architectures become important.

LLM vs Application

It is useful to separate the AI model from the software application around it.

                 AI Application
                       |
          +------------+------------+
          |                         |
          v                         v
       AI Model                  Software
          |                         |
          v                         v
    Reasoning/Text            APIs/Database/Tools

The LLM provides capabilities such as language understanding and generation.

The surrounding application provides access to business systems, data, tools, security, and application logic.

An AI agent is built by combining these capabilities in a controlled way.

3. What Is an AI Agent?

An AI agent is a software system that uses an AI model to determine and execute actions toward a goal.

A simplified conceptual model is:

        Goal
          |
          v
      AI Model
          |
          v
       Decision
          |
          v
        Tool
          |
          v
       Result
          |
          v
      AI Model
          |
          v
    Next Decision

An agent typically combines several capabilities:

             AI AGENT
                 |
     +-----------+-----------+
     |           |           |
     v           v           v
    LLM        Tools       Memory
     |           |           |
     v           v           v
 Reasoning    Actions      Context

Depending on the architecture, an agent may also have:

Planning
State management
Retrieval
Guardrails
Human approval
Long-term memory
Short-term memory
Multiple specialized agents

The important point is:

An AI agent is not simply an LLM.

The LLM is usually the reasoning component inside a larger software system.

A useful mental model

Think of an LLM as a highly capable decision-making component.

Think of an agent as the software system that gives that component the ability to interact with the world through controlled interfaces.

LLM
 |
 | decides what may be needed
 v
Agent Runtime
 |
 +---- Tool
 +---- Memory
 +---- Retrieval
 +---- State
 +---- Guardrails
 |
 v
External Systems

4. Chatbot vs AI Agent

One of the easiest ways to understand Agentic AI is to compare it with a traditional chatbot.

Traditional Chatbot

Suppose you ask:

"What is the status of order 12345?"

A traditional chatbot might search a knowledge base and respond with information.

User
 |
 v
Chatbot
 |
 v
Knowledge Base
 |
 v
Response

AI Agent

An agent could:

User
 |
 v
Agent
 |
 +----> Identify Order
 |
 +----> Call Order API
 |
 +----> Get Delivery Status
 |
 +----> Check Shipping API
 |
 +----> Analyze Result
 |
 v
Response

The distinction can be summarized as:

Capability	Chatbot	AI Agent
Understand natural language	Yes	Yes
Generate responses	Yes	Yes
Retrieve information	Often	Yes
Call tools	Sometimes	Common
Perform actions	Limited	Possible
Dynamic decision-making	Limited	Common
Multi-step tasks	Limited	Common
External system interaction	Optional	Common

However, these are not strict technical categories.

A chatbot can use tools.

An agent can be implemented with a relatively simple workflow.

The terminology is evolving, so focus on capabilities and architecture, not labels.

The key difference

A useful way to think about it is:

Chatbot

Question
   |
   v
Answer

versus:

Agent

Goal
 |
 v
Understand
 |
 v
Decide
 |
 v
Act
 |
 v
Observe
 |
 v
Decide Again
 |
 v
Complete

The agent is oriented around achieving a goal, not merely generating a response.

5. The Anatomy of an AI Agent

Let's break an agent into its major components.

A simplified architecture is:

                 +----------------+
                 |      User      |
                 +-------+--------+
                         |
                         v
                 +----------------+
                 |   AI Agent     |
                 +----------------+
                         |
          +--------------+--------------+
          |              |              |
          v              v              v
      AI Model         Tools          Memory
          |              |              |
          v              v              v
      Reasoning       Actions        Context
                         |
              +----------+----------+
              |          |          |
              v          v          v
             API       Database    Search

Let's understand each component.

5.1 AI Model

The AI model provides language understanding and reasoning capabilities.

It can help determine:

What the user wants
What information is required
Which tool may be useful
What parameters should be provided
Whether another action is necessary

The model does not necessarily execute the action itself.

It can instead produce a structured tool request.

For example:

{
  "tool": "GetOrder",
  "arguments": {
    "orderId": "12345"
  }
}

The application can validate that request and execute the corresponding operation.

5.2 Tools

Tools allow the agent to interact with the outside world.

Examples:

Database
REST API
Search Engine
Calculator
CRM
ERP
Email
Calendar
File Storage
Code Execution

For example:

Agent
  |
  +----> Customer API
  |
  +----> Order API
  |
  +----> Payment API
  |
  +----> Notification API

Tools are what allow an agent to move from:

"I think this is the answer."

to:

"I can retrieve information or perform an authorized operation."

5.3 Memory

Memory allows the system to maintain relevant information during or across interactions.

For example:

User:

My preferred programming language is C#.

Later:

User:

Show me an example.

A system with appropriate memory may know that the user prefers C#.

Memory can be divided into different categories.

Short-Term Memory

Information needed during the current task.

Current conversation
Current goal
Current tool results
Current state

Long-Term Memory

Information that may be useful across future interactions.

Preferences
Historical interactions
Previously stored information
User-specific context

Memory architecture is an important topic by itself and should not be confused with simply putting more text into a prompt.

5.4 State

State represents what the agent currently knows about the task.

For example:

Task: Process customer refund

State:
- Customer identified
- Order identified
- Refund eligibility checked
- Refund amount calculated
- Approval required

State becomes particularly important for long-running or multi-step agents.

5.5 Guardrails

Guardrails define what the agent is allowed and not allowed to do.

For example:

Agent
 |
 +---- Read Customer Data
 |
 +---- Read Order Data
 |
 +---- Create Support Ticket
 |
 X---- Delete Customer
 |
 X---- Issue Unlimited Refund

Guardrails are critical because an agent that can call tools has real-world capabilities.

6. How an Agent Works

Let's walk through a simple example.

Suppose the user says:

"Find the weather in Bangalore and suggest whether I should carry an umbrella."

A simplified agent process could be:

Step 1: Understand the request

The agent identifies:

Location = Bangalore
Task = Get weather
Task = Recommend umbrella

Step 2: Identify the required tool

The agent determines that it needs current weather information.

Available Tools

- Weather API
- Calculator
- Search
- Calendar

It selects:

Weather API

Step 3: Call the tool

The agent sends:

{
  "location": "Bangalore"
}

to the weather tool.

Step 4: Observe the result

The tool may return:

{
  "temperature": 24,
  "rainProbability": 80,
  "condition": "Rain expected"
}

Step 5: Reason over the result

The agent interprets the result.

Rain probability = 80%

Therefore:
Carry an umbrella.

Step 6: Generate the final response

The user receives:

"Rain is likely today, so carrying an umbrella would be a good idea."

The important part is that the model did not need to know the current weather beforehand.

It used a tool to retrieve current information.

7. The Agent Loop

One of the most important concepts in Agentic AI is the agent loop.

A simplified agent loop looks like this:

             +----------------+
             |     Goal       |
             +-------+--------+
                     |
                     v
             +----------------+
             |     Reason     |
             +-------+--------+
                     |
                     v
             +----------------+
             |      Act       |
             +-------+--------+
                     |
                     v
             +----------------+
             |    Observe     |
             +-------+--------+
                     |
                     v
             +----------------+
             |     Reason     |
             +-------+--------+
                     |
                     v
                  Complete?
                   /     \
                 No       Yes
                 |         |
                 +---------+
                       |
                       v
                  Final Result

This can be summarized as:

Reason → Act → Observe → Reason → Act → ...

The loop continues until the task is complete or another termination condition is reached.

Example

Suppose an agent is asked:

"Find the cheapest flight to London within my budget and book it."

The agent might:

Goal
 |
 v
Search Flights
 |
 v
Observe Results
 |
 v
Compare Prices
 |
 v
Check Budget
 |
 +---- Budget exceeded ---> Search Again
 |
 v
Select Flight
 |
 v
Ask for Approval
 |
 v
Book Flight
 |
 v
Complete

Notice that the agent may not know all the required steps before starting.

The environment can influence what happens next.

Why the loop matters

The loop gives agents their dynamic behavior.

Traditional code often looks like:

Step 1
Step 2
Step 3
Step 4

An agent can behave more like:

Goal
 |
 v
What should I do next?
 |
 v
Action
 |
 v
What did I learn?
 |
 v
What should I do next?

This is powerful, but it also introduces additional risks.

More autonomy means more opportunities for:

Incorrect decisions
Tool misuse
Unexpected costs
Security issues
Infinite loops
Incorrect data
Unintended actions

Therefore, production agents need strong controls.

8. What Are Tools?

Tools give an AI agent the ability to interact with external systems.

Examples include:

REST APIs
Databases
Search engines
Calculators
CRM systems
ERP systems
Email systems
Calendar systems
File systems
Internal enterprise applications

For example:

                    AI Agent
                       |
        +--------------+--------------+
        |              |              |
        v              v              v
    Customer API    Order API     Payment API

Tool Calling

Modern AI models can be provided with a list of tools and their descriptions.

For example:

Tool: GetOrder

Description:
Retrieves an order using an order ID.

Parameters:
- orderId: string

The model may determine that this tool is appropriate and produce a structured request.

{
  "tool": "GetOrder",
  "arguments": {
    "orderId": "12345"
  }
}

The application then:

Receives the tool request.
Validates the arguments.
Checks authorization.
Executes the tool.
Returns the result to the model.

This is an important architectural point:

The AI model should not automatically receive unrestricted access to your systems.

The application should remain in control.

Tools should be treated as APIs

A good enterprise design treats agent tools similarly to APIs.

Each tool should have:

Clear input schema
Clear output schema
Authentication
Authorization
Validation
Logging
Rate limits
Timeouts
Error handling

For example:

AI Agent
   |
   v
Tool Gateway
   |
   +---- Authorization
   +---- Validation
   +---- Rate Limiting
   +---- Audit Logging
   |
   v
Business API

9. What Is Memory?

Memory allows an agent to maintain relevant information during or across interactions.

There are two common conceptual categories.

Short-Term Memory

Information required for the current task.

Examples:

Current conversation
Current goal
Tool results
Current state
Intermediate decisions

Current Task
     |
     v
+--------------------+
| Short-Term Memory  |
+--------------------+

Long-Term Memory

Information that may remain useful across future interactions.

Examples:

User preferences
Historical information
Previously stored context
Business-specific knowledge

                 Agent
                   |
                   v
            Memory Service
                   |
          +--------+--------+
          |                 |
          v                 v
     Short-Term        Long-Term
       Memory            Memory

Memory is not the same as context

This distinction is important.

Context is information supplied to the model for the current interaction.

Memory is information that the system deliberately stores and retrieves for future or ongoing use.

For example:

Context:

Current conversation
Current tool result
Current task state

while:

Memory:

User preference
Previous interaction
Stored business information

Memory introduces architectural questions

A production system needs to decide:

What should be remembered?
How long should it be retained?
Where should it be stored?
Who can access it?
How should it be retrieved?
How can incorrect memories be corrected?
How should sensitive information be handled?

Memory should therefore be treated as an architectural capability, not simply a feature that is switched on.

10. What Is Planning?

Some tasks require multiple steps.

For example:

"Plan a business trip to London within a budget of ₹2,00,000."

The agent may need to:

Search flights.
Compare prices.
Search hotels.
Calculate the total cost.
Check the budget.
Find transportation.
Create an itinerary.

Planning allows an agent to break a high-level goal into smaller actions.

Goal
 |
 +---> Find Flights
 |
 +---> Find Hotel
 |
 +---> Calculate Cost
 |
 +---> Check Budget
 |
 +---> Find Transportation
 |
 +---> Create Itinerary

Planning does not always mean creating a perfect plan upfront

A common beginner assumption is:

"The agent first creates the entire plan and then executes it."

That is one possible approach, but agents can also plan dynamically.

For example:

Goal
 |
 v
Plan Step 1
 |
 v
Execute
 |
 v
Observe
 |
 v
Update Plan
 |
 v
Execute Next Step

The result of one action can influence the next action.

Planning vs deterministic orchestration

This is an important architectural distinction.

If your business process is known:

Validate
 |
 v
Approve
 |
 v
Create Order
 |
 v
Send Notification

you may not need an AI agent.

A normal workflow may be simpler, cheaper, more predictable, and easier to test.

Planning becomes more useful when the task is dynamic and the exact sequence cannot easily be predefined.

11. A Real-World Example

Consider an enterprise customer-support agent.

A customer asks:

"My order hasn't arrived. Can you check what's happening?"

The agent might perform:

Customer
   |
   v
AI Agent
   |
   +----> Customer API
   |
   +----> Order API
   |
   +----> Shipping API
   |
   v
Analyze Information
   |
   v
Generate Response

The agent could discover:

Order Status: Shipped
Expected Delivery: September 30
Current Status: Delayed
Reason: Weather disruption

It can then explain the situation to the customer.

With appropriate authorization, the same system could potentially:

Create a support ticket
Send an email
Request a replacement
Escalate the issue

Enterprise architecture

A more production-oriented architecture could look like:

                         Customer
                            |
                            v
                    +---------------+
                    | API Gateway   |
                    +-------+-------+
                            |
                            v
                    +---------------+
                    | AI Agent      |
                    +-------+-------+
                            |
             +--------------+--------------+
             |              |              |
             v              v              v
       Customer Tool   Order Tool    Shipping Tool
             |              |              |
             v              v              v
          CRM/API        Order API      Carrier API

Additional enterprise capabilities would typically include:

Authentication
Authorization
Audit Logging
Observability
Rate Limiting
Secrets Management
Guardrails
Human Approval

Human-in-the-loop

Suppose the customer asks:

"Refund my entire order."

The agent might determine that a refund is possible, but the actual financial operation may require human approval.

Customer
   |
   v
AI Agent
   |
   v
Check Refund Policy
   |
   v
Refund Amount = ₹50,000
   |
   v
Approval Required
   |
   v
Human Approval
   |
   v
Refund API

This is an important pattern for enterprise agentic systems.

AI does not have to mean unrestricted autonomy.

12. RAG vs Agents

RAG stands for Retrieval-Augmented Generation.

RAG typically follows this pattern:

User Question
      |
      v
Retrieve Relevant Information
      |
      v
LLM
      |
      v
Answer

An agent can use RAG as one of its capabilities.

                 AI Agent
                     |
       +-------------+-------------+
       |             |             |
       v             v             v
      RAG           API          Database

The key difference is:

RAG primarily helps an AI system find relevant information, while an agent can use information and tools to accomplish a goal.

RAG and Agentic AI are therefore not competing concepts.

RAG can be a component inside an agentic system.

Example

Suppose an employee asks:

"What is our leave policy and how many days do I have remaining?"

The agent may need two different capabilities.

First:

RAG
 |
 v
Retrieve Leave Policy

Second:

Employee API
 |
 v
Retrieve Remaining Leave

Then the agent combines both results.

                    Agent
                      |
             +--------+--------+
             |                 |
             v                 v
            RAG           Employee API
             |                 |
             v                 v
        Leave Policy       Leave Balance
             |                 |
             +--------+--------+
                      |
                      v
                   Answer

This is a good example of why RAG and agents often work together.

13. Workflow vs Agent

This is one of the most important architectural decisions.

A traditional workflow might look like:

Step 1
  |
  v
Step 2
  |
  v
Step 3
  |
  v
Step 4

The developer explicitly defines the sequence.

An agentic system may look like:

Goal
 |
 v
Agent
 |
 +----> Decide Action
 |
 +----> Execute
 |
 +----> Observe
 |
 +----> Decide Next Action
 |
 +----> Execute
 |
 v
Complete

When should you use a workflow?

Use a workflow when:

Steps are predictable.
Business rules are well defined.
Deterministic execution is important.
Compliance requires predictable behavior.
The process is easy to express as a state machine.

For example:

Receive Order
      |
      v
Validate Payment
      |
      v
Reserve Inventory
      |
      v
Create Shipment
      |
      v
Send Notification

There is little value in asking an LLM to decide this sequence if the business process is already known.

When can an agent help?

Agents can be useful when:

The number of steps varies.
The required tool depends on the situation.
The task requires interpretation.
The environment is dynamic.
The system needs to choose between multiple possible actions.

Hybrid architecture

In many enterprise systems, the best architecture may actually be a hybrid.

                    Application
                         |
             +-----------+-----------+
             |                       |
             v                       v
        Deterministic            AI Agent
         Workflow                   |
             |                      Tools
             |                       |
             +-----------+-----------+
                         |
                         v
                   Business Systems

For example:

AI Agent
   |
   v
Determine Customer Intent
   |
   v
Deterministic Workflow
   |
   +---- Validate
   +---- Approve
   +---- Execute
   +---- Audit

The AI can handle ambiguity while deterministic code handles critical business operations.

This combination is often easier to control than giving an agent unrestricted authority.

14. Single-Agent vs Multi-Agent

A single-agent system has one primary agent responsible for the task.

User
 |
 v
Agent
 |
 +---> Tools

A multi-agent system uses multiple specialized agents.

For example:

                 Orchestrator
                      |
        +-------------+-------------+
        |             |             |
        v             v             v
   Sales Agent    Finance Agent   Support Agent

Each agent may have different:

Instructions
Tools
Permissions
Knowledge
Responsibilities

Example

Suppose an enterprise wants to build an employee assistant.

                    Employee
                        |
                        v
                  Orchestrator
                        |
        +---------------+---------------+
        |               |               |
        v               v               v
   HR Agent        IT Agent        Finance Agent
        |               |               |
        v               v               v
   HR Systems       IT Systems     Finance Systems

The orchestrator can route a request to the appropriate specialist.

Do you always need multiple agents?

No.

A common mistake is to introduce multiple agents simply because the technology allows it.

If one agent with a few well-designed tools can solve the problem, adding five agents may only introduce:

More complexity
More latency
More cost
More failure points
More difficult debugging
More complicated state management

A good architecture starts with the simplest design that satisfies the requirements.

15. Simple Agent Architecture

Let's put the concepts together.

A simple agent architecture can look like this:

                         User
                           |
                           v
                  +----------------+
                  | API / UI Layer |
                  +-------+--------+
                          |
                          v
                  +----------------+
                  |  Agent Runtime |
                  +-------+--------+
                          |
              +-----------+-----------+
              |           |           |
              v           v           v
             LLM        Memory       RAG
              |           |           |
              +-----------+-----------+
                          |
                          v
                       Tools
                          |
          +---------------+---------------+
          |               |               |
          v               v               v
        APIs          Databases        Search

For an enterprise Azure implementation, the architecture could evolve into:

                         User
                           |
                           v
                  Azure Front Door
                           |
                           v
                   API Management
                           |
                           v
                  ASP.NET Core API
                           |
                           v
                    Agent Runtime
                           |
              +------------+------------+
              |            |            |
              v            v            v
        Azure OpenAI   Azure AI      Memory
                        Search        Store
              |            |            |
              +------------+------------+
                           |
                           v
                    Tool Gateway
                           |
        +------------------+------------------+
        |                  |                  |
        v                  v                  v
     REST APIs         Azure SQL          Service Bus

Supporting services can include:

Microsoft Entra ID
Azure Key Vault
Application Insights
Azure Monitor
OpenTelemetry
Azure Service Bus
Azure Storage
Cosmos DB
Redis

The exact services should depend on the requirements.

Do not introduce every Azure service simply because it is available.

16. Common Misconceptions

Agentic AI is surrounded by a lot of hype.

Let's address some common misconceptions.

Misconception 1: An AI agent is just a chatbot

Not necessarily.

A chatbot can primarily focus on conversation.

An agent can combine:

Reasoning
Tools
State
Memory
Planning
Actions

Misconception 2: Every AI application needs an agent

No.

Many applications are better implemented using:

Traditional APIs
Deterministic workflows
RAG
Background jobs
Event-driven architecture
Conventional business logic

Use an agent when dynamic decision-making provides real value.

Misconception 3: Agents are completely autonomous

They don't have to be.

An enterprise agent can operate with strict boundaries.

For example:

Agent
 |
 +---- Read Customer
 |
 +---- Read Order
 |
 +---- Create Ticket
 |
 X---- Delete Customer
 |
 X---- Issue Refund > ₹10,000

The system can require human approval for sensitive actions.

Misconception 4: The LLM controls the entire system

A well-designed architecture should not work that way.

The application should control:

Authentication
Authorization
Tool access
Data access
Validation
Business rules
Audit
Rate limits
Approval

The LLM should operate within those boundaries.

Misconception 5: More agents means a better system

Not necessarily.

Multiple agents can increase:

Cost
Latency
Complexity
Debugging difficulty
Failure modes

Start simple.

Introduce multiple agents only when specialization or isolation provides a real architectural benefit.

Misconception 6: Agents always reason perfectly

They don't.

AI models can produce incorrect decisions or interpretations.

Therefore:

AI Decision
     |
     v
Validation
     |
     v
Authorization
     |
     v
Execution

is safer than:

AI Decision
     |
     v
Execute Anything

17. When Should You Use an Agent?

An agent can be a good fit when the problem has several of the following characteristics:

1. The task is goal-oriented

For example:

"Investigate why this customer's order is delayed."

rather than:

"Call API A and then API B."

2. The next step depends on the current result

For example:

Check Order
    |
    +---- Delivered ---> Close Request
    |
    +---- Delayed -----> Check Shipping
    |
    +---- Cancelled ---> Start Refund

The path depends on what the system discovers.

3. Multiple tools may be required

For example:

Customer API
Order API
Shipping API
Payment API
Knowledge Base

4. Natural language is an important interface

Agents are particularly useful when users express goals rather than structured commands.

For example:

"Help me resolve this customer complaint."

5. The environment changes

The agent may need to adapt based on:

Tool results
User responses
Current data
External events

18. When Should You NOT Use an Agent?

This is just as important as knowing when to use one.

Do not use an agent simply because it is fashionable.

If a simple API or workflow solves the problem, that may be the better engineering choice.

Avoid an agent when the process is completely deterministic

For example:

Receive Request
    |
    v
Validate
    |
    v
Save
    |
    v
Publish Event

There may be no reason to introduce an LLM.

Avoid agents for extremely latency-sensitive operations

If the requirement is:

Response < 10 ms

adding an LLM-based reasoning loop may not be appropriate.

Avoid agents when deterministic behavior is mandatory

Some financial, safety-critical, or compliance-sensitive operations may require tightly controlled execution.

A better pattern can be:

AI
 |
 v
Recommendation
 |
 v
Deterministic Business Logic
 |
 v
Execution

Avoid giving agents unnecessary permissions

The principle should be:

Give an agent the minimum permissions required to accomplish its task.

This is similar to the principle of least privilege used in traditional security architecture.

19. Beginner Roadmap

If you're new to Agentic AI, don't start by learning ten frameworks.

Start with the fundamentals.

Stage 1: Learn Generative AI

Understand:

LLMs
Prompts
Tokens
Context windows
Embeddings
Model inference

LLM Fundamentals
        |
        v
Prompting
        |
        v
Context

Stage 2: Learn Tool Calling

Understand:

Function calling
Tool schemas
Structured outputs
Tool results

LLM
 |
 v
Tool Selection
 |
 v
Tool Execution
 |
 v
Result
 |
 v
LLM

Stage 3: Learn RAG

Understand:

Embeddings
Vector search
Retrieval
Chunking
Metadata
Grounding

Documents
   |
   v
Chunking
   |
   v
Embeddings
   |
   v
Vector Store
   |
   v
Retrieval
   |
   v
LLM

Stage 4: Learn Agent Concepts

Focus on:

Agent loop
State
Memory
Planning
Tool selection
Guardrails
Human-in-the-loop

Stage 5: Build a Simple Agent

Start with something small.

For example:

User
 |
 v
Agent
 |
 +---- Calculator
 |
 +---- Weather API
 |
 +---- Search

Stage 6: Learn Agent Frameworks

After understanding the concepts, explore frameworks and SDKs such as:

Semantic Kernel
LangChain
LangGraph
Microsoft Agent Framework
Provider-specific agent SDKs

The framework should come after understanding the underlying concepts.

Otherwise, it is easy to learn framework APIs without understanding what the architecture is actually doing.

Stage 7: Learn Production Architecture

Then focus on:

Security
Identity
Authorization
Observability
Cost management
Reliability
Evaluation
Prompt injection
Data protection
Human approval
Auditability

A production agent is an enterprise software system, not just a prompt.

20. Conclusion

Agentic AI represents a shift from AI systems that primarily generate responses toward systems that can work toward goals using tools and controlled actions.

The simplest mental model is:

              Goal
                |
                v
             Reason
                |
                v
               Act
                |
                v
             Observe
                |
                v
             Reason
                |
                v
            Complete?
             /     \
           No       Yes
           |         |
           +---------+
                |
                v
             Result

The core concepts to remember are:

LLM
 |
 +---- Reasoning
 |
 +---- Tools
 |
 +---- Memory
 |
 +---- State
 |
 +---- Planning
 |
 +---- Guardrails
 |
 +---- Human Approval

But there is an even more important lesson.

Agentic AI is not about giving AI unlimited autonomy. It is about giving AI controlled capabilities to accomplish useful goals.

As an engineer, the question should not simply be:

"How can I build an AI agent?"

A better question is:

"Does this problem actually benefit from agentic behavior, and if so, what level of autonomy is appropriate?"

That shift in thinking is what separates an interesting AI demo from a production-ready enterprise system.

What's Next?

Now that we understand the fundamentals, the next step is to understand the most important building blocks in more detail:

The Agent Loop
Tool Calling
Memory and State
RAG and Agents
Single-Agent vs Multi-Agent Architecture
Building an Agent with .NET
Building an Agent on Azure
Securing AI Agents
Prompt Injection and Agent Security
Designing Production-Ready Agentic AI Systems

Agentic AI is still evolving rapidly.

The frameworks will change.

The model providers will change.

The terminology will change.

But the fundamental engineering principles will remain:

Clear goals. Controlled tools. Explicit permissions. Observable behavior. Deterministic boundaries. Human oversight where necessary.

That is the foundation for building useful and responsible AI agents.

Entity Framework Core Performance Optimization: A Practical Guide for .NET Developers

Chethan Ramaswamy — Sat, 26 Sep 2026 13:55:27 +0000

Entity Framework Core Performance Optimization: A Practical Guide for .NET Developers

Entity Framework Core (EF Core) simplifies database development by allowing .NET developers to work with strongly typed C# objects and LINQ instead of writing SQL for every database operation.

However, the convenience of an ORM can sometimes hide expensive operations.

A LINQ query that looks simple in C# can result in:

Unnecessary database round trips
Large result sets
Excessive change tracking
N+1 queries
Expensive joins
Unnecessary columns being retrieved
Poor pagination performance
Excessive memory usage

The goal of performance optimization is not to avoid EF Core. It is to understand how EF Core translates and executes queries and then design those queries appropriately.

Good EF Core performance comes from minimizing unnecessary database work, data transfer, object materialization, and application-side processing.

This article walks through the most important EF Core performance considerations, from query execution and related-data loading to CRUD operations, DbContext, diagnostics, and practical optimization patterns.

Contents Snapshot

1. Understanding Entity Framework Core Performance
- How EF Core executes queries
- LINQ-to-SQL translation
- Where EF Core performance bottlenecks occur
2. Common EF Core Performance Problems
- Loading unnecessary data
- Excessive entity tracking
- N+1 queries
- Lazy loading
- Excessive Include()
- Premature query execution
3. Optimizing EF Core Queries
- Projection with Select()
- DTO-based queries
- AsNoTracking()
- Filtering and sorting
- Avoiding client-side processing
- Inspecting generated SQL
4. Managing Related Data
- Include() and ThenInclude()
- Eager loading
- Explicit loading
- Lazy loading
- AsSplitQuery() vs single queries
5. Pagination and Large Data Sets
- Skip() and Take()
- Keyset pagination
- Efficient querying of large tables
6. Insert, Update, and Delete Performance
- SaveChangesAsync()
- Batch operations
- ExecuteUpdateAsync()
- ExecuteDeleteAsync()
- Handling large data operations
7. DbContext Performance
- DbContext lifetime
- Change tracking
- Connection management
- Async database operations
- Context pooling
8. EF Core Performance Patterns and Anti-Patterns
- Common mistakes
- Recommended patterns
- When to use or avoid specific EF Core features
9. Measuring and Diagnosing EF Core Performance
- Logging
- Generated SQL
- Query timing
- Profiling
- Identifying slow queries
10. Practical EF Core Performance Checklist
- Query checklist
- Tracking checklist
- Loading checklist
- Write-operation checklist
- Production checklist
11. Key Takeaways

1. Understanding Entity Framework Core Performance

Before optimizing EF Core, it is important to understand what happens when a query is executed.

Consider this simple query:

var customers = await dbContext.Customers
    .Where(x => x.IsActive)
    .ToListAsync();

At a high level, the execution flow looks like this:

C# LINQ Query
      |
      v
EF Core
      |
      v
Expression Translation
      |
      v
Generated SQL
      |
      v
Database
      |
      v
Result Set
      |
      v
EF Core Materialization
      |
      v
C# Objects

Several stages can contribute to the overall execution time.

How EF Core Executes Queries

When an IQueryable is built, EF Core does not immediately execute the query.

For example:

var query = dbContext.Customers
    .Where(x => x.IsActive)
    .OrderBy(x => x.Name);

At this point, the query has been composed but not necessarily executed.

Execution occurs when a terminal operation is called:

var customers = await query.ToListAsync();

Other examples include:

await query.FirstAsync();
await query.SingleAsync();
await query.CountAsync();
await query.AnyAsync();

This distinction is important because adding filters and projections before query execution allows EF Core to translate more of the work into SQL.

LINQ-to-SQL Translation

Consider:

var customers = await dbContext.Customers
    .Where(x => x.IsActive)
    .Select(x => new
    {
        x.Id,
        x.Name
    })
    .ToListAsync();

Conceptually, EF Core translates the LINQ expression into SQL similar to:

SELECT
    Id,
    Name
FROM Customers
WHERE IsActive = 1;

The exact SQL depends on the EF Core version, provider, model configuration, and query.

This means developers should understand both sides:

LINQ
  |
  v
EF Core Translation
  |
  v
SQL
  |
  v
Database Execution

A query that looks efficient in C# is not necessarily efficient after translation.

Where EF Core Performance Bottlenecks Occur

Potential bottlenecks include:

Query translation
Database execution
Network transfer
Entity materialization
Change tracking
Application-side processing
Excessive database round trips
Large result sets

Therefore:

Do not optimize EF Core based only on how the C# code looks. Measure what the application and database actually do.

2. Common EF Core Performance Problems

Loading Unnecessary Data

One of the most common problems is retrieving more data than the application needs.

Consider:

var customers = await dbContext.Customers
    .Where(x => x.IsActive)
    .ToListAsync();

Suppose the Customer entity contains:

Id
Name
Email
Phone
Address
ProfileImage
Preferences
Audit fields

If the API only needs:

Id
Name
Email

loading the entire entity is unnecessary.

This can increase:

Database I/O
Network traffic
Memory usage
Entity materialization
Serialization cost

Projection is usually a better approach for read-only API scenarios.

var customers = await dbContext.Customers
    .Where(x => x.IsActive)
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name,
        Email = x.Email
    })
    .ToListAsync();

Only the required fields are requested by the query.

Excessive Entity Tracking

EF Core uses change tracking to detect modifications to entities.

This is useful when updating data:

var customer = await dbContext.Customers
    .FirstAsync(x => x.Id == customerId);

customer.Name = "John";

await dbContext.SaveChangesAsync();

EF Core tracks the customer and can determine what changed.

For read-only scenarios, tracking may not be necessary.

var customers = await dbContext.Customers
    .AsNoTracking()
    .Where(x => x.IsActive)
    .ToListAsync();

AsNoTracking() tells EF Core not to track the returned entities for changes.

This can reduce tracking overhead for appropriate read-heavy workloads.

However, it should not be added blindly everywhere.

Ask:

Does this query need to modify the returned entities?

If the answer is no, no-tracking may be appropriate.

The N+1 Query Problem

The N+1 query problem occurs when an application executes one query to retrieve a collection and then performs additional queries for each item.

Consider:

var orders = await dbContext.Orders
    .ToListAsync();

foreach (var order in orders)
{
    Console.WriteLine(order.Customer.Name);
}

Depending on the relationship-loading configuration, this can result in:

1 query  -> Orders

N queries -> Customers

If there are 5,000 orders, the application could potentially perform thousands of additional database operations.

Even when individual queries are fast, the combined overhead can become significant.

Better Approach

Projection can retrieve the required related data as part of the query:

var orders = await dbContext.Orders
    .Select(x => new OrderDto
    {
        Id = x.Id,
        Amount = x.Amount,
        CustomerName = x.Customer.Name
    })
    .ToListAsync();

The important principle is:

Minimize unnecessary database round trips.

Lazy Loading

Lazy loading retrieves related data when a navigation property is accessed.

For example:

var order = await dbContext.Orders
    .FirstAsync(x => x.Id == orderId);

var customerName = order.Customer.Name;

With lazy loading enabled, accessing Customer can trigger another database query.

This can be convenient, but it can also hide database operations inside ordinary property access.

For example:

foreach (var order in orders)
{
    Console.WriteLine(order.Customer.Name);
}

What looks like a simple loop may result in many database calls.

Practical Consideration

Lazy loading can be useful in some scenarios, but it should be used carefully in performance-sensitive applications.

For API workloads, explicit query shaping and projection often make database access easier to understand and control.

Excessive `Include()`

Include() is useful when related entities are genuinely required.

For example:

var orders = await dbContext.Orders
    .Include(x => x.Customer)
    .ToListAsync();

However, adding many relationships to a query can result in complex SQL and large result sets.

For example:

var orders = await dbContext.Orders
    .Include(x => x.Customer)
    .Include(x => x.Items)
    .Include(x => x.Payments)
    .Include(x => x.Shipments)
    .ToListAsync();

This may result in a large query and repeated data across joined rows.

If the API only needs selected fields, projection is often clearer:

var orders = await dbContext.Orders
    .Select(x => new OrderSummaryDto
    {
        Id = x.Id,
        Amount = x.Amount,
        CustomerName = x.Customer.Name,
        ItemCount = x.Items.Count()
    })
    .ToListAsync();

Use Include() when you actually need entity graphs.

Use projection when you need a specific result shape.

Premature Query Execution

Consider:

var customers = await dbContext.Customers
    .ToListAsync();

var activeCustomers = customers
    .Where(x => x.IsActive)
    .ToList();

The entire customer table is loaded into memory before filtering.

A better approach is:

var activeCustomers = await dbContext.Customers
    .Where(x => x.IsActive)
    .ToListAsync();

Now the filtering happens in the database.

A useful rule is:

Keep the query as IQueryable while composing database operations, and execute it only when you actually need the results.

3. Optimizing EF Core Queries

Projection with `Select()`

Projection is one of the most useful EF Core optimization techniques.

Instead of retrieving complete entities:

var products = await dbContext.Products
    .Where(x => x.IsActive)
    .ToListAsync();

project only the required fields:

var products = await dbContext.Products
    .Where(x => x.IsActive)
    .Select(x => new ProductDto
    {
        Id = x.Id,
        Name = x.Name,
        Price = x.Price
    })
    .ToListAsync();

This reduces the amount of data transferred from the database.

It can also reduce application memory consumption and object materialization.

Why Projection Matters

Consider an entity with 30 columns.

If an API requires only 4 columns:

Entity
  |
  +-- 30 columns
  |
  v
Database
  |
  v
Application

Projection changes this to:

Entity
  |
  +-- 4 required columns
  |
  v
Database
  |
  v
Application

This becomes increasingly important as data volume grows.

DTO-Based Queries

Using DTOs also creates a clear boundary between persistence models and API contracts.

Example:

public sealed class CustomerDto
{
    public int Id { get; init; }
    public string Name { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
}

Query:

var customers = await dbContext.Customers
    .AsNoTracking()
    .Where(x => x.IsActive)
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name,
        Email = x.Email
    })
    .ToListAsync();

This approach has several advantages:

Explicit data requirements
Smaller result sets
Reduced coupling
Clear API contracts
Less unnecessary entity materialization

`AsNoTracking()`

For read-only queries:

var products = await dbContext.Products
    .AsNoTracking()
    .Where(x => x.IsActive)
    .ToListAsync();

Use tracking when you need to modify the entity:

var product = await dbContext.Products
    .FirstAsync(x => x.Id == productId);

product.Price = 100;

await dbContext.SaveChangesAsync();

Use no-tracking when the result is simply being read:

GET API
  |
  v
Query database
  |
  v
Return response

The choice should be based on the query's behavior, not applied as a blanket rule.

Filtering and Sorting

Filtering should generally happen in the database rather than after materialization.

Avoid:

var customers = await dbContext.Customers
    .ToListAsync();

var result = customers
    .Where(x => x.Country == "India")
    .OrderBy(x => x.Name)
    .ToList();

Prefer:

var result = await dbContext.Customers
    .Where(x => x.Country == "India")
    .OrderBy(x => x.Name)
    .ToListAsync();

This allows the database to perform the filtering and sorting.

For large datasets, database-side operations are generally preferable to loading unnecessary rows into application memory.

Avoiding Client-Side Processing

A common performance problem occurs when developers unintentionally move processing from the database into application memory.

For example:

var customers = await dbContext.Customers
    .ToListAsync();

var result = customers
    .Where(x => x.Name.StartsWith("A"))
    .ToList();

Instead:

var result = await dbContext.Customers
    .Where(x => x.Name.StartsWith("A"))
    .ToListAsync();

The database can process the filtering before returning the result.

The general pattern is:

Avoid:

Database
   |
   v
Large result set
   |
   v
Application filtering


Prefer:

Database
   |
   +-- Filter
   +-- Sort
   +-- Project
   |
   v
Small result set
   |
   v
Application

Inspecting Generated SQL

Do not assume that a LINQ query generates the SQL you expect.

EF Core provides ToQueryString() for inspecting the SQL representation of a query.

var query = dbContext.Customers
    .Where(x => x.IsActive)
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name
    });

var sql = query.ToQueryString();

Console.WriteLine(sql);

This is useful when diagnosing:

Unexpected joins
Missing filters
Excessive columns
Complex queries
Unexpected query shapes

For production diagnosis, application logging and database monitoring should also be used rather than relying only on ToQueryString().

4. Managing Related Data

Relationships are one of the areas where EF Core can generate unexpected database work.

Consider:

Order
 |
 +-- Customer
 |
 +-- OrderItems
 |
 +-- Payments

The correct loading strategy depends on what the application actually needs.

`Include()` and `ThenInclude()`

Include() loads related data.

var orders = await dbContext.Orders
    .Include(x => x.Customer)
    .ToListAsync();

For nested relationships:

var orders = await dbContext.Orders
    .Include(x => x.Customer)
        .ThenInclude(x => x.Address)
    .ToListAsync();

Use this when the related entities are actually required.

Avoid adding Include() simply because the relationship exists.

Eager Loading

Eager loading retrieves related data as part of the query.

Example:

var orders = await dbContext.Orders
    .Include(x => x.Customer)
    .ToListAsync();

Advantages:

Explicit
Easy to understand
Avoids some hidden database calls

Potential downside:

Large entity graphs can produce complex queries and large result sets

For read-only APIs, projection can often provide a more precise result shape.

Explicit Loading

Explicit loading allows the application to deliberately load related data.

For example:

var order = await dbContext.Orders
    .FirstAsync(x => x.Id == orderId);

await dbContext.Entry(order)
    .Reference(x => x.Customer)
    .LoadAsync();

This gives the application explicit control over when related data is loaded.

It can be useful when the related data is conditionally required.

However, repeated explicit loading inside loops can still create N+1 behavior.

Lazy Loading

Lazy loading loads related entities when they are accessed.

Although convenient, it can make database activity less visible in application code.

For example:

foreach (var order in orders)
{
    Console.WriteLine(order.Customer.Name);
}

The loop does not visibly contain a database query, but accessing Customer can trigger one when lazy loading is enabled.

For performance-sensitive applications, make database access explicit whenever practical.

`AsSplitQuery()` vs Single Queries

Consider a query with multiple collection relationships:

var orders = await dbContext.Orders
    .Include(x => x.Items)
    .Include(x => x.Payments)
    .ToListAsync();

A single-query approach can produce large joins.

EF Core supports split queries:

var orders = await dbContext.Orders
    .Include(x => x.Items)
    .Include(x => x.Payments)
    .AsSplitQuery()
    .ToListAsync();

Conceptually:

Single Query

Orders
  |
  +-- Items
  |
  +-- Payments

versus:

Split Query

Query 1 -> Orders
Query 2 -> Items
Query 3 -> Payments

Split queries can reduce some join-related duplication, but they also mean multiple database round trips.

Therefore:

Choose between single and split queries based on the actual query shape and measured performance.

5. Pagination and Large Data Sets

Returning thousands or millions of rows from an API is rarely appropriate.

Pagination limits the amount of data processed and returned.

`Skip()` and `Take()`

A common approach is:

var customers = await dbContext.Customers
    .OrderBy(x => x.Id)
    .Skip(page * pageSize)
    .Take(pageSize)
    .ToListAsync();

For example:

Page size = 50
Page      = 2

The query retrieves the next 50 records after the previous 100 records.

This approach is simple and useful for many applications.

However, very large offsets can become increasingly expensive because the database may need to process rows that are skipped.

Keyset Pagination

For large datasets, keyset pagination can be an alternative.

Suppose the last item from the previous page has:

Id = 50000

The next query can be:

var customers = await dbContext.Customers
    .Where(x => x.Id > lastCustomerId)
    .OrderBy(x => x.Id)
    .Take(50)
    .ToListAsync();

Conceptually:

Previous page
     |
     v
Last Id = 50000
     |
     v
WHERE Id > 50000
     |
     v
Take 50

This approach is especially useful for large, sequential datasets.

When to Consider Keyset Pagination

Keyset pagination is useful when:

The dataset is large
Users navigate sequentially
A stable ordering key exists
Very deep pages are expected

Offset pagination can still be appropriate when users need direct access to arbitrary pages.

6. Insert, Update, and Delete Performance

EF Core performance is not limited to queries.

Write operations can also become expensive when large numbers of entities are involved.

`SaveChangesAsync()`

Avoid calling SaveChangesAsync() inside every iteration.

Inefficient

foreach (var customer in customers)
{
    customer.IsActive = false;

    await dbContext.SaveChangesAsync();
}

This can create many database round trips.

Better

foreach (var customer in customers)
{
    customer.IsActive = false;
}

await dbContext.SaveChangesAsync();

This reduces the number of explicit save operations.

However, for very large datasets, loading and tracking every entity can still be expensive.

That is where set-based operations become useful.

Batch Operations

When processing large numbers of entities, consider the size of the batch.

For example:

1,000,000 records
      |
      v
Process in manageable batches
      |
      +-- Batch 1
      +-- Batch 2
      +-- Batch 3
      +-- ...

Batching can help control:

Memory consumption
Transaction size
Change tracker size
Execution time
Database pressure

The appropriate batch size depends on the workload and should be validated through testing.

`ExecuteUpdateAsync()`

For operations that can be expressed as a set-based update, ExecuteUpdateAsync() can avoid loading entities into memory.

For example:

await dbContext.Customers
    .Where(x => !x.IsActive)
    .ExecuteUpdateAsync(setters =>
        setters.SetProperty(
            x => x.IsArchived,
            true));

Conceptually, the operation becomes:

Application
     |
     v
UPDATE statement
     |
     v
Database

rather than:

Database
     |
     v
Load entities
     |
     v
Application
     |
     v
Track entities
     |
     v
Modify entities
     |
     v
Save changes

For large set-based updates, this can substantially reduce application-side work.

`ExecuteDeleteAsync()`

Similarly, records can be deleted directly without loading every entity.

await dbContext.Customers
    .Where(x => x.IsInactive)
    .ExecuteDeleteAsync();

This is useful when the business operation is simply:

Delete all records matching condition

rather than:

Load each entity
  |
  v
Run application logic
  |
  v
Delete entities

Before using set-based operations, consider whether entity-level business rules, events, auditing, or other application logic need to run.

Handling Large Data Operations

For very large workloads, consider:

Batching
Set-based operations
Appropriate transaction boundaries
Memory consumption
Database throughput
Error recovery
Idempotency
Retry behavior

The right strategy depends on whether the operation is:

User-driven
Scheduled
Background processing
Bulk migration
Data correction
Real-time processing

7. DbContext Performance

DbContext is central to EF Core applications.

Understanding its lifecycle and behavior is important for performance and correctness.

DbContext Lifetime

In ASP.NET Core applications, a common configuration is:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString));

This typically creates a scoped DbContext.

The conceptual request lifecycle is:

HTTP Request
     |
     v
DbContext
     |
     +-- Query
     +-- Query
     +-- Update
     |
     v
SaveChanges
     |
     v
Request Complete
     |
     v
DbContext Disposed

Avoid using a single DbContext instance across unrelated concurrent requests.

DbContext is not designed for concurrent operations on the same instance.

Change Tracking

The change tracker maintains information about entities being tracked.

For example:

var customer = await dbContext.Customers
    .FirstAsync(x => x.Id == customerId);

customer.Name = "Updated Name";

await dbContext.SaveChangesAsync();

EF Core can determine that Name changed.

However, tracking thousands of entities can increase memory and processing overhead.

For read-heavy workloads, no-tracking queries can reduce this overhead:

var customers = await dbContext.Customers
    .AsNoTracking()
    .ToListAsync();

The right approach depends on the workload.

Connection Management

EF Core relies on the underlying database provider for connection management and pooling.

A simplified flow is:

Application
     |
     v
EF Core
     |
     v
Connection Pool
     |
     v
Database

Potential problems include:

Connection pool exhaustion
Long-running database operations
Excessive concurrency
Connections held longer than necessary

If an application experiences database timeouts, investigate whether the problem is:

Connection acquisition
        |
        or
        v
Query execution
        |
        or
        v
Database resource contention

Do not assume all database timeout problems have the same root cause.

Async Database Operations

Use asynchronous database APIs in ASP.NET Core applications:

var customers = await dbContext.Customers
    .ToListAsync();

Similarly:

await dbContext.SaveChangesAsync();

Asynchronous I/O allows the application to avoid blocking request threads while waiting for database operations.

The benefit is particularly relevant for applications handling many concurrent requests.

Context Pooling

For some workloads, EF Core supports context pooling.

For example:

builder.Services.AddDbContextPool<AppDbContext>(options =>
    options.UseSqlServer(connectionString));

Pooling allows EF Core to reuse DbContext instances rather than creating a new instance each time.

However, pooled contexts require careful consideration of state that might be stored on the context or related services.

Context pooling is an optimization that should be measured rather than enabled simply because it exists.

8. EF Core Performance Patterns and Anti-Patterns

Understanding what not to do is just as important as understanding the recommended patterns.

Common Mistakes

Loading Everything

var customers = await dbContext.Customers
    .ToListAsync();

followed by application-side filtering.

Prefer database-side filtering:

var customers = await dbContext.Customers
    .Where(x => x.IsActive)
    .ToListAsync();

Returning Entities Directly From APIs

Returning EF entities directly can expose persistence models to API consumers.

Prefer DTOs:

var customers = await dbContext.Customers
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name
    })
    .ToListAsync();

Calling `SaveChangesAsync()` Repeatedly

Avoid:

foreach (var item in items)
{
    dbContext.Update(item);
    await dbContext.SaveChangesAsync();
}

Prefer a suitable batching or set-based strategy.

Using Lazy Loading Without Understanding Its Cost

Lazy loading can make database calls invisible in application code.

Be particularly careful with loops and large collections.

Adding `Include()` Everywhere

Include() is not a replacement for query design.

Ask:

Do I really need the complete related entity?

If the answer is no, projection may be more appropriate.

Recommended Patterns

For read-heavy API endpoints:

var result = await dbContext.Customers
    .AsNoTracking()
    .Where(x => x.IsActive)
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name,
        Email = x.Email
    })
    .ToListAsync();

This combines several useful principles:

Database-side filtering
Projection
Reduced tracking
Explicit result shape

For large updates:

await dbContext.Customers
    .Where(x => !x.IsActive)
    .ExecuteUpdateAsync(setters =>
        setters.SetProperty(
            x => x.IsArchived,
            true));

For large result sets:

var result = await dbContext.Customers
    .Where(x => x.Id > lastCustomerId)
    .OrderBy(x => x.Id)
    .Take(50)
    .ToListAsync();

When to Use or Avoid Specific EF Core Features

Feature	Useful When	Be Careful When
`AsNoTracking()`	Read-only queries	Entities need to be updated through the context
`Include()`	Related entities are required	Many large collection relationships are included
`AsSplitQuery()`	Large relationship graphs	Additional database round trips matter
Lazy loading	Convenience is important	Query count must be predictable
Projection	APIs need specific fields	Complex result shapes require careful testing
`ExecuteUpdateAsync()`	Large set-based updates	Entity-level business logic must execute
`ExecuteDeleteAsync()`	Large set-based deletes	Per-entity processing is required
Context pooling	High-throughput workloads	Context-specific mutable state is used

The important point is that there is no single EF Core feature that makes every application faster.

9. Measuring and Diagnosing EF Core Performance

Performance optimization should start with measurement.

Do not optimize based solely on assumptions.

Logging

EF Core can provide database-related logging that helps identify queries and execution behavior.

For example:

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options
        .UseSqlServer(connectionString)
        .EnableDetailedErrors();
});

Be careful when enabling detailed logging in production because sensitive information can potentially appear in logs depending on the configuration.

Generated SQL

For a specific query:

var query = dbContext.Customers
    .Where(x => x.IsActive)
    .Select(x => new CustomerDto
    {
        Id = x.Id,
        Name = x.Name
    });

var sql = query.ToQueryString();

Inspecting generated SQL can reveal unexpected behavior.

For example:

Expected:

SELECT Id, Name
FROM Customers
WHERE IsActive = 1


Unexpected:

SELECT many columns
FROM Customers
JOIN ...
JOIN ...
JOIN ...

This can lead to further investigation.

Query Timing

Measure actual execution time rather than assuming a query is slow.

For example:

var stopwatch = Stopwatch.StartNew();

var customers = await dbContext.Customers
    .AsNoTracking()
    .Where(x => x.IsActive)
    .ToListAsync();

stopwatch.Stop();

Console.WriteLine(
    $"Query completed in {stopwatch.ElapsedMilliseconds} ms");

For production applications, use structured logging and telemetry instead of ad-hoc console output.

Profiling

For a production-grade application, consider observing:

HTTP Request
      |
      v
Application Code
      |
      v
EF Core
      |
      v
Database Dependency

Useful measurements include:

API latency
Database query duration
Number of database calls
Result-set size
Error rate
Request throughput
Memory usage
Connection utilization

The objective is to identify where the time is actually being spent.

Identifying Slow Queries

A useful troubleshooting process is:

Slow API
   |
   v
Measure API latency
   |
   v
Identify database dependency
   |
   v
Identify slow query
   |
   v
Inspect generated SQL
   |
   v
Analyze execution
   |
   v
Optimize EF Core query
   |
   v
Measure again

If the database query itself is efficient but the API is still slow, investigate other parts of the request pipeline.

10. Practical EF Core Performance Checklist

Query Checklist

[ ] Are only required columns being selected?
[ ] Is filtering performed in the database?
[ ] Is projection used where appropriate?
[ ] Are queries executed only when needed?
[ ] Are N+1 queries eliminated?
[ ] Is generated SQL understood?
[ ] Are large result sets paginated?

Tracking Checklist

[ ] Does the query actually require change tracking?
[ ] Is AsNoTracking() used for appropriate read-only queries?
[ ] Is the number of tracked entities reasonable?
[ ] Are long-lived DbContext instances avoided?

Loading Checklist

[ ] Is Include() used only when required?
[ ] Are large relationship graphs avoided?
[ ] Is lazy loading being used intentionally?
[ ] Could projection replace entity loading?
[ ] Should AsSplitQuery() be considered for the query shape?

Write-Operation Checklist

[ ] Is SaveChangesAsync() being called unnecessarily inside loops?
[ ] Can the operation be performed in batches?
[ ] Can ExecuteUpdateAsync() be used?
[ ] Can ExecuteDeleteAsync() be used?
[ ] Are transaction boundaries appropriate?
[ ] Is application-level business logic required for each entity?

Production Checklist

[ ] Is query performance measured?
[ ] Are database calls observable?
[ ] Are slow queries identifiable?
[ ] Are application logs configured appropriately?
[ ] Are connection issues monitored?
[ ] Are realistic datasets used for performance testing?
[ ] Are performance changes validated before and after deployment?

11. Key Takeaways

Entity Framework Core provides powerful abstractions for working with relational databases, but those abstractions do not remove the need to understand database access patterns.

The most important principles are:

Understand how LINQ becomes SQL.
Retrieve only the data the application actually needs.
Use projection for precise read models.
Use AsNoTracking() for appropriate read-only workloads.
Avoid N+1 queries.
Use Include() carefully.
Understand the trade-offs of lazy loading.
Keep filtering and sorting in the database where appropriate.
Avoid premature query execution.
Use appropriate pagination for large datasets.
Avoid unnecessary SaveChangesAsync() calls.
Consider set-based operations for large updates and deletes.
Manage DbContext lifetime correctly.
Use asynchronous database operations.
Measure performance instead of relying on assumptions.

A useful mental model is:

                EF Core Performance
                       |
        +--------------+--------------+
        |              |              |
        v              v              v
      Query          Tracking       Loading
        |              |              |
        v              v              v
   Projection      NoTracking       Include
   Filtering       Context         Lazy Load
   Pagination      Lifetime        Split Query
        |              |              |
        +--------------+--------------+
                       |
                       v
                 Database Work
                       |
                       v
                 Measure & Tune

Conclusion

EF Core performance optimization is not about applying every available optimization.

It is about understanding the workload and choosing the simplest approach that avoids unnecessary work.

When an EF Core query becomes slow, start with a few fundamental questions:

What data do I actually need?

How many database calls am I making?

Is EF Core tracking entities unnecessarily?

What SQL is actually being generated?

Can the operation be performed efficiently at the database level?

Once these questions become part of the development and code-review process, many EF Core performance issues can be identified before they become production problems.

The best optimization is often not a complicated EF Core technique. It is simply doing less unnecessary work.

dotnet #csharp #efcore #entityframework #aspnetcore #performance #softwarearchitecture #programming

SOLID Principles in C#: A Practical Guide with Real-World Examples and Design Patterns

Chethan Ramaswamy — Sat, 26 Sep 2026 09:30:35 +0000

📑 Contents

What Does SOLID Mean?
SOLID Is Not the Same as Design Patterns
1. Single Responsibility Principle — SRP
- The Simple Explanation
- A Common Problem
- Refactoring the Design
- Design Patterns and Techniques That Can Support SRP
- Common SRP Mistake
2. Open/Closed Principle — OCP
- The Simple Explanation
- A Common Problem
- Applying the Strategy Pattern
- Strategy Pattern and OCP
- Factory Pattern and OCP
3. Liskov Substitution Principle — LSP
- The Simple Explanation
- The Classic Example
- A Better Design
- LSP in Enterprise Applications
- LSP and Composition
- Common LSP Warning Signs
4. Interface Segregation Principle — ISP
- The Simple Explanation
- A Common Problem
- Split the Interface
- ISP in an Enterprise Service
- Patterns That Can Support ISP
- Common ISP Mistake
5. Dependency Inversion Principle — DIP
- The Simple Explanation
- A Common Problem
- Introduce an Abstraction
Dependency Inversion vs Dependency Injection
- Dependency Inversion Principle
- Dependency Injection
SOLID and Design Patterns — The Practical Connection
SOLID Does Not Mean "More Interfaces"
SOLID Does Not Mean "Create More Classes"
SOLID Does Not Mean "Remove Every if/else"
SOLID Does Not Mean "Use Every Design Pattern"
A Real-World Example: Notification System
- Introduce an Abstraction
How to Identify SOLID Issues During Code Review
- SRP Questions
- OCP Questions
- LSP Questions
- ISP Questions
- DIP Questions
A Practical SOLID Refactoring Workflow
- Step 1 — Identify What Changes
- Step 2 — Identify the Coupling
- Step 3 — Identify the Responsibility
- Step 4 — Introduce an Abstraction When It Adds Value
- Step 5 — Choose a Pattern If It Fits
- Step 6 — Keep the Design Simple
SOLID in a Typical .NET Application
SOLID vs Design Patterns
When Should You Not Apply SOLID Aggressively?
A Simple SOLID Mental Model
SOLID Design Pattern Quick Reference
Common SOLID Misconceptions
- Misconception 1: "SOLID means more interfaces."
- Misconception 2: "SOLID means every class should have one method."
- Misconception 3: "SOLID means no if/else statements."
- Misconception 4: "DIP and Dependency Injection are the same."
- Misconception 5: "Every SOLID problem requires a design pattern."
- Misconception 6: "Inheritance is always better than composition."
- Misconception 7: "Following SOLID guarantees good architecture."
The Most Important Lesson
Final Takeaways
Practical SOLID Checklist

SOLID is one of the most discussed topics in object-oriented programming.

Most developers have heard of the five principles:

S — Single Responsibility Principle
O — Open/Closed Principle
L — Liskov Substitution Principle
I — Interface Segregation Principle
D — Dependency Inversion Principle

But knowing what the letters stand for is very different from knowing how to apply them.

A developer may remember that SRP means "a class should have one reason to change" but still struggle to identify an SRP violation in a real application.

Similarly, developers often learn design patterns such as Strategy, Factory, Adapter, Decorator, and Repository, but may not understand how these patterns relate to SOLID.

This article takes a practical approach.

Instead of simply memorizing definitions, we will look at:

The problem each SOLID principle tries to solve
How that problem appears in real applications
How to recognize the problem
How to refactor the design
Which design patterns or techniques can help
Common misconceptions
How the principles work together

The examples use C# and .NET, but the underlying concepts apply to object-oriented software in general.

What Does SOLID Mean?

SOLID is an acronym for five object-oriented design principles:

Principle	Meaning	Practical Question
S	Single Responsibility Principle	Does this class have more than one reason to change?
O	Open/Closed Principle	Can I add new behavior without repeatedly modifying stable code?
L	Liskov Substitution Principle	Can a derived type safely replace its base type?
I	Interface Segregation Principle	Are implementations forced to depend on methods they do not need?
D	Dependency Inversion Principle	Does my business logic depend directly on implementation details?

A simple way to remember them:

S → Keep responsibilities focused

O → Make changing behavior extensible

L → Make inheritance behaviorally trustworthy

I → Keep interfaces focused

D → Depend on abstractions

SOLID should not be treated as five rules that must be applied mechanically.

The goal is not to create more interfaces, classes, or abstractions.

The goal is to create software that is easier to:

Understand
Change
Test
Extend
Maintain

SOLID Is Not the Same as Design Patterns

This distinction is important.

SOLID principles are design principles.

Design patterns are reusable approaches to recurring software design problems.

For example:

Design Problem
      ↓
Identify the underlying design principle
      ↓
Consider possible design approaches
      ↓
Choose a suitable pattern or technique
      ↓
Keep the solution as simple as possible

A design pattern does not automatically make code SOLID.

Likewise, SOLID does not require the use of design patterns.

Use SOLID to guide your design decisions. Use a design pattern when it provides a practical solution to the problem you actually have.

Also, not every pattern discussed in this article is a Gang of Four (GoF) design pattern. For example, Repository and Dependency Injection are commonly used design or architectural techniques in modern enterprise applications, but they are not GoF patterns.

1. Single Responsibility Principle — SRP

The Simple Explanation

The Single Responsibility Principle states:

A class should have one reason to change.

This is often misunderstood as:

"A class should contain only one method."

That is not what SRP means.

A class can contain multiple methods and still have a single responsibility.

The better question is:

Do the responsibilities in this class change for different reasons?

A Common Problem

Imagine an e-commerce application with this class:

public class OrderService
{
    public void CreateOrder(Order order)
    {
        // Save order to database
    }

    public void ProcessPayment(Order order)
    {
        // Process payment
    }

    public void SendConfirmationEmail(Order order)
    {
        // Send email
    }

    public byte[] GenerateInvoice(Order order)
    {
        // Generate PDF invoice
        return [];
    }
}

At first glance, this may look convenient.

Everything related to an order is in one place.

But this class actually contains several responsibilities:

OrderService
    |
    +-- Order persistence
    |
    +-- Payment processing
    |
    +-- Email communication
    |
    +-- Invoice generation

Now consider the following changes:

The database technology changes.
The payment provider changes.
The email provider changes.
The invoice format changes.

These changes are driven by different concerns.

If all of them require modifying OrderService, the class has multiple reasons to change.

That is a warning sign for SRP.

Refactoring the Design

We can separate the responsibilities:

public interface IOrderRepository
{
    Task SaveAsync(Order order);
}

public interface IPaymentService
{
    Task ProcessAsync(Order order);
}

public interface INotificationService
{
    Task SendOrderConfirmationAsync(Order order);
}

public interface IInvoiceService
{
    Task<byte[]> GenerateAsync(Order order);
}

The application service can then coordinate the workflow:

public class OrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly IPaymentService _paymentService;
    private readonly INotificationService _notificationService;

    public OrderService(
        IOrderRepository orderRepository,
        IPaymentService paymentService,
        INotificationService notificationService)
    {
        _orderRepository = orderRepository;
        _paymentService = paymentService;
        _notificationService = notificationService;
    }

    public async Task CreateOrderAsync(Order order)
    {
        await _orderRepository.SaveAsync(order);
        await _paymentService.ProcessAsync(order);
        await _notificationService.SendOrderConfirmationAsync(order);
    }
}

Now the responsibilities are clearer:

OrderService
     |
     +── IOrderRepository
     +── IPaymentService
     +── INotificationService

OrderService coordinates the workflow instead of implementing every technical detail itself.

Design Patterns and Techniques That Can Support SRP

SRP does not require a particular design pattern.

However, several patterns or techniques can help separate responsibilities:

Pattern / Technique	How it can help
Facade	Provides a simplified interface over multiple components
Strategy	Separates interchangeable business algorithms
Command	Encapsulates an operation
Decorator	Separates cross-cutting behavior
Mediator	Separates request handling responsibilities
Repository	Separates persistence concerns from business logic

These are not "SRP patterns."

They are approaches that can help create a design with better separation of responsibilities.

Common SRP Mistake

A common misunderstanding is:

"Every class must do only one thing."

That can lead to unnecessary fragmentation.

For example, creating a separate class for every small method may produce a system with too many abstractions and dependencies.

Instead, ask:

Do these responsibilities change independently?

If they do, separating them may make the design easier to maintain.

If they do not, keeping them together may be perfectly reasonable.

2. Open/Closed Principle — OCP

The Simple Explanation

The Open/Closed Principle states:

Software entities should be open for extension but closed for modification.

A practical interpretation is:

Design areas of expected variation so that new behavior can be added without repeatedly changing stable, already-tested code.

This does not mean existing code can never be modified.

Requirements change, bugs need fixing, and designs evolve.

The principle is about avoiding unnecessary modification of stable code every time a new variation is introduced.

A Common Problem

Consider payment processing:

public class PaymentService
{
    public void Process(string paymentType, decimal amount)
    {
        if (paymentType == "CreditCard")
        {
            // Credit card payment
        }
        else if (paymentType == "PayPal")
        {
            // PayPal payment
        }
        else if (paymentType == "UPI")
        {
            // UPI payment
        }
    }
}

Today we support:

Credit Card
PayPal
UPI

Tomorrow we might add:

Bank Transfer
Apple Pay
Google Pay

If the conditional keeps growing, every new payment method requires modifying the same class.

The problem is not that if or switch statements are inherently bad.

The problem is that independently changing behavior is becoming tightly coupled to one piece of code.

Applying the Strategy Pattern

We can introduce an abstraction:

public interface IPaymentStrategy
{
    void Pay(decimal amount);
}

Then create separate implementations:

public class CreditCardPayment : IPaymentStrategy
{
    public void Pay(decimal amount)
    {
        // Process credit card payment
    }
}

public class UpiPayment : IPaymentStrategy
{
    public void Pay(decimal amount)
    {
        // Process UPI payment
    }
}

The service depends on the abstraction:

public class PaymentService
{
    private readonly IPaymentStrategy _paymentStrategy;

    public PaymentService(IPaymentStrategy paymentStrategy)
    {
        _paymentStrategy = paymentStrategy;
    }

    public void Process(decimal amount)
    {
        _paymentStrategy.Pay(amount);
    }
}

Now a new payment method can be introduced:

public class BankTransferPayment : IPaymentStrategy
{
    public void Pay(decimal amount)
    {
        // Process bank transfer
    }
}

The existing payment implementations do not need to change.

Strategy Pattern and OCP

This is one of the clearest relationships between SOLID and design patterns:

Problem
   ↓
Multiple interchangeable behaviors
   ↓
Identify the variation
   ↓
Encapsulate each behavior
   ↓
Strategy Pattern
   ↓
Add new strategies without changing existing strategies

The Strategy Pattern is particularly useful when several algorithms or business rules implement the same conceptual operation.

Factory Pattern and OCP

A Factory can be useful when object creation is itself a concern.

For example:

public interface IPaymentProcessor
{
    void Process(decimal amount);
}

Implementations:

IPaymentProcessor
       |
       +---- CreditCardProcessor
       +---- UpiProcessor
       +---- BankTransferProcessor

A simple factory might select an implementation:

public class PaymentProcessorFactory
{
    public IPaymentProcessor Create(string type)
    {
        return type switch
        {
            "CreditCard" => new CreditCardProcessor(),
            "UPI" => new UpiProcessor(),
            "BankTransfer" => new BankTransferProcessor(),
            _ => throw new ArgumentException("Unsupported payment type")
        };
    }
}

However, notice something important.

The factory itself must change when a new payment type is added.

Therefore, this factory is not automatically an example of a completely closed-for-modification design.

It can still be a useful solution if the creation logic is intentionally centralized and the trade-off is acceptable.

In larger .NET applications, dependency injection, keyed services, configuration-driven registration, or other approaches may sometimes provide a better fit.

The lesson is:

Do not use a pattern simply because its name appears in a SOLID discussion. Evaluate the actual design trade-off.

3. Liskov Substitution Principle — LSP

The Simple Explanation

The Liskov Substitution Principle states that:

A derived type should be usable wherever its base type is expected without violating the expectations of the consuming code.

In simpler terms:

If B is a subtype of A, replacing an A with a B should not unexpectedly break the program's correctness or behavioral assumptions.

LSP is less about syntax and more about behavioral contracts.

The Classic Example

Consider:

public class Bird
{
    public virtual void Fly()
    {
        Console.WriteLine("Flying");
    }
}

Now imagine:

public class Penguin : Bird
{
    public override void Fly()
    {
        throw new NotSupportedException();
    }
}

We have created a problem.

The base class exposes Fly() as a behavior that consumers can call.

But Penguin cannot provide that behavior.

This code becomes problematic:

Bird bird = new Penguin();

bird.Fly();

The derived type cannot safely satisfy the expectations created by the base abstraction.

A Better Design

The problem is the abstraction.

Not every bird needs to support flying.

We can separate the concepts:

public abstract class Bird
{
    public abstract void Move();
}

Then define flying separately:

public interface IFlyingBird
{
    void Fly();
}

An eagle can implement it:

public class Eagle : Bird, IFlyingBird
{
    public override void Move()
    {
        Fly();
    }

    public void Fly()
    {
        Console.WriteLine("Eagle is flying");
    }
}

A penguin does not need to implement IFlyingBird:

public class Penguin : Bird
{
    public override void Move()
    {
        Console.WriteLine("Penguin is walking");
    }
}

The abstraction now better represents the actual capabilities of the types.

LSP in Enterprise Applications

The Bird/Penguin example is useful for understanding the principle, but enterprise applications often encounter LSP problems in more subtle ways.

Consider a payment processor:

public abstract class PaymentProcessor
{
    public abstract void Process(decimal amount);
    public abstract void Refund(decimal amount);
}

Suppose an implementation does not support refunds:

public class SomePaymentProcessor : PaymentProcessor
{
    public override void Process(decimal amount)
    {
        // Process payment
    }

    public override void Refund(decimal amount)
    {
        throw new NotSupportedException();
    }
}

If consumers of PaymentProcessor reasonably expect every implementation to support refunds, the abstraction is too broad.

A better design may separate the capabilities:

public interface IPaymentProcessor
{
    void Process(decimal amount);
}

public interface IRefundProcessor
{
    void Refund(decimal amount);
}

An implementation can then support the capabilities it actually provides.

This example also connects naturally to the Interface Segregation Principle.

LSP and Composition

A useful way to avoid problematic inheritance is to consider composition.

Instead of creating a complex hierarchy:

BaseProcessor
     |
     +-- ProcessorA
     +-- ProcessorB
     +-- ProcessorC

consider whether behavior can be composed:

Processor
    |
    +-- Strategy
    +-- Validator
    +-- Formatter

Composition is not a replacement for inheritance in every situation, but it can reduce problems caused by incorrect inheritance relationships.

Common LSP Warning Signs

Look carefully when you see:

throw new NotSupportedException();

inside an overridden method.

This is not automatically an LSP violation.

Sometimes an unsupported operation is legitimate.

But it should trigger a design question:

Does the base abstraction promise behavior that this implementation cannot provide?

Other warning signs include:

Derived classes disabling base behavior
Derived classes significantly changing the meaning of base methods
Consumers checking concrete subtypes before using them
Large type-checking blocks
Frequent is checks against derived types
Special-case handling for particular subclasses

4. Interface Segregation Principle — ISP

The Simple Explanation

The Interface Segregation Principle states:

Clients should not be forced to depend on methods they do not use.

In simpler terms:

Prefer focused interfaces that represent meaningful capabilities over large interfaces containing unrelated operations.

A Common Problem

Consider an employee management system:

public interface IEmployee
{
    void Work();
    void Eat();
    void AttendMeeting();
    void WriteCode();
    void ManageTeam();
}

Now imagine a developer:

public class Developer : IEmployee
{
    public void Work()
    {
    }

    public void Eat()
    {
    }

    public void AttendMeeting()
    {
    }

    public void WriteCode()
    {
    }

    public void ManageTeam()
    {
        throw new NotSupportedException();
    }
}

The developer is forced to implement ManageTeam() even though that capability is not part of the developer's responsibility.

This is a sign of a fat interface.

Split the Interface

Instead, define smaller, cohesive interfaces:

public interface IWorker
{
    void Work();
}

public interface IDeveloper
{
    void WriteCode();
}

public interface IManager
{
    void ManageTeam();
}

Now:

public class Developer : IWorker, IDeveloper
{
    public void Work()
    {
    }

    public void WriteCode()
    {
    }
}

And:

public class EngineeringManager : IWorker, IManager
{
    public void Work()
    {
    }

    public void ManageTeam()
    {
    }
}

Each class depends only on the capabilities it needs.

ISP in an Enterprise Service

Imagine a large customer service interface:

public interface ICustomerService
{
    Customer GetCustomer(int id);
    void CreateCustomer(Customer customer);
    void UpdateCustomer(Customer customer);
    void DeleteCustomer(int id);
    void SendMarketingEmail(int id);
    void ExportCustomers();
}

Different consumers may need completely different capabilities.

Instead, we could separate them:

public interface ICustomerReader
{
    Customer GetCustomer(int id);
}

public interface ICustomerWriter
{
    void CreateCustomer(Customer customer);
    void UpdateCustomer(Customer customer);
    void DeleteCustomer(int id);
}

public interface ICustomerExporter
{
    void ExportCustomers();
}

This creates smaller contracts that can be consumed independently.

Patterns That Can Support ISP

Some patterns can complement interface segregation:

Adapter — exposes the interface a client actually needs
Facade — provides a focused interface over a more complex subsystem
Proxy — can provide a focused boundary around another component

Again, the pattern does not implement ISP automatically.

The important design decision is to ensure clients are not forced to depend on irrelevant operations.

Common ISP Mistake

Do not interpret ISP as:

"Every interface should contain exactly one method."

That is not the principle.

An interface can contain several methods when they represent one cohesive capability.

For example:

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(int id);
    Task AddAsync(Order order);
    Task UpdateAsync(Order order);
}

These operations may form a cohesive persistence contract.

The goal is cohesion, not an arbitrary number of methods.

5. Dependency Inversion Principle — DIP

The Simple Explanation

The Dependency Inversion Principle states:

High-level modules should not depend on low-level modules. Both should depend on abstractions.

It also states:

Abstractions should not depend on details. Details should depend on abstractions.

In simpler terms:

Business logic should not be tightly coupled to infrastructure details.

A Common Problem

Consider:

public class OrderService
{
    private readonly SqlOrderRepository _repository;

    public OrderService()
    {
        _repository = new SqlOrderRepository();
    }

    public void CreateOrder(Order order)
    {
        _repository.Save(order);
    }
}

OrderService directly creates SqlOrderRepository.

The business service now knows:

Which persistence implementation is being used
How the repository is created
That the repository is backed by SQL Server

This creates tight coupling.

Introduce an Abstraction

Define:

public interface IOrderRepository
{
    void Save(Order order);
}

The infrastructure implementation can be:

public class SqlOrderRepository : IOrderRepository
{
    public void Save(Order order)
    {
        // Save to SQL Server
    }
}

Now the service depends on the abstraction:

public class OrderService
{
    private readonly IOrderRepository _repository;

    public OrderService(IOrderRepository repository)
    {
        _repository = repository;
    }

    public void CreateOrder(Order order)
    {
        _repository.Save(order);
    }
}

The dependency direction becomes:

Before:

OrderService
     |
     ↓
SqlOrderRepository


After:

OrderService
     |
     ↓
IOrderRepository
     ↑
     |
SqlOrderRepository

The high-level business logic no longer needs to know the concrete persistence implementation.

Dependency Inversion vs Dependency Injection

These concepts are closely related but are not the same thing.

Dependency Inversion Principle

DIP is a design principle.

It describes how high-level and low-level components should depend on abstractions.

Dependency Injection

Dependency Injection is a technique for providing dependencies to a class from outside the class.

For example:

public OrderService(IOrderRepository repository)
{
    _repository = repository;
}

This is constructor injection.

In ASP.NET Core, the built-in dependency injection container can register the implementation:

builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();
builder.Services.AddScoped<OrderService>();

The framework can then provide SqlOrderRepository when OrderService is created.

So the relationship is:

DIP
 ↓
Design principle

Dependency Injection
 ↓
Implementation technique

Dependency Injection is one common way to implement a design that follows DIP.

SOLID and Design Patterns — The Practical Connection

Now let's connect the principles with patterns and techniques that can help address related design problems.

SOLID Principle	Patterns / Techniques That May Help	Typical Design Problem
SRP	Command, Strategy, Decorator, Facade, Repository	Too many independent responsibilities
OCP	Strategy, Decorator, Template Method, Factory	New behavior repeatedly requires modifying existing code
LSP	Strategy, Adapter, Composition	Incorrect or overly restrictive inheritance
ISP	Adapter, Facade, Proxy	Clients depend on unnecessary operations
DIP	Dependency Injection, Adapter, Repository, Factory	Business logic depends directly on implementation details

This is not a strict one-to-one mapping.

A pattern can support multiple SOLID principles, and a SOLID principle can be applied without using a design pattern.

For example:

Strategy
   ↓
Can support OCP
   ↓
Can also help SRP
   ↓
May also improve testability

Likewise:

Adapter
   ↓
Can help isolate an external dependency
   ↓
Can support DIP
   ↓
Can expose a focused interface
   ↓
Can support ISP

The correct approach is to start with the design problem, not the pattern name.

SOLID Does Not Mean "More Interfaces"

One of the biggest misconceptions about SOLID is:

"If I create interfaces everywhere, my code is SOLID."

Not necessarily.

Consider:

public interface IUserService
{
    void CreateUser();
}

public class UserService : IUserService
{
    public void CreateUser()
    {
    }
}

If the interface provides no meaningful abstraction or architectural boundary, it may simply add indirection.

Instead, ask:

Where do I actually need an abstraction?

Useful boundaries often include:

External systems
Infrastructure
Business strategies
Multiple implementations
Testing boundaries
Plugin-style architectures
Components that are expected to vary independently

Abstraction has a cost.

Use it where it provides a meaningful benefit.

SOLID Does Not Mean "Create More Classes"

Another common mistake is over-fragmentation.

For example:

OrderService
OrderValidator
OrderCalculator
OrderMapper
OrderLogger
OrderFormatter
OrderHelper
OrderUtility
OrderManager
OrderProcessor
OrderHandler

Having many classes does not automatically mean the design is better.

A highly fragmented design can introduce:

More dependencies
More files
More abstractions
More cognitive overhead
More difficult debugging
More complex dependency graphs

The objective is appropriate separation, not maximum separation.

SOLID Does Not Mean "Remove Every if/else"

Another misconception is:

"SOLID means removing every if/else statement."

That's not true.

This can be perfectly reasonable:

if (order.Total > 1000)
{
    ApplyDiscount(order);
}

The question is whether the conditional represents a stable rule or whether it is continuously growing with independently changing behavior.

For example:

if (paymentType == "CreditCard")
{
}
else if (paymentType == "UPI")
{
}
else if (paymentType == "PayPal")
{
}
else if (paymentType == "BankTransfer")
{
}

If this list continuously grows and each branch represents an independent behavior, the Strategy Pattern may be worth considering.

The pattern should be introduced because it improves the design, not simply because an if statement exists.

SOLID Does Not Mean "Use Every Design Pattern"

Design patterns are tools.

Using them everywhere can create unnecessary complexity.

For example, a simple calculation does not need:

Abstract Factory
      ↓
Factory Method
      ↓
Strategy
      ↓
Decorator
      ↓
Mediator

when this may be sufficient:

public decimal CalculateTax(decimal amount)
{
    return amount * 0.18m;
}

A good engineer knows not only how to apply patterns, but also when not to apply them.

A Real-World Example: Notification System

Let's bring several SOLID principles together using a notification system.

Suppose an application needs to send:

Email
SMS
Push notifications

A simple implementation might look like this:

public class NotificationService
{
    public void Send(string type, string recipient, string message)
    {
        if (type == "Email")
        {
            // Send email
        }
        else if (type == "SMS")
        {
            // Send SMS
        }
        else if (type == "Push")
        {
            // Send push notification
        }
    }
}

It works.

But what happens when we add:

WhatsApp
Microsoft Teams
Slack

The class keeps growing.

Introduce an Abstraction

public interface INotificationSender
{
    Task SendAsync(string recipient, string message);
}

Email:

public class EmailNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        // Send email
        return Task.CompletedTask;
    }
}

SMS:

public class SmsNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        // Send SMS
        return Task.CompletedTask;
    }
}

Push:

public class PushNotificationSender : INotificationSender
{
    public Task SendAsync(string recipient, string message)
    {
        // Send push notification
        return Task.CompletedTask;
    }
}

The application service can work with the abstraction:

public class NotificationService
{
    private readonly INotificationSender _sender;

    public NotificationService(INotificationSender sender)
    {
        _sender = sender;
    }

    public Task SendAsync(string recipient, string message)
    {
        return _sender.SendAsync(recipient, message);
    }
}

The resulting design is:

NotificationService
        |
        ↓
INotificationSender
        ↑
        |
  +-----+-----+------+
  |           |      |
Email        SMS    Push

Several principles are represented here.

SRP

Each sender is responsible for one notification mechanism.

OCP

A new notification mechanism can be introduced as another implementation without changing the existing senders.

LSP

Each implementation should honor the behavioral contract defined by INotificationSender.

ISP

The interface contains only the operation needed by notification senders.

DIP

NotificationService depends on INotificationSender, not directly on an email, SMS, or push provider.

This is a good example of how SOLID principles can work together rather than being treated as five isolated rules.

How to Identify SOLID Issues During Code Review

Instead of checking the five principles mechanically, ask practical questions.

SRP Questions

Does this class have unrelated responsibilities?
Would different concerns cause different changes to this class?
Does the class interact with too many unrelated technologies?
Is the class becoming a "God class"?

OCP Questions

Does adding a new behavior require modifying existing logic?
Is a conditional structure continuously growing?
Are new business rules repeatedly being added to the same class?
Can the changing behavior be isolated?

LSP Questions

Does a subclass throw NotSupportedException for inherited behavior?
Does a subclass change the expected meaning of a base method?
Do consumers need to check the concrete subtype before using it?
Is inheritance actually representing the required behavioral relationship?

ISP Questions

Are implementations forced to implement irrelevant methods?
Is the interface becoming very large?
Do different consumers use completely different subsets of the interface?
Can the contract be divided into meaningful capabilities?

DIP Questions

Does business logic directly instantiate infrastructure classes?
Does a service depend directly on a database provider?
Does business logic know about external SDK implementation details?
Can an infrastructure implementation be replaced without changing business logic?

A Practical SOLID Refactoring Workflow

You do not need to redesign an entire application whenever you discover a SOLID issue.

A practical workflow is:

Step 1 — Identify What Changes

Ask:

What is likely to change independently?

Examples:

Payment provider
Notification channel
Database
Pricing algorithm
Authentication mechanism
File storage provider

Step 2 — Identify the Coupling

Ask:

Which component knows too much about this changing behavior?

Step 3 — Identify the Responsibility

Ask:

Can this behavior be separated without making the design unnecessarily complex?

Step 4 — Introduce an Abstraction When It Adds Value

For example:

public interface IPaymentProcessor
{
    Task ProcessAsync(decimal amount);
}

Step 5 — Choose a Pattern If It Fits

For example:

Multiple interchangeable algorithms
        ↓
Strategy Pattern

External system has an incompatible API
        ↓
Adapter Pattern

Object creation is complex or needs encapsulation
        ↓
Factory Pattern

Step 6 — Keep the Design Simple

Do not introduce five abstractions when one abstraction solves the problem.

SOLID in a Typical .NET Application

A typical enterprise application may have a structure similar to:

                 API Controller
                       |
                       ↓
              Application Service
                       |
          +------------+------------+
          |            |            |
          ↓            ↓            ↓
     Repository     Payment     Notification
          |         Strategy       Service
          ↓            |
      Database      +--+--+
                    |     |
                  Card   UPI

This does not mean every .NET application should have exactly this structure.

It simply demonstrates how the principles can work together.

SRP

Components have focused responsibilities.

OCP

New payment strategies can be introduced without modifying existing payment strategies.

LSP

Payment implementations should honor the abstraction's behavioral contract.

ISP

Consumers can depend on focused interfaces.

DIP

Application-level code depends on abstractions rather than infrastructure implementations.

SOLID vs Design Patterns

SOLID Principles	Design Patterns
Design principles	Reusable design approaches
Help guide design decisions	Help solve recurring design problems
More abstract	More concrete
Help identify desirable design characteristics	Provide implementation techniques
Can be applied without design patterns	Can be used independently of SOLID
Focus on maintainability and flexibility	Focus on recurring structural or behavioral problems

A useful mental model is:

SOLID tells you what characteristics to aim for. Design patterns provide techniques that may help you achieve those characteristics.

When Should You Not Apply SOLID Aggressively?

SOLID is valuable, but context matters.

For a small application with a simple and stable requirement:

Simple problem
     ↓
Simple implementation

may be better than:

Simple problem
     ↓
Multiple interfaces
     ↓
Multiple factories
     ↓
Multiple strategies
     ↓
Complex dependency graph

For a larger application with:

Multiple teams
Frequent requirement changes
External integrations
Complex business rules
Long-term maintenance
Significant automated testing requirements

appropriate abstractions can provide greater value.

The right design depends on:

Complexity
Change frequency
Number of implementations
Team size
Testing requirements
Expected lifetime of the software
Operational requirements

SOLID is a design guide, not a requirement to maximize abstraction.

A Simple SOLID Mental Model

When reviewing a class, ask these five questions:

1. S — Does this class have too many independent reasons to change?

2. O — Do I repeatedly modify this code whenever a new behavior is introduced?

3. L — Can every implementation genuinely honor the behavioral contract
       of its abstraction?

4. I — Is the interface asking implementations to support things they
       don't need?

5. D — Does my business logic depend directly on infrastructure or
       concrete implementations?

These questions are often more useful during code reviews than simply memorizing five definitions.

SOLID Design Pattern Quick Reference

Principle	Common Design Smell	Possible Refactoring	Patterns / Techniques That May Help
SRP	One class has unrelated responsibilities	Extract cohesive responsibilities	Command, Strategy, Decorator, Facade, Repository
OCP	New behavior repeatedly requires modifying existing code	Encapsulate variation behind abstractions	Strategy, Decorator, Template Method, Factory
LSP	Derived type cannot honor the base contract	Redesign the abstraction or prefer composition	Strategy, Adapter, Composition
ISP	Large interface with irrelevant methods	Split into cohesive capabilities	Adapter, Facade, Proxy
DIP	Business logic directly depends on infrastructure	Introduce appropriate abstractions	Dependency Injection, Adapter, Repository, Factory

This table is a practical association, not a strict rule.

There is no requirement that a particular SOLID principle must always be implemented using a particular pattern.

Common SOLID Misconceptions

Misconception 1: "SOLID means more interfaces."

Reality: Interfaces are useful when they represent meaningful abstractions or boundaries.

Misconception 2: "SOLID means every class should have one method."

Reality: SRP is about reasons to change, not method count.

Misconception 3: "SOLID means no if/else statements."

Reality: Conditional logic is perfectly valid. The question is whether independently changing behavior is becoming tightly coupled.

Misconception 4: "DIP and Dependency Injection are the same."

Reality: DIP is a design principle. Dependency Injection is one technique that can help implement it.

Misconception 5: "Every SOLID problem requires a design pattern."

Reality: Sometimes a simple refactoring is the best solution.

Misconception 6: "Inheritance is always better than composition."

Reality: Inheritance is useful when the subtype genuinely satisfies the behavioral contract of the base abstraction. Composition can be preferable when behavior needs to vary independently.

Misconception 7: "Following SOLID guarantees good architecture."

Reality: SOLID addresses important object-oriented design concerns, but good architecture also requires consideration of performance, security, reliability, scalability, maintainability, operational complexity, and business requirements.

The Most Important Lesson

When developers learn SOLID, it is tempting to memorize statements such as:

SRP → One responsibility

OCP → Open for extension, closed for modification

LSP → Subtypes must be substitutable

ISP → Small interfaces

DIP → Depend on abstractions

These definitions are useful, but they are only the starting point.

A more useful engineering mindset is:

What is changing?
       ↓
What is coupled to that change?
       ↓
Is the responsibility cohesive?
       ↓
Is the abstraction meaningful?
       ↓
Can the dependency be inverted?
       ↓
Would a design pattern simplify the solution?
       ↓
Is the resulting design actually easier to maintain?

That is where SOLID becomes practical.

Final Takeaways

SOLID is not about writing more code.

It is about making change easier to manage.

The five principles can be summarized as:

SRP
→ Keep responsibilities focused.

OCP
→ Isolate expected variation so new behavior can be added with
  minimal modification to stable code.

LSP
→ Make abstractions behaviorally trustworthy.

ISP
→ Keep contracts focused on meaningful capabilities.

DIP
→ Keep high-level business logic independent from implementation details.

Design patterns and techniques can support these principles:

SRP → Command, Strategy, Decorator, Facade, Repository

OCP → Strategy, Decorator, Template Method, Factory

LSP → Strategy, Adapter, Composition

ISP → Adapter, Facade, Proxy

DIP → Dependency Injection, Adapter, Repository, Factory

But there is an even more important lesson:

Don't start with a design pattern. Start with the problem.

Ask:

What is changing?
What is tightly coupled to that change?
Can the responsibility be separated?
Is an abstraction actually useful?
Would a design pattern simplify the solution?
Does the resulting design reduce complexity rather than increase it?

Good software design is not about following SOLID mechanically.

It is about creating a codebase where responsibilities are clear, dependencies are manageable, expected changes are easier to accommodate, and complexity is kept under control.

The best SOLID design is not the one with the most abstractions.

It is the one that makes the important changes easier without introducing unnecessary complexity.

Practical SOLID Checklist

Before committing a significant design change, ask:

□ Does each component have a clear and cohesive responsibility?

□ Can expected variations be added without repeatedly changing stable code?

□ Can implementations safely honor the contracts of their abstractions?

□ Are interfaces focused on meaningful capabilities?

□ Does business logic avoid unnecessary dependencies on infrastructure details?

□ Am I introducing an abstraction because I need it, rather than because
  SOLID tells me to?

□ Am I using a design pattern because it solves a real problem?

□ Has the solution become simpler or more maintainable?

□ Have I avoided unnecessary layers and abstractions?

If the answer to these questions is clear, you are applying SOLID as an engineering principle, rather than simply memorizing its definitions.

programming

csharp

dotnet

solid

designpatterns

softwarearchitecture

RAG Explained: A Beginner's Guide to Retrieval-Augmented Generation

Chethan Ramaswamy — Sat, 26 Sep 2026 06:31:04 +0000

📑 Contents

Imagine You Have 10,000 Company Documents
So, What Is RAG?
A Simple Real-World Example
How Does RAG Actually Work?
- Stage 1: Prepare the Knowledge
- Step 1: Collect Your Documents
- Step 2: Break Large Documents into Smaller Pieces
- Step 3: Create Embeddings
- Step 4: Store the Information
- Stage 2: Answer the User's Question
- Step 5: The User Asks a Question
- Step 6: Give the Information to the AI
The Complete RAG Flow
- Preparing the knowledge
- Answering a question
Is RAG Just Search?
RAG vs Fine-Tuning
Where Can We Use RAG?
- Developer Assistant
- HR Assistant
- Customer Support
- Enterprise Knowledge Assistant
Does RAG Make AI 100% Accurate?
What Does RAG Look Like with .NET and Azure?
The 5 Things You Need to Remember
Your Turn
Key Takeaway

If you've started learning Generative AI, you've probably come across terms like:

LLM. Embeddings. Vector Search. RAG.

At first, these terms can sound complicated.

But the basic idea behind RAG is actually quite simple.

Let's understand it with a real-world example. 👇

🤔 Imagine You Have 10,000 Company Documents

Imagine your company has thousands of documents:

HR policies
Travel policies
Product documentation
Technical guides
Customer FAQs
Security guidelines

Now an employee asks:

"How much can I claim for a hotel during business travel?"

Would you expect a general AI model to know your company's specific policy?

Probably not.

The information is inside your company's documents.

This is where RAG becomes useful.

💡 So, What Is RAG?

RAG stands for Retrieval-Augmented Generation.

Think of RAG like this:

Find the right information first, then ask the AI to answer using that information.

That's the basic idea.

A simplified flow looks like this:

User asks a question
        ↓
Find relevant information
        ↓
Give that information to the AI
        ↓
AI generates an answer

Let's see how this works.

🏨 A Simple Real-World Example

Suppose your company's travel policy says:

Employees can claim hotel expenses up to ₹5,000 per night when traveling for business.

An employee asks:

"What is the hotel reimbursement limit?"

A RAG application can:

Search the company's travel policy.
Find the relevant information.
Provide that information to the AI.
Generate an answer.

The AI can then respond:

"According to the travel policy, employees can claim hotel expenses up to ₹5,000 per night."

Notice what happened?

The AI didn't need to already know your company's travel policy.

The application retrieved the relevant information first.

That's the basic idea behind RAG.

🔍 How Does RAG Actually Work?

Let's break it down into a few simple steps.

Don't worry — we'll keep the technical jargon to a minimum.

A basic RAG application can be understood in two stages:

Prepare the knowledge
Answer the user's question

Let's look at both.

📚 Stage 1: Prepare the Knowledge

Before users can ask questions, we need to prepare the documents so that relevant information can be found quickly.

📄 Step 1: Collect Your Documents

Your knowledge could come from many places:

📄 PDF files
📝 Word documents
🌐 Websites
🗄️ Databases
☁️ Cloud storage
📚 Knowledge bases

For example:

Company Knowledge
       │
       ├── HR Policy.pdf
       ├── Travel Policy.pdf
       ├── Security Policy.pdf
       └── Product Manual.pdf

These documents become the knowledge source for our AI application.

✂️ Step 2: Break Large Documents into Smaller Pieces

Imagine you have a 100-page travel policy.

We don't want to send all 100 pages to the AI every time someone asks a question.

Instead, we divide the document into smaller pieces called chunks.

Travel Policy
      │
      ├── Chunk 1
      ├── Chunk 2
      ├── Chunk 3
      ├── Chunk 4
      └── ...

Why?

Because when someone asks a question, we usually need only the small section related to that question.

For example:

Question:

"What is the hotel reimbursement limit?"

The system might retrieve:

Chunk 27:

"Employees can claim hotel expenses
up to ₹5,000 per night..."

That's much more useful than sending the entire document to the AI.

💡 Think of it this way

Imagine giving a student a 500-page textbook and asking:

"Find the paragraph about hotel reimbursement."

It would take time to search through the entire book.

Instead, if we already know the relevant page, we can go directly there.

Chunking helps us create those smaller searchable pieces of information.

🧠 Step 3: Create Embeddings

Here's our first technical concept:

Embeddings.

Embeddings are numerical representations of text that help systems measure semantic similarity.

Embeddings help a system find information based on semantic similarity, rather than only matching exact words.

For example:

User asks:

"How much can I claim for a hotel?"

The document says:

"Hotel accommodation expenses are limited to ₹5,000 per night."

The words aren't exactly the same.

But the meaning is related.

Embeddings help the system identify this semantic similarity.

You can think of it like this:

Text
 ↓
Embedding Model
 ↓
Numerical Vector
 ↓
Compare with other vectors
 ↓
Find semantically similar content

You don't need to understand the mathematics behind embeddings to start learning RAG.

The important thing to remember is:

Embeddings help a system find information based on semantic similarity, rather than only matching exact words.

🗂️ Step 4: Store the Information

Now we need somewhere to store our document chunks and their embeddings.

This is where vector databases and vector search systems come in.

Some popular options include:

Azure AI Search
PostgreSQL + pgvector
Pinecone
Qdrant
Weaviate

Think of this as a smart search system for your documents.

Conceptually:

Document Chunk
      +
Embedding
      +
Metadata
      ↓
Vector Search

Metadata can contain information such as:

Document: TravelPolicy.pdf
Department: Finance
Year: 2026
DocumentType: Policy

This additional information can help the application filter and organize the data.

🔎 Stage 2: Answer the User's Question

Now our knowledge has been prepared.

Let's see what happens when a user asks a question.

🔎 Step 5: The User Asks a Question

The employee asks:

"What is the hotel reimbursement limit?"

The application converts the question into an embedding and uses it to search the knowledge base.

The search might return several results:

Result 1:
Employees can claim hotel expenses
up to ₹5,000 per night.

Result 2:
Business travel expenses must be
submitted within 30 days.

Result 3:
International travel requires
manager approval.

The application identifies the information that is most relevant to the question.

🤖 Step 6: Give the Information to the AI

Now we have two important pieces:

Question:

What is the hotel reimbursement limit?

Relevant information:

Employees can claim hotel expenses up to ₹5,000 per night.

The application provides the question and retrieved context to the LLM.

Conceptually:

User Question
      +
Retrieved Context
      ↓
Prompt
      ↓
LLM
      ↓
Generated Answer

The LLM can then generate:

"Employees can claim hotel expenses up to ₹5,000 per night."

And that's the Generation part of Retrieval-Augmented Generation.

🧩 The Complete RAG Flow

Now let's separate the process into two simple flows.

Preparing the knowledge

Documents
    ↓
Chunking
    ↓
Embeddings
    ↓
Vector Search Index

Answering a question

User Question
      ↓
Question Embedding
      ↓
Search the Knowledge Base
      ↓
Relevant Chunks
      ↓
Question + Retrieved Context
      ↓
LLM
      ↓
Final Answer

This is the heart of a RAG application.

Retrieve relevant information → provide it as context → generate an answer.

🔍 Is RAG Just Search?

Not exactly.

Traditional search might work like this:

Question
   ↓
Search
   ↓
List of Documents

You then need to open the documents and find the answer yourself.

RAG goes one step further:

Question
   ↓
Search Relevant Information
   ↓
Provide Context to AI
   ↓
Generate Answer

So you can think of RAG as:

Search + AI

Traditional search helps you find information.

A RAG application helps an AI system retrieve relevant information and generate an answer using that information.

🆚 RAG vs Fine-Tuning

This is another question beginners often have:

"Why not fine-tune the model instead?"

RAG and fine-tuning solve different problems.

RAG	Fine-Tuning
Retrieves external information at query time	Further trains the model
Useful when knowledge changes frequently	Useful for specialized behavior or tasks
Documents can be updated independently	Requires a training process
Commonly used for knowledge-based applications	Commonly used for specialized model behavior

A simple way to remember it:

RAG → Give the AI relevant information.

Fine-tuning → Adapt the AI for a specific behavior or task.

For example, if your company's HR policy changes next month, you can update the knowledge source used by a RAG application without retraining the language model.

🌎 Where Can We Use RAG?

RAG isn't limited to company policies.

It can be used in many real-world applications.

👨‍💻 Developer Assistant

A developer asks:

"How does our authentication service work?"

The RAG application searches the company's technical documentation and provides relevant context to the LLM.

🏢 HR Assistant

An employee asks:

"How many vacation days can I carry forward?"

The application searches HR policies and generates an answer based on the retrieved information.

🛠️ Customer Support

A customer asks:

"How do I reset my device?"

The application can search product documentation and provide step-by-step guidance.

📚 Enterprise Knowledge Assistant

An employee asks:

"What is the process for raising a purchase request?"

The application searches company procedures and generates a response.

The common pattern is:

Company Knowledge
       ↓
      RAG
       ↓
      LLM
       ↓
  AI Assistant

⚠️ Does RAG Make AI 100% Accurate?

No.

This is important to understand.

RAG can provide the AI with relevant information, but it does not guarantee a perfect answer.

For example, if the retrieval system finds the wrong information, the LLM may generate an incorrect response based on that context.

There can also be problems if:

The source document contains incorrect information.
Important information was not retrieved.
The retrieved context is incomplete.
The prompt doesn't clearly guide the model.
The model misunderstands the retrieved context.

That's why production RAG systems need good:

Document processing
Search and retrieval
Security
Prompt design
Evaluation
Monitoring

So don't think of RAG as a magic solution.

Instead, think of it as a way to ground an AI application with relevant external information.

☁️ What Does RAG Look Like with .NET and Azure?

If you're a .NET developer, a simple enterprise RAG architecture could look like this:

                 User
                   ↓
              .NET Web API
                   ↓
             Azure AI Search
                   ↓
             Relevant Chunks
                   ↓
             Prompt + Context
                   ↓
             Azure OpenAI
                   ↓
              AI Response

Your .NET application can orchestrate the process:

Receive the user's question.
Search for relevant information.
Retrieve the relevant chunks.
Build the prompt with the retrieved context.
Send the request to the AI model.
Return the response.

This makes RAG particularly interesting for developers working with .NET and Azure.

🎯 The 5 Things You Need to Remember

If you're completely new to RAG, remember these five concepts:

Documents

Where your knowledge lives.
Chunks

Smaller pieces of your documents.
Embeddings

Numerical representations that help systems measure semantic similarity.
Retrieval

Finding information relevant to the user's question.
Generation

The LLM uses the retrieved information to generate the answer.

Put them together:

Documents
    ↓
Chunks
    ↓
Embeddings
    ↓
Search
    ↓
Relevant Context
    ↓
LLM
    ↓
Answer

That's Retrieval-Augmented Generation.

💬 Your Turn

Have you tried building a RAG application?

What would you like to build with RAG?

👨‍💻 Developer assistant
📄 Document chatbot
🏢 Enterprise knowledge assistant
🛠️ Customer support assistant
🤖 Something else

Share your idea in the comments. 👇

📌 Key Takeaway

If you remember just one sentence from this article, remember this:

A RAG application retrieves relevant information from a knowledge source and provides it to an LLM so it can generate a more informed response.

And that's the foundation of many modern Generative AI applications.

Designing a Scalable Notification System using .NET, Azure Service Bus, MediatR, and SignalR

Chethan Ramaswamy — Tue, 31 Mar 2026 19:35:49 +0000

📌 What We'll Cover

Why I'm Writing This
The Problem with the "Simple" Approach
A Better Approach: Event-Driven Notifications
High-Level Architecture
Where MediatR Fits
Why Azure Service Bus?
- Loose Coupling
- Retry and Failure Handling
- Independent Scaling
- Future Integrations
Topics and Subscriptions
SignalR for Real-Time Notifications
SignalR at Scale
End-to-End Flow
- Step 1 — User Performs an Action
- Step 2 — API Receives the Request
- Step 3 — Command Handler Processes the Business Operation
- Step 4 — Outbox Processor Publishes the Event
- Step 5 — Consumers Process the Event
- Step 6 — Real-Time Update Reaches the Client
One Important Production Consideration: The Outbox Pattern
Handling Duplicate Messages
Trade-Offs
Where This Architecture Works Well
- E-commerce
- Banking
- Monitoring Platforms
- Enterprise Applications
Key Design Principles
- MediatR
- Azure Service Bus
- Azure Service Bus Topics and Subscriptions
- SignalR
- Azure SignalR Service
- Outbox Pattern
- Idempotent Consumers
- Dead-Letter Handling
Final Thoughts

Why I'm Writing This

“Send a notification when something happens.”

It sounds simple.

But in a real application, notifications can quickly become more complicated than expected.

You may need to support:

Real-time UI notifications
Email and SMS
Multiple consumers
Retries and failure handling
High traffic
Future integrations
Loose coupling between business logic and notification processing

The challenge is not simply how to send a notification.

The real question is:

How do we design notifications so they don't become tightly coupled to the core business flow?

This article walks through one approach using .NET, MediatR, Azure Service Bus, SignalR, and the Outbox Pattern.

The Problem with the "Simple" Approach

A common implementation starts with something like:

API
  ↓
Save to Database
  ↓
Send Email
  ↓
Send Notification

It works.

At least initially.

But as the application grows, problems start appearing.

Every feature begins calling notification logic directly:

OrderService → NotificationService
PaymentService → NotificationService
UserService → NotificationService

Then new requirements arrive:

Add SMS
Add push notifications
Add in-app notifications
Add analytics
Add audit events

The notification service gradually becomes tightly coupled to multiple parts of the application.

Another problem is failure handling.

What happens if the email provider is temporarily unavailable?

Should the order creation fail?

Usually, the answer is no.

The business operation and notification delivery have different reliability requirements.

A Better Approach: Event-Driven Notifications

The basic idea is:

Business Action
      ↓
Domain/Application Event
      ↓
Outbox
      ↓
Message Broker
      ↓
Notification Consumers
      ↓
Email / UI / SMS / Push / etc.

The business operation completes without waiting for every notification channel to finish.

This creates a much cleaner boundary between:

"Something happened"

and

"What should we do because it happened?"

High-Level Architecture

The production-oriented architecture looks like this:

                         ┌──────────────────┐
                         │      Client      │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │   .NET Web API   │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │     MediatR      │
                         │ Command Handler  │
                         └────────┬─────────┘
                                  │
                                  ▼
                     ┌──────────────────────────┐
                     │    Database Transaction  │
                     │                          │
                     │  ┌────────┐ ┌─────────┐ │
                     │  │ Order  │ │ Outbox  │ │
                     │  └────────┘ └─────────┘ │
                     └────────────┬─────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ Outbox Processor │
                         └────────┬─────────┘
                                  │
                                  ▼
                     ┌────────────────────────┐
                     │  Azure Service Bus     │
                     │        Topic           │
                     └────────────┬───────────┘
                                  │
                   ┌──────────────┼──────────────┐
                   │              │              │
                   ▼              ▼              ▼
             ┌──────────┐   ┌───────────┐  ┌──────────┐
             │  Email   │   │  SignalR  │  │  Audit   │
             │ Consumer │   │  Consumer │  │ Consumer │
             └──────────┘   └─────┬─────┘  └──────────┘
                                  │
                                  ▼
                     ┌────────────────────────┐
                     │ Azure SignalR Service  │
                     └────────────┬───────────┘
                                  │
                                  ▼
                           ┌─────────────┐
                           │   Clients   │
                           │Browser/Mobile│
                           └─────────────┘

The important principle is that each component has a specific responsibility.

The Outbox is part of the primary architecture, not an afterthought.

Where MediatR Fits

MediatR sits primarily inside the application layer.

Instead of having a controller directly coordinate business operations:

Controller
    ↓
Service
    ↓
Database

we can use a request/handler model:

Controller
    ↓
MediatR
    ↓
Command Handler
    ↓
Business Logic
    ↓
Database

For example:

public record CreateOrderCommand(
    int CustomerId,
    decimal Amount
) : IRequest<int>;

The handler processes the command:

public class CreateOrderHandler
    : IRequestHandler<CreateOrderCommand, int>
{
    public async Task<int> Handle(
        CreateOrderCommand request,
        CancellationToken cancellationToken)
    {
        // Validate business rules
        // Create order
        // Save order

        return orderId;
    }
}

MediatR also provides a clean place for application-level cross-cutting concerns such as:

Validation
Logging
Performance measurement
Authorization
Transaction behavior

The important point is:

MediatR is not the message broker.

It helps with in-process application decoupling.

Azure Service Bus handles distributed messaging between processes or services.

That distinction becomes important as the system grows.

Why Azure Service Bus?

After the business operation is committed, an event such as OrderCreated needs to be delivered to downstream consumers.

With the Outbox Pattern, the event is first persisted as part of the same database transaction and is then published asynchronously.

For example:

{
  "eventType": "OrderCreated",
  "orderId": 12345,
  "customerId": 1001
}

The resulting flow becomes:

Order Service
     ↓
Outbox
     ↓
Outbox Processor
     ↓
Azure Service Bus
     ↓
Notification Consumers

Azure Service Bus provides the messaging infrastructure between the producer and consumers.

Instead of:

Order Service
     ↓
Notification Service

we have:

Order Service
     ↓
Outbox
     ↓
Azure Service Bus
     ↓
Notification Consumers

This provides several benefits.

1. Loose Coupling

The producer doesn't need to know which consumers exist.

Today:

OrderCreated
    ↓
Email

Tomorrow:

OrderCreated
    ↓
Email
SMS
Analytics
Audit
Push Notification

The order-processing logic doesn't need to change simply because another consumer was added.

2. Retry and Failure Handling

Azure Service Bus provides messaging and delivery mechanisms, while retry behavior is typically implemented through the Service Bus client and consumer/application logic.

Transient failures can therefore be handled without making the original business transaction depend on downstream notification delivery.

Messages that repeatedly fail processing can also be moved to a dead-letter queue for investigation or later recovery.

The exact retry strategy should be designed at the consumer level based on the type of failure.

For example:

Message
   ↓
Consumer
   ↓
Processing succeeds?
   ├── Yes → Complete message
   │
   └── No
       ↓
   Retry / Redelivery
       ↓
   Repeated failure?
       └── Dead-letter

3. Independent Scaling

The notification consumers can scale independently from the API.

For example:

API instances
     ↓
Outbox Processor
     ↓
Service Bus
     ↓
Notification Workers

If notification volume increases significantly, the consumer side can be scaled independently.

4. Future Integrations

The same event can potentially be consumed by additional systems without modifying the original producer.

This is particularly useful in larger enterprise environments.

Topics and Subscriptions

For multiple consumers, an Azure Service Bus Topic with multiple Subscriptions is a natural fit.

For example:

                  OrderCreated Event
                         │
                         ▼
                ┌─────────────────┐
                │ Azure Service   │
                │ Bus Topic       │
                └────────┬────────┘
                         │
             ┌───────────┼───────────┐
             │           │           │
             ▼           ▼           ▼
        Email Sub    SignalR Sub   Audit Sub
             │           │           │
             ▼           ▼           ▼
          Email       SignalR       Audit

Each subscription can receive its own copy of the message.

This keeps consumers independent.

It also means that one consumer can fail or be delayed without preventing another subscription from processing its own copy of the event.

SignalR for Real-Time Notifications

For browser-based real-time notifications, polling can introduce unnecessary latency and traffic.

SignalR allows the server to push messages to connected clients.

For example:

OrderCreated Event
        ↓
SignalR Consumer
        ↓
SignalR Hub
        ↓
Azure SignalR Service
        ↓
Connected Client

The client can receive something like:

"Order #12345 has been created successfully."

This works particularly well for:

Dashboards
Order tracking
Monitoring systems
Alerts
Chat-like applications
In-app notifications

A SignalR connection can also be associated with a user or group, allowing notifications to be targeted appropriately.

SignalR at Scale

A single SignalR server is straightforward.

The challenge appears when the application is deployed across multiple instances.

For example:

                       ┌──────────────────────┐
                       │   Azure SignalR      │
                       │      Service         │
                       └──────────┬───────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
                    ▼             ▼             ▼
               API Instance   API Instance   API Instance

For Azure-hosted applications, Azure SignalR Service can provide the scale-out layer for SignalR connections.

This allows application instances to remain focused on application processing while Azure SignalR Service manages persistent client connections.

The exact deployment model depends on application scale, hosting model, and operational requirements.

End-to-End Flow

Let's put everything together.

Step 1 — User performs an action

The user creates an order.

Client → POST /orders

Step 2 — API receives the request

The controller sends a command through MediatR.

Controller
    ↓
CreateOrderCommand
    ↓
MediatR

Step 3 — Command handler processes the business operation

The handler validates the request and creates the order.

The order and the corresponding outbox event are persisted in the same database transaction.

Database Transaction
       │
       ├── Order
       │
       └── Outbox Event

This is important because it prevents the application from successfully committing the order while completely losing the event because of a separate publish operation.

Step 4 — Outbox processor publishes the event

A background process reads unpublished events from the outbox and publishes them to Azure Service Bus.

Database
   ↓
Outbox Processor
   ↓
Azure Service Bus Topic

The business transaction does not wait for the downstream consumers to finish.

Step 5 — Consumers process the event

Different consumers can react independently.

                 OrderCreated
                      ↓
              Azure Service Bus
                 /     |      \
                /      |       \
               ▼       ▼        ▼
            Email   SignalR    Audit

Step 6 — Real-time update reaches the client

The SignalR consumer sends an update to the appropriate connected client.

Service Bus
     ↓
SignalR Consumer
     ↓
SignalR Hub
     ↓
Azure SignalR Service
     ↓
Browser / Mobile

The key principle is:

Order creation should not depend on notification delivery succeeding.

One Important Production Consideration: The Outbox Pattern

There is a subtle issue with a simpler implementation.

Consider this sequence:

1. Save Order
2. Publish OrderCreated

What happens if step 1 succeeds but step 2 fails?

The order exists in the database, but the event was never published.

This is a classic dual-write problem.

For production systems where reliable event publishing is important, an Outbox Pattern can help.

Instead of:

Save Order
     ↓
Publish Event

we persist both the business data and the outgoing event in the same database transaction:

Database Transaction
       │
       ├── Order
       │
       └── Outbox Event

A background worker then reads the outbox and publishes events to Service Bus:

Database
   ↓
Outbox Processor
   ↓
Azure Service Bus
   ↓
Consumers

This separates the critical business transaction from downstream message delivery while preserving the event that needs to be published.

Handling Duplicate Messages

Messaging systems should generally be designed with the assumption that a message can potentially be delivered more than once.

Azure Service Bus commonly uses at-least-once delivery semantics with Peek-Lock processing, so consumers should be designed to handle duplicate delivery safely.

That means consumers should ideally be idempotent.

For example:

Message ID: 8f23...

The consumer can maintain a record of processed message IDs.

If the same message arrives again:

Message
   ↓
Already processed?
   ├── Yes → Ignore / safely return
   └── No  → Process

This becomes especially important when processing operations such as:

Sending emails
Updating notification state
Creating records
Calling external APIs

Azure Service Bus also provides duplicate detection capabilities, but duplicate detection should not be treated as a replacement for idempotent consumer design.

Trade-Offs

This architecture is not free.

You are introducing additional infrastructure:

Azure Service Bus
Outbox storage
Background consumers
SignalR / Azure SignalR Service
Monitoring
Retry handling
Dead-letter handling
Distributed tracing

There is also eventual consistency.

For example:

Order Created
      ↓
Outbox Event
      ↓
Event Published
      ↓
Consumer Processes Event
      ↓
Notification Appears

The notification might appear milliseconds or seconds after the business operation.

But that trade-off can be worthwhile when the system needs:

Scalability
Resilience
Independent consumers
Extensibility
Loose coupling

The architecture should still be evaluated against the actual requirements.

A small application with one notification channel may not need all of these components.

Where This Architecture Works Well

This pattern can be useful in systems such as:

E-commerce

OrderPlaced
    ↓
Email
Inventory
Payment
Shipping
Customer Notification

Banking

TransactionCompleted
    ↓
SMS
Email
Mobile Push
Audit
Fraud Monitoring

Monitoring Platforms

AlertRaised
    ↓
Dashboard
Email
SMS
Incident Management

Enterprise Applications

Any system where a business event may need to trigger multiple independent downstream actions can benefit from this approach.

Key Design Principles

The technology is important, but the architectural principles matter more.

MediatR

Use it for in-process application decoupling.

Azure Service Bus

Use it for asynchronous communication between distributed components.

Azure Service Bus Topics and Subscriptions

Use them when multiple independent consumers need to react to the same event.

SignalR

Use it for real-time communication with connected clients.

Azure SignalR Service

Consider it when SignalR needs to scale across multiple application instances in Azure.

Outbox Pattern

Use it when you need stronger guarantees between database state and event publishing.

Idempotent Consumers

Design consumers so duplicate messages don't create unintended side effects.

Dead-Letter Handling

Treat repeatedly failed messages as operational data that needs monitoring, investigation, and potentially controlled replay.

Final Thoughts

Notifications are easy to implement when a system is small.

They become much more interesting when the application needs to scale, support multiple channels, handle failures, and evolve over time.

A useful separation is:

Business Logic
      ↓
Database Transaction
      ↓
Outbox Event
      ↓
Message Broker
      ↓
Independent Consumers
      ↓
Notification Channels

With this approach, the core business operation doesn't need to know whether the notification is delivered through email, SignalR, SMS, push notifications, or a future integration.

The result is an architecture that is more decoupled, scalable, resilient, and easier to evolve.

And perhaps the most important lesson:

Don't let notification delivery become part of your critical business transaction unless it truly needs to be.

If you've implemented a similar architecture, I'd be interested in hearing how you handled retries, ordering, duplicate messages, dead-letter queues, and the outbox problem.

dotnet #azure #systemdesign #microservices #softwarearchitecture #azureservicebus #signalr #mediatr #eventdrivenarchitecture

DEV Community: Chethan Ramaswamy

ASP.NET Core Authentication & Authorization Explained: What to Use, When, and How to Ship It Safely

1. Two questions, two jobs

2. The vocabulary, in plain English

3. How it fits together in ASP.NET Core

4. Pick your approach in 60 seconds

The single most important recommendation

5. Authentication mechanisms, one by one

5.1 Cookie authentication

5.2 ASP.NET Core Identity

5.3 JWT Bearer authentication

5.4 OpenID Connect (OIDC) and OAuth 2.0

5.5 The BFF pattern for SPAs (recommended)

5.6 Service-to-service: client credentials, managed identity, mTLS

5.7 API keys

5.8 Windows / Negotiate

5.9 Basic authentication

5.10 Combining multiple schemes

5.11 Passkeys (passwordless)

6. Authorization: a ladder, not a menu

Rung 0: Make "secure by default" your baseline

Rung 1: Simple [Authorize]

Rung 2: Roles (RBAC)

Rung 3: Claims and policies (your default workhorse)

Rung 4: Custom requirements and handlers

Rung 5: Resource-based authorization (the one people skip)

Rung 6: Permission-based authorization (fine-grained, at scale)

Rung 7: Attribute-based, multi-tenant, and external policy engines

Which rung do I need?

7. Reference architectures (what I would actually build)

8. A production-flavored API example

9. The production checklist

Transport and cookies

Data Protection (the #1 multi-instance bug)

Tokens

Secrets and keys

Account security (if you use Identity)

Abuse protection

Authorization hygiene

Observability

10. Test your access rules

11. Twelve mistakes I keep seeing in code reviews

12. Wrapping up

I Tested Building an Enterprise LLMOps Pipeline on Microsoft Azure. Here’s What Surprised Me.

LLMOps on Microsoft Azure: A Practical Guide to Foundry, RAG, Evaluation, and Guardrails

The core idea: MLOps is not LLMOps

Quick comparison

The architecture: how the Microsoft pieces fit together

The core players

Five gotchas that bite in production

1. Traditional unit tests break down

2. Pure vector search is rarely enough

3. API keys in app settings are a risk (and managed identity has its own trap)

4. Models get retired on a fixed clock

5. Costs creep up quietly

Production checklist

What's next

OWASP Top 10 for ASP.NET Core Web API: A Practical Security Guide

Introduction

Table of contents

Security foundations for an ASP.NET Core API

A01:2025 --- Broken Access Control

Vulnerable pattern

Safer approach: enforce access at the resource query

Practical controls

A02:2025 --- Security Misconfiguration

Common ASP.NET Core pitfalls

Configure CORS deliberately

Production configuration checklist

A03:2025 --- Software Supply Chain Failures

Reduce dependency risk

Practical controls

A04:2025 --- Cryptographic Failures

Common examples

Protect secrets outside source code

Practical controls

A05:2025 --- Injection

SQL injection: unsafe string concatenation

Prefer parameterized queries

Validate input as well

Rung 1: Simple `[Authorize]`