Reference scripts in Blazor Application

30 Mar 2022 / 12 minutes to read

This section provides information about the script isolation process and how to reference scripts from CDN, Static Web Assets and Custom resource generator (CRG) for Syncfusion Blazor Components.

The javascript interop files needs to be added to support the features that can’t be implemented in native blazor.

CDN Reference

You can refer the Syncfusion Blazor scripts through the CDN resources.

From 2022 Vol1 (20.1) version, JavaScript isolation is marked as obsolete and disabled by default to refer scripts externally. Refer Disable JavaScript isolation topic to disable for earlier versions to refer scripts externally.

  • For Blazor WASM App, reference scripts in ~/wwwroot/index.html file.
  • For Blazor Server App, reference scripts in ~/Pages/_Layout.cshtml file for .NET 6 project and in ~/Pages/_Host.cshtml file for .NET 5 and .NET Core 3.X project.

Syncfusion Blazor components are available in CDN for each version. Make sure that the version in the URLs matches the version of the Syncfusion Blazor Package you are using.

Component CDN Script Reference
All components except PDF Viewer & Document Editor https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor.min.js
PDF Viewer https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor-pdfviewer.min.js
Document Editor https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor-documenteditor.min.js
<head>
    ....
    <script src="https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

If you are using PDFViewer or DocumentEditor, ensure to add additional script references as follows,

<head>
    ....
    <script src="https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor-pdfviewer.min.js" type="text/javascript"></script>
    <script src="https://cdn.syncfusion.com/blazor/20.1.55/syncfusion-blazor-documenteditor.min.js" type="text/javascript"></script>
</head>

In addition to above, Syncfusion Blazor components provides latest scripts in CDN without versioning. You can use this in development environment if you want to always use the latest version of scripts. It is not recommended to use this in production environment.

WARNING

The un-versioned CDN links which always maintains latest version scripts are deprecated from 2022 Vol1 - 20.1 version. These links are available with 19.4 version scripts to avoid breaking in sites and apps that uses un-versioned links.

Component CDN Script Reference
All components except PDF Viewer & Document Editor https://cdn.syncfusion.com/blazor/syncfusion-blazor.min.js
PDF Viewer https://cdn.syncfusion.com/blazor/syncfusion-blazor-pdfviewer.min.js
Document Editor https://cdn.syncfusion.com/blazor/syncfusion-blazor-documenteditor.min.js

Static web assets

You can refer the Syncfusion Blazor scripts through the NuGet package’s static web assets.

From 2022 Vol1 (20.1) version, JavaScript isolation is marked as obsolete and disabled by default to refer scripts externally. Refer Disable JavaScript isolation topic to disable for earlier versions to refer scripts externally.

Enable static web assets usage

To use static web assets, ensure UseStaticFiles method is called as follows,

  • For .NET 6 app, open the ~/Program.cs file and call UseStaticFiles method.
  • For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and call UseStaticFiles method.

For Blazor WASM App, call UseStaticFiles method in Server project of the above mentioned file.

Refer script from static web assets

  • If you are using Syncfusion Blazor individual NuGet package, the combined scripts available in Syncfusion.Blazor.Core package. To refer script from static web assets, use the code below.

      <head>
          ...
          <script  src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"  type="text/javascript"></script>
      </head>
  • If you’re using the PDF viewer or Document Editor component, use the code below to refer to script from static web assets.

      <head>
          ...
         <script  src="_content/Syncfusion.Blazor.PdfViewer/scripts/syncfusion-blazor-pdfviewer.min.js"  type="text/javascript"></script>
         <script  src="_content/Syncfusion.Blazor.WordProcessor/scripts/syncfusion-blazor-documenteditor.min.js"  type="text/javascript"></script>
      </head>
  • If you are using Syncfusion.Blazor NuGet package, use the code below to refer to script from static web assets.

    It is not recommended to use Syncfusion.Blazor NuGet for production environment. Use individual NuGet packages for production.

      <head>
          ...
          <script  src="_content/Syncfusion.Blazor/scripts/syncfusion-blazor.min.js"  type="text/javascript"></script>
      </head>

    The PDF Viewer and Document Editor component scripts are available in static web assets from 19.3.* version. If you are using PDF Viewer or Document Editor component with 19.2.* version, it automatically switch to the JavaScript isolation in the application end.

JavaScript isolation

Syncfusion Blazor components supports JavaScript isolation where the needed scripts are loaded by the component itself when its rendered. So, you don’t have to reference scripts externally in application.

Syncfusion recommends to reference scripts using Static Web Assets, CDN and CRG over JavaScript isolation approach for better loading performance of the blazor application.

From 2022 Vol1 (20.1) version version, JavaScript isolation is marked as obsolete and disabled by default. You can enable JavaScript isolation by following below steps,

Blazor Server App

  • For .NET 6 app, open the ~/Program.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation as false.

  • For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation as false.

using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });

var app = builder.Build();
....
using Syncfusion.Blazor;

namespace BlazorApplication
{
    public class Startup
    {
        ...
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddServerSideBlazor();
            services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
        }
        ...
    }
}

Blazor WASM App

For Blazor WebAssembly App, set IgnoreScriptIsolation property as false using AddSyncfusionBlazor service method in ~/Program.cs file.

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
await builder.Build().RunAsync();
....
using Syncfusion.Blazor;

namespace WebApplication1
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            ....
            builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
            await builder.Build().RunAsync();
        }
    }
}

Disable JavaScript isolation

From 2022 Vol1 (20.1) version version, JavaScript isolation is marked as obsolete and disabled by default. You don’t have to make below additional changes.

The Syncfusion Blazor components supports to refer scripts externally at the application-end by disabling default JavaScript isolation approach for better initial loading performance which explained in the previous section. You can disable JS isolation by setting IgnoreScriptIsolation as true while adding Syncfusion blazor service using AddSyncfusionBlazor().

Blazor Server App

  • For .NET 6 app, open the ~/Program.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation.

  • For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation.

using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });

var app = builder.Build();
....
using Syncfusion.Blazor;

namespace BlazorApplication
{
    public class Startup
    {
        ...
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddServerSideBlazor();
            services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
        }
        ...
    }
}

Blazor WASM App

For Blazor WebAssembly App, set IgnoreScriptIsolation property as true using AddSyncfusionBlazor service method in ~/Program.cs file.

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
await builder.Build().RunAsync();
....
using Syncfusion.Blazor;

namespace WebApplication1
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            ....
            builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
            await builder.Build().RunAsync();
        }
    }
}

If you set IgnoreScriptIsolation property as true, You need to reference scripts externally via Static Web Assets or CDN or and CRG.

Custom Resource Generator

The Syncfusion Blazor provides an option to generate a component’s interop scripts using the Custom Resource Generator (CRG) tool for the Blazor components. Refer here to generate the component-wise scripts externally using CRG.

See also