Bridging the Gap: MAUI Hybrid Mobile Development

In the dynamic world of mobile application development, finding the right tools that combine efficiency, flexibility, and robustness is an ongoing quest. While there are numerous mobile frameworks available in programming, the options become limited when focusing on JavaScript frameworks and hybrid applications. Developers often seek solutions that allow them to leverage modern JavaScript frameworks alongside native capabilities seamlessly.

Enter MAUI Hybridizer, a powerful library designed to integrate JavaScript applications with .NET MAUI, enabling developers to create dynamic, cross-platform hybrid mobile applications with ease.

The Need for Enhanced Hybrid Libraries

Building Upon Existing Solutions

There are several options for building hybrid applications using JavaScript frameworks. Tools like Capacitor and NativeScript have made significant contributions to hybrid mobile app development. They provide valuable features and have their own strengths:

• Capacitor offers broad platform support and a familiar web-based development approach.
• NativeScript allows developers to build native apps using JavaScript, TypeScript, or Angular, providing direct access to native APIs.

However, developers may encounter challenges such as:

• Plugin Development Complexity: Capacitor plugins often require knowledge of native languages like Java and Swift, which can be a barrier for those primarily experienced in web development.
• Support and Maintenance: NativeScript, while powerful, may suffer from a lack of active support and updates, potentially leading to challenges in developing and maintaining production-ready applications.

These considerations highlight the opportunity for a library that combines the strengths of existing solutions while addressing their limitations, providing a more streamlined and accessible development experience specifically for JavaScript frameworks and hybrid applications.

Introducing MAUI Hybridizer

Leveraging MAUI’s Rich Heritage

.NET Multi-platform App UI (MAUI) builds upon the strong foundation laid by Xamarin, offering a unified framework for creating native applications across multiple platforms, including Android, iOS, macOS, and Windows. This rich background means that MAUI has a plethora of APIs already implemented, providing access to native device features without the need for platform-specific code.

The Logic Behind the Library

MAUI Hybridizer serves as a bridge between the JavaScript application and the .NET MAUI framework. It enables two-way communication between the JavaScript and C# layers, allowing developers to call native APIs from JavaScript and vice versa. This is achieved through a hybrid web view that loads the JavaScript application and facilitates communication using a messaging system.

Seamless Plugin Integration

MAUI Hybridizer takes full advantage of MAUI’s extensive API set, allowing developers to use these existing implementations as plugins within the hybrid application. This not only accelerates development but also ensures that applications are built upon proven, stable technologies.

Key Features

• Two-Way Communication: Seamlessly invoke native C# methods from JavaScript and call JavaScript functions from C#.
• Plugin Architecture: Easily create and integrate custom plugins to extend the application’s functionality.
• Event Handling: Trigger and handle application lifecycle events, such as Resume and Stop, across both layers.

Creating a Plugin: A Step-by-Step Guide

One of the standout features of MAUI Hybridizer is the ability to create custom plugins, enabling developers to extend the application’s capabilities by tapping into native device features.

Step 1: Create a .NET MAUI Class Library

First, create a new .NET MAUI Class Library project. Ensure that you’re using a supported .NET version (less than 9, as Roslyn analyzers may not fully support .NET 9 yet).

dotnet new mauiclasslib -n MyCustomPlugin -f net8.0

Step 2: Add the AutoGen NuGet Package

Add the Allowed.Maui.Hybridizer.AutoGen package to your project:

dotnet add package Allowed.Maui.Hybridizer.AutoGen

Step 3: Implement the C# Plugin

Create your plugin class, using attributes to designate it as a plugin and its methods as invokable from JavaScript.

using System.Text.Json.Serialization;
using Allowed.Maui.Hybridizer.Abstractions.Attributes;
using Allowed.Maui.Hybridizer.Abstractions.Plugins;

namespace MyCustomPlugin;

[HwvPlugin]
public class StoragePlugin
{
    [HwvMethod]
    public GetResponse Get([HwvPayload] GetRequest request)
    {
        return new GetResponse(Preferences.Default.Get(request.Key, string.Empty));
    }

    [HwvMethod]
    public void Set([HwvPayload] SetRequest request)
    {
        Preferences.Default.Set(request.Key, request.Value);
    }

    [HwvMethod]
    public void Remove([HwvPayload] RemoveRequest request)
    {
        Preferences.Default.Remove(request.Key);
    }

    public record GetRequest([property: JsonPropertyName("key")] string Key);

    public record GetResponse([property: JsonPropertyName("value")] string Value);

    public record SetRequest(
        [property: JsonPropertyName("key")] string Key,
        [property: JsonPropertyName("value")] string Value);

    public record RemoveRequest([property: JsonPropertyName("key")] string Key);
}

Step 4: Register the Plugin with Dependency Injection

After implementing your plugin, you need to register it with the MAUI dependency injection container so that it can be recognized by Maui Hybridizer.

In your MauiProgram.cs, add the following code:

// Add the Hybridizer with plugin modules
builder.Services.AddHybridizer(
    Allowed.Maui.Hybridizer.Essentials.HwvPluginModule.Invoke, 
    MyCustomPlugin.HwvPluginModule.Invoke
);

