Getting Started with .NET MAUI Blazor Application
29 Apr 20237 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
- Launch Visual Studio 2022 (Preview), and in the start window click Create a new project to create a new project:
- For .NET MAUI Blazor app, choose the .NET MAUI Blazor app template. Select Next.
- In the Configure your new project window, name your project, choose a location for the project and click the
Create
button.
- Wait for the project to be created, and its dependencies to be restored, then the project structure looks like below.
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.
<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 Packages in the App
Syncfusion Blazor components are available in nuget.org. In order to use Syncfusion Blazor components in the application, add reference to the corresponding NuGet. Refer to NuGet packages topic for available NuGet packages list with component details and Benefits of using individual NuGet packages.
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 for Syncfusion.Blazor.Calendars and then install it.
Register Syncfusion Blazor Service
Open ~/Imports.razor
file and add Syncfusion.Blazor namespace.
@using Syncfusion.Blazor
Now, register the Syncfusion Blazor service in the MAUI Blazor App. Here, Syncfusion Blazor Service is registered by setting the IgnoreScriptIsolation property as true
using AddSyncfusionBlazor
service method in ~/MauiProgram.cs
file as follows,
NOTE
From 2022 Vol1 (20.1) version - The default value of
IgnoreScriptIsolation
is changed astrue
, so, you don’t have to setIgnoreScriptIsolation
property explicitly to refer scripts externally.
using Syncfusion.Blazor;
public static class MauiProgram
{
public static Maui CreateMauiApp()
{
...
builder.Services.AddSyncfusionBlazor();
}
}
Add style sheet
Checkout the Blazor Themes topic to learn different ways to refer themes in the application, and to have the expected appearance for Syncfusion Blazor components. Here, the theme is referred using Static Web Assets.
To add theme to the app, open the NuGet package manager in Visual Studio (Tools → NuGet Package Manager → Manage NuGet Packages for Solution), search for Syncfusion.Blazor.Themes and then install it. Then, theme stylesheet from NuGet can be referred inside the <head>
of wwwroot/index.html file in the application as follows,
<head>
....
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
</head>
Add script reference
Checkout Adding Script Reference topic to learn different ways to add script reference in Blazor Application. In this getting started walk-through, the required scripts are referred using Static Web Assets externally inside the <head>
of 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
Syncfusion recommends to reference scripts using Static Web Assets, CDN and CRG by disabling JavaScript isolation for better loading performance of the 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.
@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
.
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.
<img src="images/welcome_picture.png" height="60" width="60" />
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.
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:
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.
See also
MAUI Blazor Diagram
NOTE