Exploring .NET MAUI 9: HybridWebView Features

.NET MAUI 9 is the next major version of the cross-platform application UI framework. An article detailing the significant features of this version has already been published and can be accessed here.

This release features two prominent enhancements:

• HybridWebView
• TitleBar for Windows

The TitleBar support for MacCatalyst is in progress. Track here.

This article will delve into the details of HybridWebView.

When it comes to app development, there’re three options:

• Native App
  • Swift for iOS
  • Java/Kotlin for Android
• Cross-platform App
  • .NET MAUI
  • Flutter
• Web App
  • Blazor
  • Angular
  • React

Within the domain of cross-platform apps, a specific sub-category is acknowledged, referred to as Hybrid App development, which employs Web components within the cross-platform framework.

Blazor Hybrid represents an exemplary case wherein Blazor components are rendered within the .NET MAUI app using the BlazorWebView.

Following the extensive reach of the Blazor Hybrid approach, the MAUI team has introduced a new control named HybridWebView, which enables the integration of JS components within the .NET MAUI app.

The primary advantage of this Hybrid approach lies in the reuse of both code and skills. The components can be reused within a Web app and the same team can develop the mobile app as well.

Contemporary JavaScript frameworks are predominantly utilized in the creation of single-page applications (SPAs), as they eliminate the need for page refresh and enable dynamic content updates through direct manipulation of the DOM.

This new HybridWebView, similar to BlazorWebView, utilizes the underlying Web engine of the OS platform to render these components.

Due to the static nature of JavaScript components, they can be served directly, necessitating only a web engine for processing. It is essential to include the necessary assets for this HybridWebView within a subfolder in the Resources\Raw directory, which is specifically designated for the static assets of the MAUI app. The artifacts from this folder are served as it is.

The name of the subfolder constitutes the value assigned to the HybridRoot property.

Similar to the Main method in C-style programming languages, an HTML page must be specified for the initial rendering of the View – Specified with the DefaultFile property.

The definition of HybridWebView is articulated as follows:

<HybridWebView
    x:Name="hwv"
    DefaultFile="index.html"
    HybridRoot="wwwroot"
    RawMessageReceived="OnRawMessageReceived" />

A name has been defined for the view and an event (RawMessageReceived) wired up, which will be elucidated further in this article.

Since these represent the default values of DefaultFile and HybridRoot properties, they may also be omitted.

Messaging:

Messages can be transmitted from .NET to JavaScript and conversely.

From .NET to JS:

From .NET, invoke the SendRawMessage() method on the instance of the HybridWebView object with the message as a string parameter.

hwv.SendRawMessage("Hello from .NET MAUI!!!");

On the JS side, it is necessary to register for the HybridWebViewMessageReceived event to receive the message as an argument of the event.

window.addEventListener("HybridWebViewMessageReceived", function(e) {
    // Access the message from the event argument
    // e.detail.message
});

From JS to .NET:

From JS, invoke the SendRawMessage() method, providing the message as a string parameter on the HybridWebView JS object.

// From script
window.HybridWebView.SendRawMessage('Hello from JS!!!');

To receive the message on the .NET side, wire up the RawMessageReceived event on the HybridWebView object.

// Event handler - C#
private async void OnRawMessageReceived(object sender, HybridWebViewRawMessageReceivedEventArgs e)
{
    // Event argument holds the message
    await DisplayAlert("Raw Message Received", e.Message, "OK");
}

JS Interop:

JS methods can be invoked from .NET using the InvokeJavaScriptAsync() method on the instance of the HybridWebView object with the parameters too.

To send input parameters and retrieve return values, it is essential to perform proper JSON encoding, which depends on the Source Generator. The model type should inherit from JsonSerializerContext, be defined as partial, and be adorned with the appropriate attributes; the Source Generator will do the necessary work.

Sample code:

// Defined in the script
function addNumbers(num1, num2) {
    return num1 + num2;
}

Model type:

using System.Text.Json.Serialization;

namespace HybridWebViewApp.Models;

[JsonSerializable(typeof(int))]
internal partial class IntContext : JsonSerializerContext;

Invocation:

// Refer to the sample for details
// Only the relevant portion is shown here
var result = await hwv.InvokeJavaScriptAsync<int>(
    "addNumbers", // JS method name
    IntContext.Default.Int32, // Return type
    [num1, num2], // Input parameters
    [IntContext.Default.Int32, IntContext.Default.Int32]); // Parameter types
await DisplayAlert("Result", $"{result}", "OK");

Output:

The Web DevTools can be accessed like that of a web browser for debugging purposes.

Project Template:

A new project template utilizing HybridWebView is now available in the .NET MAUI All-in-One Templates pack. For further info, please refer to this article.

Open Points:

• The core script required for the proper functioning of the HybridWebView must be manually integrated at this time.
  • Manual updates must be made whenever changes occur to the script
  • An issue has been documented regarding this matter – Track here
• The View will initiate with the default HTML file exclusively, without the option to directly navigate to a specific component.
  • There is a issue logged for this as well – Track here
• There is no provision to invoke the .NET method from JS
  • Work in progress – Track here – Addressed in .NET 9 GA release

Sample Project:

A functioning plain sample of the HybridWebView has been made available in my .NET MAUI Samples GitHub repository. Please refer to the src\NET_9\HybridWebViewApp folder for the source code.

Further Reading:

• HybridWebView

Happy coding. Stay connected as we continue to learn and share the experiences from this exciting journey of being a .NET developer.