Upgrade Syncfusion® Blazor components to the latest version

22 Oct 20252 minutes to read

Use the following checklist to upgrade Syncfusion® Blazor components safely and consistently.

Compatible .NET version

Syncfusion® Blazor components in the latest version '{:nuget-version:}' are compatible with the latest version of .NET 8.0 or .NET 9.0. Also, refer to version compatibility documentation for more information about version compatibility of Syncfusion® Blazor components and .NET SDK.

Client resource file references

Ensure CSS resources are correctly referenced in the application.

  • Add the following style reference in the appropriate file based on the hosting model: in ~/Components/App.razor for Blazor Web App, in ~/Pages/_Host.cshtml for Blazor Server App, or in ~/wwwroot/index.html for Blazor WebAssembly App.

    If using the Syncfusion.Blazor NuGet package, include the following reference:

      <link href="_content/Syncfusion.Blazor/styles/bootstrap4.css" rel="stylesheet" />

    If using individual NuGet packages, include the following reference:

      <link href="_content/Syncfusion.Blazor.Themes/bootstrap4.css" rel="stylesheet" />

NOTE

Use a single theme file that matches the chosen look and feel (for example, Bootstrap 5, Material, Tailwind, or Fluent). Replace the file name in the reference with the corresponding theme (for example, bootstrap5.css, material.css, tailwind.css, or fluent.css) when applicable. For production builds or minimal bundles, generate custom styles for selected components using the Theme Studio web application at the following link: https://ej2.syncfusion.com/themestudio/.

Breaking changes

Review breaking changes for each release to understand required code or behavior updates. See the release notes (breaking changes).

Cache problem

Before restoring NuGet packages, clear older versions of Syncfusion® Blazor NuGet packages to avoid conflicts.

The following steps explain how to clean the cache:

  1. Delete the Syncfusion® Blazor NuGet packages from the installed location {System-driver}/Users/{user-name}/.nuget/packages/. In Windows, the installed location of Syncfusion® Blazor NuGet packages can be found using %userprofile%/.nuget/packages/.
  2. Update to the latest Syncfusion® Blazor NuGet packages.

Tip: The NuGet cache can also be cleared using the .NET CLI: run dotnet nuget locals all --clear in a terminal.

Linker.xml configuration

For Blazor WebAssembly applications, ensure that a Linker.xml (trimming configuration) file is configured when required. Missing this configuration can prevent Syncfusion® Blazor components from rendering.

Refer to this KB article for details on Linker.xml usage.

NOTE

Linker.xml configuration applies only to Blazor WebAssembly applications.

See Also