docs.sheetjs.com/docz/docs/03-demos/02-frontend/09-blazor.md

title	sidebar_label	pagination_prev	pagination_next	sidebar_position
Sheets in Blazor Sites	Blazor	demos/index	demos/grid/index	9

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

Blazor is a framework for building user interfaces using C#, HTML, JS and CSS.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

This demo uses Blazor and SheetJS to process and generate spreadsheets. We'll explore how to load SheetJS in Razor components and compare common state models and data flow strategies.

:::caution Blazor support is considered experimental.

Great open source software grows with user tests and reports. Any issues should be reported to the Blazor project for further diagnosis.

:::

:::danger Telemetry

The dotnet command embeds telemetry.

The DOTNET_CLI_TELEMETRY_OPTOUT environment variable should be set to 1.

"Platform Configuration" includes instructions for setting the environment variable on supported platforms.

:::

Integration Details

Installation

The SheetJS library can be loaded when the page is loaded or imported whenever the library functionality is used.

Standalone Script

The SheetJS Standalone scripts can be loaded in the root HTML page (typically wwwroot/index.html):

{`\

`}

ECMAScript Module

The SheetJS ECMAScript module script can be dynamically imported from functions. This ensures the library is only loaded when necessary. The following example loads the library and returns a Promise that resolves to the version string:

