Getting started with the Blazor PDF Viewer in WSL mode

17 Jul 20264 minutes to read

Follow these steps to set up Windows Subsystem for Linux (WSL), install the .NET SDK, and run the Blazor PDF Viewer (Next-Gen) component in WSL mode.

Prerequisites

Step 1: Enable Windows Subsystem for Linux and Virtual Machine Platform

To enable Windows Subsystem for Linux (WSL) and the Virtual Machine Platform on Windows:

  1. Open the Start menu and search for Control Panel. Select Programs and Features, then choose Turn Windows features on or off.
  2. Select Windows Subsystem for Linux and Virtual Machine Platform. Click OK and restart the computer.
  3. After restart, open a PowerShell prompt as Administrator and run the following command to set WSL 2 as the default architecture:
    wsl --set-default-version 2

The Windows Features dialog should show the WSL and Virtual Machine Platform options enabled:

Windows Features dialog with WSL and Virtual Machine Platform enabled

For more details, see the official Microsoft guide: Install WSL.

Step 2: Install Ubuntu

To install Ubuntu from the Microsoft Store:

  1. Open the Microsoft Store and search for Ubuntu. Select the latest LTS release (22.04 or 24.04).
  2. Choose Get to download and install, then select Launch to start Ubuntu.
  3. On first launch, create a new Ubuntu user by providing a username and password.
  4. From a Windows PowerShell prompt, set Ubuntu as the default WSL distribution:
    wsl -s Ubuntu

Ubuntu install page in Microsoft Store

Ubuntu first-run prompt for username and password

Step 3: Install the .NET SDK inside WSL

Open the Ubuntu terminal and run the following commands one by one to add the Microsoft package feed and install the .NET SDK on Ubuntu 22.04:

    wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb
    rm packages-microsoft-prod.deb
    sudo apt-get update && \
    sudo apt-get install -y dotnet-sdk-8.0

For Ubuntu 24.04, replace 22.04 in the wget URL with 24.04. To target .NET 9 instead, replace dotnet-sdk-8.0 with dotnet-sdk-9.0.

Verify the installation:

    dotnet --info

The output should resemble the following:

dotnet --info output in Ubuntu

Troubleshooting installation

If dotnet --info does not list the installed SDK, remove any conflicting packages and reinstall:

    sudo apt remove dotnet*
    sudo apt remove aspnetcore*
    sudo apt remove netstandard*
    sudo apt-get remove dotnet-host
    sudo apt autoremove
    sudo apt-get update
    sudo apt-get install -y dotnet-sdk-8.0
    dotnet --info

Step 4: Create the Blazor PDF Viewer project and run it in WSL

NOTE: Replace the project name BlazorPdfViewerApp with the name of your actual sample or solution.

From the Ubuntu terminal, create a new Blazor app, add the Syncfusion NuGet feed, and restore the dependencies:

    dotnet new blazorserver -n BlazorPdfViewerApp
    cd BlazorPdfViewerApp
    dotnet add package Syncfusion.Blazor.PdfViewerServer
    dotnet restore

Open the project in Visual Studio Code from inside WSL (run code . from the Ubuntu terminal) so the integrated terminal and debugger attach to the Linux context. Build and run the project:

    dotnet run

The Blazor PDF Viewer component should load in the browser:

Blazor app running in WSL mode

NOTE

If any issues occur while running in WSL mode, use the following instructions to resolve them.

If the sample does not load the PDF file and an exception is thrown:

Exception shown when PDF fails to load

In the Ubuntu terminal, run the following commands one by one to install the required Blazor PDF Viewer dependencies for Linux:

    sudo apt-get install libfontconfig1
    sudo apt-get update && apt-get install -y --allow-unauthenticated libgdiplus libc6-dev libx11-dev
    sudo apt-get update
    sudo apt install libgdiplus

Close the project, reopen it, and run it in WSL mode. It should run properly.

Blazor PDF Viewer running successfully in WSL mode

See also