Introduction

When a browser keeps serving an old JavaScript or CSS file after deployment, the usual cause is correct browser behavior combined with an incomplete cache-busting strategy. Static assets are intentionally cached aggressively, so if the URL does not change, many clients will keep the previous file.

The reliable fix is not to disable caching entirely. The better approach is to keep long-lived caching for assets and change the asset URL whenever the file content changes.

Why Cache Busting Works

Browsers cache by URL. If /css/site.css is cached for a week, deploying new contents to the same URL does not guarantee an immediate refresh. If the URL becomes /css/site.css?v=abc123, the browser treats it as a different resource and fetches it again.

The best version value is one derived from the file contents, not the current time. A content hash changes only when the file changes, which preserves browser caching for unchanged assets and avoids unnecessary downloads.

ASP.NET Core: Use asp-append-version

In ASP.NET Core, the simplest solution is the built-in Tag Helper:

<link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
<script src="~/js/app.js" asp-append-version="true"></script>

When rendered, ASP.NET Core appends a version query string based on the file contents. That gives you automatic cache busting without manual bookkeeping.

This works well with a standard caching policy: cache static assets for a long time, but keep HTML documents short-lived. The browser can reuse the fingerprinted asset until the content changes, then fetch the new version immediately after a deployment.

Classic ASP.NET MVC or Web Forms

If you are not on ASP.NET Core, you can still version the URL yourself. A common pattern is to append the file's last write timestamp or a hash:

1using System;
2using System.IO;
3using System.Web;
4using System.Web.Mvc;
5
6public static class AssetVersionExtensions
7{
8    public static string VersionedContent(this UrlHelper url, string virtualPath)
9    {
10        var absolutePath = HttpContext.Current.Server.MapPath(virtualPath);
11        var version = File.GetLastWriteTimeUtc(absolutePath).Ticks.ToString();
12        return url.Content($"{virtualPath}?v={version}");
13    }
14}

Then use it in Razor:

<link rel="stylesheet" href="@Url.VersionedContent("~/Content/site.css")" />
<script src="@Url.VersionedContent("~/Scripts/app.js")"></script>

This is not as strong as a real content hash, but it is a practical upgrade over hardcoded asset paths.

Pair URL Versioning With Cache Headers

Versioned URLs work best when your cache headers match the strategy. Static files with fingerprinted URLs can usually be cached for a long time because the URL changes on deployment. HTML pages are different because they need to reference the newest asset URLs.

In ASP.NET Core, you can configure static file caching explicitly:

1using Microsoft.AspNetCore.Builder;
2using Microsoft.Extensions.DependencyInjection;
3using Microsoft.Net.Http.Headers;
4using System;
5
6var builder = WebApplication.CreateBuilder(args);
7var app = builder.Build();
8
9app.UseStaticFiles(new StaticFileOptions
10{
11    OnPrepareResponse = ctx =>
12    {
13        ctx.Context.Response.Headers[HeaderNames.CacheControl] =
14            "public,max-age=" + TimeSpan.FromDays(30).TotalSeconds;
15    }
16});
17
18app.Run();

The important point is architectural: fingerprinted assets can be cached aggressively, while the HTML that references them should be refreshed more frequently.

Common Pitfalls

The most common mistake is appending the current time on every request. That forces a cache miss even when the file did not change, which removes the performance benefit of caching.

Another problem is versioning CSS and JavaScript but forgetting about bundles, CDN edges, or service workers. If another layer serves stale files, changing the query string in Razor alone may not be enough.

Developers also sometimes disable all browser caching to fix one deployment bug. That works, but it is a poor tradeoff for production traffic. Prefer deterministic versioned URLs and targeted cache headers instead of global no-cache behavior.

Summary

• Browsers cache static assets by URL, so changing file content alone is not enough to force a refresh.
• Prefer content-based versioning, such as asp-append-version, over timestamps generated on every request.
• In older ASP.NET apps, append a stable version value to the asset URL yourself.
• Keep HTML relatively fresh and allow fingerprinted CSS and JavaScript files to be cached aggressively.