// Add essentials plugins you need
builder.Services.RegisterAlertPlugin();
builder.Services.RegisterBatteryPlugin();
builder.Services.RegisterStoragePlugin();

// Add your custom plugin
builder.Services.AddTransient<CustomAlertPlugin>();

Note: HwvPluginModule is an autogenerated class created by the Allowed.Maui.Hybridizer.AutoGen package when you build your plugin. It contains method to register your plugin’s services.

Step 5: Initialize the Bridge Service

This step sets up the communication channel and should be done once in your JavaScript application, usually after the application is loaded.

import { bridgeService } from "../hybridizer/BridgeService";

// Initialize the bridge service for communication
if (!platformService.isWeb())
    bridgeService.initialize();

Step 6: Create the JavaScript Interface

In your JavaScript application, create an interface to communicate with the native plugin.

import { bridgeService } from "../hybridizer/BridgeService";
import { PlatformConstants } from "../hybridizer/PlatformConstants";
import { platformService } from "../hybridizer/PlatformService";

export class StoragePlugin {
  async get(key: string): Promise<GetResponse | undefined> {
    if (platformService.getPlatform() === PlatformConstants.Web) {
      return { value: localStorage.getItem(key) };
    } else {
      return await bridgeService.invoke<GetResponse>('Storage', 'Get', { key });
    }
  }

  async set(key: string, value: string): Promise<void> {
    if (platformService.getPlatform() === PlatformConstants.Web) {
      localStorage.setItem(key, value);
    } else {
      await bridgeService.invoke('Storage', 'Set', { key, value });
    }
  }

  async remove(key: string): Promise<void> {
    if (platformService.getPlatform() === PlatformConstants.Web) {
      localStorage.removeItem(key);
    } else {
      await bridgeService.invoke('Storage', 'Remove', { key });
    }
  }
}

export interface GetResponse {
  value?: string | null;
}

export const storagePlugin = new StoragePlugin();

Explanation

• Platform Check: Determines if the application is running on the web or as a native app.
• Methods: Use bridgeService.invoke to call native methods when running as a native app.
• Usage: Import and use storagePlugin in your JavaScript code to access native storage functionality.

Calling JavaScript from C#: Handling Events

MAUI Hybridizer also facilitates calling JavaScript functions from the C# layer, which is particularly useful for handling application lifecycle events like Resume and Stop.

Implementing Event Handling

In your App.xaml.cs file, set up the application lifecycle events and use _jsCaller to invoke JavaScript methods.

public partial class App : Application
{
    private readonly AppLifecycleService _appLifecycle;
    private readonly HwvJsCaller _jsCaller;

    public App(AppLifecycleService appLifecycle, HwvJsCaller jsCaller)
    {
        _appLifecycle = appLifecycle;
        _jsCaller = jsCaller;
        InitializeComponent();

        _appLifecycle.Resumed += async () => { await _jsCaller.WrappedCall("Resumed"); };
        _appLifecycle.Stopped += async () => { await _jsCaller.WrappedCall("Stopped"); };
    }

    protected override Window CreateWindow(IActivationState? activationState)
    {
        var window = new Window(new AppShell());
        window.Resumed += _appLifecycle.OnResumed;
        window.Stopped += _appLifecycle.OnStopped;
        return window;
    }
}

Explanation

• AppLifecycleService: A custom service that handles application lifecycle events.
• HwvJsCaller: Injected to enable calling JavaScript functions from C#.
• Event Subscriptions: When the app resumes or stops, the corresponding JavaScript functions Resumed or Stopped are called.

JavaScript Side

In your JavaScript application, register the event handlers using bridgeService.register.

bridgeService.register('Resumed', () => {
  // Handle resume event
});

bridgeService.register('Stopped', () => {
  // Handle stop event
});

Full Example

A comprehensive example of this implementation can be found in the sample project within the MAUI Hybridizer repository.

Conclusion

MAUI Hybridizer builds upon the strengths of existing tools to offer a robust, flexible solution for hybrid mobile application development. By simplifying plugin development and facilitating seamless communication between JavaScript and native code, it provides developers with an accessible and efficient tool for creating high-quality, cross-platform applications.

Personal Opinion

As a developer who has navigated the complexities of hybrid mobile app development, I find that MAUI Hybridizer leverages MAUI’s rich API heritage effectively while providing an intuitive interface for JavaScript integration. It complements existing solutions by offering an alternative that may better suit developers looking for tighter integration with .NET MAUI and a more straightforward plugin development process.

Current Status and Future Plans

MAUI Hybridizer is currently in beta, offering developers the opportunity to explore its features and capabilities. With the release of .NET 9, the library is planned to exit its beta phase, accompanied by a set of essential plugins in the MAUI Hybridizer Essentials package, which will cover core native functionalities and further enhance the development experience.

Getting Started

To explore Maui Hybridizer and see it in action, visit the GitHub repository and check out the sample project. Whether you’re building a new application or looking to enhance an existing one, this library offers a promising path forward in hybrid mobile development.