In legacy ASP.NET applications that use System.Web.Optimization, CssRewriteUrlTransform rewrites CSS URLs relative to each included stylesheet’s virtual directory. That helps keep relative assets such as images reachable after CSS is served through a bundle URL. It is not a built-in ASP.NET Core feature.
Why CSS asset paths can break after bundling
A relative CSS reference such as url(images/1.jpg) is normally interpreted in relation to the stylesheet that contains it. Once CSS is served through a bundle, the browser may instead resolve that reference against the bundle URL. The path can then point to the wrong directory.
Microsoft describes CssRewriteUrlTransform as rewriting URLs so assets remain available after bundling. Its API documentation says the transform uses the base directory of the included stylesheet’s virtual path—not the bundle’s virtual URL—to make URLs absolute. See the Microsoft Learn class reference and Process method reference.
How the transform resolves a relative URL
Microsoft’s example includes ~/content/some.css and rewrites url(images/1.jpg) to url(/content/images/1.jpg). The stylesheet’s virtual directory, /content/, supplies the base path. When diagnosing a URL, start with the included CSS file’s virtual path rather than the bundle path.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match#1 Best Overall
Registering a legacy CSS bundle
A bundle has its own virtual path and includes one or more virtual file paths. A basic registration can look like this:
bundles.Add(new Bundle("~/content/styles").Include(
"~/content/styles/site.css",
"~/content/styles/theme.css"));To attach the URL transform to an included stylesheet, the configuration can use an item transform, as in this pattern:
Rank #2
bundles.Add(new Bundle("~/content/styles/site")
.Include("~/content/styles/site.css", new CssRewriteUrlTransform()));The class implements IItemTransform and processes each stylesheet using its included virtual path. Check the exact Include overload supported by the System.Web.Optimization package version in your project; the cited API references do not establish every version-specific overload. Microsoft’s bundling and minification guidance also shows bundle registration and rendering a registered bundle with Styles.Render.
Check whether optimization is enabled
BundleTable.EnableOptimizations controls whether bundling and minification of bundle references are enabled. A path failure that occurs only when optimized assets are served should be reproduced under the same optimization setting as the affected environment. Consult the Microsoft Learn property reference for the setting.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsTroubleshoot a broken CSS URL
- Find the included stylesheet. Record the exact virtual path registered in the bundle.
- Inspect the failing CSS reference. Identify the
url(...)value and whether it is relative, root-relative, absolute, or another form. - Resolve ordinary relative paths from the stylesheet directory. For example, a stylesheet at
/content/site.csswithurl(images/1.jpg)corresponds to/content/images/1.jpgin Microsoft’s documented example. - Inspect the emitted CSS. Confirm the rewritten URL points to the asset’s actual location under the application’s deployment path.
- Verify the pipeline and environment. Confirm the transform is attached to the CSS item in the legacy bundle configuration and that optimization is enabled where the issue occurs.
For a virtual application root, custom routing, or proxy setup, check the URL emitted in that deployment. The API example establishes the ordinary relative-path behavior, not every hosting configuration or every URL form.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Does this apply to ASP.NET Core?
No—not as a built-in ASP.NET Core transform. CssRewriteUrlTransform belongs to the legacy System.Web.Optimization API and assembly. Microsoft’s ASP.NET Core bundling and minification guidance says the framework does not provide a native bundling and minification solution and describes third-party tooling, including Gulp and Webpack. Identify the application’s asset pipeline before applying legacy MVC or Web Forms examples to a Core project.
Quick Recap
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