{\ async function sheetjs_version(id) { /* dynamically import the script in the event listener */ // highlight-next-line const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs"); \n\ /* use the library */ return XLSX.version; }}

Calling JS from C#

Setup

The primary mechanism for invoking JS functions from Blazor is IJSRuntime¹. It should be injected at the top of relevant Razor component scripts:

@inject IJSRuntime JS

Fire and Forget

When exporting a file with the SheetJS writeFile method², browser APIs do not provide success or error feedback. As a result, this demo invokes functions using the InvokeVoidAsync static method³:

private async Task ExportDataset() {
    await JS.InvokeVoidAsync("export_method", data);
}

Methods are commonly bound to buttons in the Razor template using @onclick:

<button @onclick="ExportDataset">Export Dataset</button>

State in Blazor

The example presidents sheet has one header row with "Name" and "Index" columns.

C# Representation

The natural C# representation of a single row is a class object:

public class President {
  public string Name { get; set; }
  public int Index { get; set; }
}

var PrezClinton = new President() { Name = "Bill Clinton", Index = 42 };

The entire dataset is typically stored in an array of class objects:

private President[] data;

Data Interchange

InvokeVoidAsync can pass data from the C# state to a JS function:

    await JS.InvokeVoidAsync("export_method", data);

Each row in the dataset will be passed as a separate argument to the JavaScript method, so the JavaScript code should collect the arguments:

/* NOTE: blazor spreads the C# array, so the ... spread syntax is required */
async function export_method(...rows) {
  /* display the array of objects */
  console.log(rows);
}

Each row is a simple JavaScript object.

:::caution pass

Blazor automatically spreads arrays. Each row is passed as a separate argument to the JavaScript method.

The example method uses the JavaScript spread syntax to collect the arguments.

:::

Exporting Data

With the collected array of objects, the SheetJS json_to_sheet method⁴ will generate a SheetJS worksheet⁵ from the dataset. After creating a workbook⁶ object with the book_new method⁷, the file is written with writeFile²:

{\ /* NOTE: blazor spreads the C# array, so the spread is required */ async function export_method(...rows) { const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs"); const ws = XLSX.utils.json_to_sheet(rows); const wb = XLSX.utils.book_new(ws, "Data"); XLSX.writeFile(wb, "SheetJSBlazor.xlsx"); }}

HTML Tables

When displaying datasets, Razor components typically generate HTML tables:

<table class="table" id="weather-table">
  <thead>
    <tr><th>Date</th><th>Temp. (C)</th><th>Temp. (F)</th><th>Summary</th></tr>
  </thead>
  <tbody>
    @foreach (var forecast in forecasts)
    {
      <tr>
        <td>@forecast.Date.ToShortDateString()</td>
        <td>@forecast.TemperatureC</td>
        <td>@forecast.TemperatureF</td>
        <td>@forecast.Summary</td>
      </tr>
    }
  </tbody>
</table>

If it has an id, JS code on the frontend can find the table element using the document.getElementById DOM method. A SheetJS workbook object can be generated using the table_to_book method⁸ and exported with writeFile²:

{\ /* NOTE: blazor spreads the C# array, so the spread is required */ async function export_method() { const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs"); const wb = XLSX.utils.table_to_book(document.getElementById("weather-table")); XLSX.writeFile(wb, "SheetJSBlazor.xlsx"); }}

This approach uses data that already exists in the document, so no additional data is passed from C# to JavaScript.

Complete Demo

The Blazor + WASM starter app includes a "Weather" component that displays data from a C#-managed dataset. This demo uses SheetJS to export data in two ways:

• "Export Dataset" will send row objects from the underlying C# data store to the frontend. The SheetJS json_to_sheet method⁴ builds the worksheet.

• "Export HTML Table" will scrape the table using the SheetJS table_to_book method⁸. No extra data will be sent to the frontend.

:::note Tested Deployments

This demo was tested in the following deployments:

Architecture	Date
darwin-arm	2024-10-15

:::

Platform Configuration

0. Set the DOTNET_CLI_TELEMETRY_OPTOUT environment variable to 1.

How to disable telemetry (click to hide)

Add the following line to .profile, .bashrc and .zshrc:

export DOTNET_CLI_TELEMETRY_OPTOUT=1

Close and restart the Terminal to load the changes.

Type env in the search bar and select "Edit the system environment variables".

In the new window, click the "Environment Variables..." button.

In the new window, look for the "System variables" section and click "New..."

Set the "Variable name" to DOTNET_CLI_TELEMETRY_OPTOUT and the value to 1.

Click "OK" in each window (3 windows) and restart your computer.

1. Install .NET

Installation Notes (click to show)

For macOS x64 and ARM64, install the dotnet-sdk Cask with Homebrew:

brew install --cask dotnet-sdk

For Steam Deck Holo and other Arch Linux x64 distributions, the dotnet-sdk and dotnet-runtime packages should be installed using pacman:

sudo pacman -Syu dotnet-sdk dotnet-runtime

https://dotnet.microsoft.com/en-us/download/dotnet/6.0 is the official source for Windows and ARM64 Linux versions.

2. Open a new Terminal window in macOS or PowerShell window in Windows.

App Creation

3. Create a new blazorwasm app:

dotnet new blazorwasm -o SheetJSBlazorWasm
cd SheetJSBlazorWasm
dotnet run

When the Blazor service runs, the terminal will display a URL:

info: Microsoft.Hosting.Lifetime[14]
// highlight-next-line
      Now listening on: http://localhost:6969

4. In a new browser window, open the displayed URL from Step 3.

5. Click the "Weather" link and confirm the page includes a data table.

6. Stop the server (press CTRL+C in the terminal window).

SheetJS Integration

7. Add the following script tag to wwwroot/index.html in the HEAD block:

{`\

`}

8. Inject the IJSRuntime dependency near the top of Pages/Weather.razor:

@page "/weather"
@inject HttpClient Http
// highlight-next-line
@inject IJSRuntime JS

9. Add an ID to the TABLE element in Pages/Weather.razor:

{
    <!-- highlight-next-line -->
    <table class="table" id="weather-table">
        <thead>
            <tr>

10. Add callbacks to the @code section in Pages/Weather.razor:

    private async Task ExportDataset()
    {
        await JS.InvokeVoidAsync("export_dataset", forecasts);
    }

    private async Task ExportHTML()
    {
        await JS.InvokeVoidAsync("export_html", "weather-table");
    }

11. Add Export buttons to the template in Pages/Weather.razor:

<p>This component demonstrates fetching data from the server.</p>

<!-- highlight-start -->
<button @onclick="ExportDataset">Export Dataset</button>
<button @onclick="ExportHTML">Export HTML TABLE</button>
<!-- highlight-end -->

Testing

12. Launch the dotnet process again:

dotnet run

When the Blazor service runs, the terminal will display a URL:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:6969

13. In a new browser window, open the displayed URL from Step 12.

14. Click the "Weather" link. The page should match the following screenshot:

15. Click the "Export Dataset" button and save the generated file to SheetJSBlazorDataset.xlsx. Open the file in a spreadsheet editor and confirm the data matches the table. The column labels will differ since the underlying dataset uses different labels.

16. Click the "Export HTML TABLE" button and save the generated file to SheetJSBlazorHTML.xlsx. Open the file in a spreadsheet editor and confirm the data matches the table. The column labels will match the HTML table.

:::note pass

It is somewhat curious that the official dotnet Blazor sample dataset marks 1 C and -13 C as "freezing" but marks -2 C as "chilly". It stands to reason that -2 C should also be freezing.

:::

---

1. See "Microsoft.JSInterop.IJSRuntime" in the dotnet documentation. ↩︎

2. See writeFile in "Writing Files" ↩︎

3. See "Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync" in the dotnet documentation. ↩︎

4. See json_to_sheet in "Utilities" ↩︎

5. See "Sheet Objects" ↩︎

6. See "Workbook Object" ↩︎

7. See book_new in "Utilities" ↩︎

8. See table_to_book in "HTML" Utilities ↩︎