Getting Started with .NET MAUI Blazor Application

29 Jan 20246 minutes to read

This section explains how to create and run the first .NET Multi-platform Blazor App UI (.NET MAUI Blazor) app with Syncfusion Blazor components.

What is .NET MAUI Blazor App?

.NET MAUI Blazor App is a .NET MAUI App where Blazor web app is hosted in .NET MAUI app using BlazorWebView control. This enable a Blazor web app to be integrated with platform features and UI controls. Also, BlazorWebView can be added to any page of .NET MAUI app, and pointed to the root of the Blazor app. The Blazor components run natively in the .NET process and render web UI to an embedded web view control. .NET MAUI Blazor apps can run on all the platforms supported by .NET MAUI.

Visual Studio provides .NET MAUI Blazor app template to create .NET MAUI Blazor Apps.

Prerequisites

.NET SDK 6.0 (Latest .NET SDK 6.0.101 or above)
The latest preview of Visual Studio 2022 17.1 or above, with required workloads:
- Mobile development with .NET
- ASP.NET and web development

Create a new .NET MAUI Blazor App in Visual Studio

You can create a .NET MAUI Blazor App using Visual Studio via Microsoft Templates

BlazorWebView in .NET MAUI Blazor App

The above steps creates a multi-targeted .NET MAUI Blazor app that can be deployed to Android, iOS, macOS, and Windows.

In MainPage.xaml, The BlazorWebView is added and points to the root of the Blazor app. The root Blazor component for the app is in Main.razor, which Razor compiles into a type named Main in the application’s root namespace.

MainPage.xaml
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:b="clr-namespace:Microsoft.AspNetCore.Components.WebView.Maui;assembly=Microsoft.AspNetCore.Components.WebView.Maui"
             xmlns:local="clr-namespace:MauiApp1"
             x:Class="MauiApp1.MainPage"
             BackgroundColor="{DynamicResource PageBackgroundColor}">

    <b:BlazorWebView HostPage="wwwroot/index.html">
        <b:BlazorWebView.RootComponents>
            <b:RootComponent Selector="app" ComponentType="{x:Type local:Main}" />
        </b:BlazorWebView.RootComponents>
    </b:BlazorWebView>

</ContentPage>

For more details refer Create a .NET MAUI Blazor app topic. If you already have .NET MAUI app and want to convert use BlazorWebView, refer Add a BlazorWebView to an existing app topic.

Install Syncfusion Blazor Calendars and Themes NuGet in the App

Here’s an example of how to add Blazor Calendar component in the app, open the NuGet package manager in Visual Studio (Tools → NuGet Package Manager → Manage NuGet Packages for Solution), search and install Syncfusion.Blazor.Calendars and Syncfusion.Blazor.Themes. Alternatively, you can utilize the following package manager command to achieve the same.

Package Manager
Install-Package Syncfusion.Blazor.Calendars -Version 25.1.35
Install-Package Syncfusion.Blazor.Themes -Version 25.1.35

NOTE

Syncfusion Blazor components are available in nuget.org. Refer to NuGet packages topic for available NuGet packages list with component details.

Register Syncfusion Blazor Service

Open ~/_Imports.razor file and import the Syncfusion.Blazor and Syncfusion.Blazor.Calendars namespace.

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Calendars

Now, register the Syncfusion Blazor service in the MauiProgram.cs file of your MAUI Blazor App.

~/MauiProgram.cs
using Syncfusion.Blazor;
    ....
    builder.Services.AddSyncfusionBlazor();
    ....

Add stylesheet and script resources

The theme stylesheet and script can be accessed from NuGet through Static Web Assets. Reference the stylesheet and script in the <head> of the ~wwwroot/index.html file.

<head>
    ....
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

NOTE

Check out the Blazor Themes topic to discover various methods (Static Web Assets, CDN, and CRG) for referencing themes in your Blazor application. Also, check out the Adding Script Reference topic to learn different approaches for adding script references in your Blazor application.

Add Syncfusion Blazor component

Now add Syncfusion Blazor component in any razor file. Here, the Calendar component is added in ~/Pages/index.razor page under the ~/Pages folder.

RAZOR
@using Syncfusion.Blazor.Calendars

<SfCalendar TValue="DateTime"></SfCalendar>

In the Visual Studio toolbar, select the Windows Machine button to build and run the app.
Before running the sample, make sure the mode is Windows Machine.

Build and run MAUI Blazor App

NOTE

If you want to run the application in Android or iOS refer MAUI Getting Started for the setup.

NOTE

Download demo from GitHub

How to use images in .NET MAUI Blazor Application

Add the images in the images in the wwwroot folder of the application and refer it using img tag in Blazor App.

In the below code images are added under images folder in wwwroot folder.

RAZOR
<img src="images/welcome_picture.png" height="60" width="60" />

MAUI Blazor App with added image

Troubleshooting

How to solve deployment errors in Windows?

If you get error dialog like “There were deployment errors”, Enable developer mode. For more details refer Enable your device for development.

Enable developer mode in system settings

How to solve deployment errors in iOS?

In iOS code is statically compiled ahead of time, so, configure Syncfusion Blazor assemblies in MtouchExtraArgs tag for the iOS Release configuration in the project when deploy on a real device.

Below are possible errors if MtouchExtraArgs tag is not configured,

App won’t load on real device with error “An unhandled error has occurred” after you compile in Release mode with Visual Studio and deploy to real device.
AOT related failures like Attempting to JIT compile method while running in aot-only mode

<PropertyGroup Condition="$(TargetFramework.Contains('-ios')) And $(Configuration.Contains('Release')) ">
  <UseInterpreter>true</UseInterpreter>
  <MtouchExtraArgs>--linkskip=Syncfusion.Blazor.Themes --linkskip=Syncfusion.Blazor.Inputs</MtouchExtraArgs>
</PropertyGroup>

Reference:

Could not AOT the assembly of my App

How to solve “The project doesn’t know how to run the profile Windows Machine” while running MAUI Blazor App?

This issue has been fixed in most recent release of Visual Studio. For more details refer here.
You can also fix this error by installing Single-project MSIX Packaging Tools.