Skip to content

kb(Common): Add .NET 9 information to cache busting documentation #3175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 12, 2025
Merged

kb(Common): Add .NET 9 information to cache busting documentation #3175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8edb515
kb(Common): Add .NET 9 information to cache busting documentation
dimodi Aug 12, 2025
a2d60ca
Update knowledge-base/common-browser-cache-buster.md
dimodi Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 8 additions & 17 deletions getting-started/what-you-need.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,7 @@ There are a few other optional namespaces that may be needed often. You can impo

>caption _Imports.razor

<div class="skip-repl"></div>

````RAZOR
````RAZOR.skip-repl
@* required *@
@using Telerik.Blazor // set component parameters
@using Telerik.Blazor.Components // recognize components tags
Expand All @@ -113,9 +111,7 @@ To avoid the need to register Telerik namespaces in `.cs` files, use [`global us

>caption Program.cs or MauiProgram.cs

<div class="skip-repl"></div>

````CS
````C#.skip-repl
// required
global using Telerik.Blazor; // use component parameter values
global using Telerik.Blazor.Components; // use component types and instances
Expand All @@ -138,9 +134,7 @@ Register the Telerik service in all projects that use Telerik Blazor components.

>caption Program.cs or MauiProgram.cs

<div class="skip-repl"></div>

````CS
````C#.skip-repl
builder.Services.AddTelerikBlazor();
````

Expand All @@ -151,9 +145,10 @@ builder.Services.AddTelerikBlazor();

The Telerik UI for Blazor components require a [theme stylesheet](#css-theme) and a [JSInterop file](#javascript-file).

To use static CSS and JS assets from the NuGet package in a project, make sure that the project has [`app.UseStaticFiles();` in its `Program.cs`](https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-8.0&tabs=visual-studio#consume-content-from-a-referenced-rcl) file. This is true by default.
To use static CSS and JS assets from the NuGet package in a project, make sure that the [project allows it](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files), which is true by default. To [prevent browser caching of the Telerik static NuGet assets during version upgrades](slug:common-kb-browser-cache-buster):

You can also [add the Telerik UI for Blazor version number to the CSS and JavaScript file URLs to prevent browser caching during version upgrades](slug:common-kb-browser-cache-buster).
* In .NET 9 and later versions, you can use `MapStaticAssets()` in `Program.cs` and `@Assets["..."]` in `App.razor`.
* Add the Telerik UI for Blazor version number to the CSS and JavaScript file URLs.

### CSS Theme

Expand All @@ -163,9 +158,7 @@ Register the [Telerik font icon stylesheet](slug:common-features-icons#font-icon

>caption Adding the Telerik Blazor CSS files

<div class="skip-repl"></div>

````HTML
````HTML.skip-repl
<head>
<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css" />

Expand All @@ -191,9 +184,7 @@ The recommended way to register the Telerik Blazor JS file for better loading pe

>caption Adding the Telerik Blazor JavaScript file

<div class="skip-repl"></div>

````HTML
````HTML.skip-repl
<!DOCTYPE html>
<html>
<head>
Expand Down
22 changes: 19 additions & 3 deletions knowledge-base/common-browser-cache-buster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,27 @@ This KB article answers the following questions:

## Solution

To avoid browser caching issues when upgrading the Telerik UI for Blazor version, use the so-called cache busting. Add the components' version number to the Telerik client asset URLs as a query string. In this way, the browser will always load the correct version of the CSS stylesheet and the JSInterop file. Browsers will still use cached Telerik client assets as long as the components version stays the same.
To avoid browser caching issues when upgrading the Telerik UI for Blazor version, consider one of the following options:

* Serve the Telerik CSS and JS files through the so-called [Map Static Assets routing endpoint conventions](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/map-static-files) which requires:
* .NET 9 or later
* `app.MapStaticAssets();` in `Program.cs`
* [`@Assets["..."]` in `App.razor`](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files?view=aspnetcore-9.0#deliver-assets-with-map-static-assets-routing-endpoint-conventions)
* Use the so-called [cache busting](#cache-busting). Add the components' version number to the Telerik client asset URLs as a query string. In this way, the browser will always load the correct version of the CSS stylesheet and the JSInterop file. Browsers will still use cached Telerik client assets as long as the components version stays the same.

Using the correct client assets [avoids Telerik-related JavaScript errors](slug:troubleshooting-js-errors).

The required approach varies, depending on the Blazor application:
>caption Map Static Telerik Assets in .NET 9 or later

````RAZOR.skip-repl
<link href="@Assets["_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css"]" rel="stylesheet" />

<script src="@Assets["_content/Telerik.UI.for.Blazor/js/telerik-blazor.js"]"></script>
````

## Cache Busting

Cache busting varies depending on the Blazor application:

* [Blazor Web Apps and legacy Blazor Server apps](#blazor-web-apps-and-legacy-blazor-server-apps)
* [Standalone Blazor WebAssembly apps and Hybrid apps](#standalone-blazor-webassembly-apps-and-hybrid-apps)
Expand Down Expand Up @@ -80,7 +96,7 @@ If the Telerik CSS theme and JavaScript file reside in the `index.html` file, yo

## Notes

In addition to cache busting, you can [use a `defer` attribute to load the `telerik-blazor.js` file asynchronously](slug:getting-started/what-you-need#javascript-file) and improve the client-side app performance.
You can also [use a `defer` attribute to load the `telerik-blazor.js` file asynchronously](slug:getting-started/what-you-need#javascript-file) and improve the client-side app performance.

## See Also

Expand Down
Loading