MAUI Hybrid Launcher for OpenSilver

Starting with OpenSilver 3.2, you can now run your OpenSilver applications not only in the browser but also as native apps on macOS, Windows, Android, and iOS. Additionally, you can publish these apps to major app stores: Google Play, Apple App Store, and Windows Store. This multi-platform capability is enabled by our support for the new MAUI Hybrid Launcher.

Overview

The MAUI Hybrid Launcher bridges OpenSilver with the native capabilities provided by .NET MAUI. This means you get the best of both worlds:

Web-based UI: Develop with familiar OpenSilver paradigms.
Native integration: Leverage platform-specific features and publish to app stores.

Prerequisites

Before you get started, ensure you have the following installed:

Visual Studio 2022 or later with the ".NET Multi-platform App UI development" component installed.
One of the following OpenSilver tools:

Creating an OpenSilver Application with MAUI Hybrid Launcher

You can create a new OpenSilver application with the MAUI Hybrid Launcher using either the command line, Visual Studio 2022, or Visual Studio Code.

1. Via Command Line

Open your terminal and run one of the following commands:

For all supported MAUI Platforms:

dotnet new opensilverapp -o MyAppName --mauiPlatforms all

For specific MAUI Platforms (e.g., Android and Windows):

dotnet new opensilverapp -o MyAppName --mauiPlatforms android windows

Note: The Browser launcher is always included by default.

After running the command, a new OpenSilver application will be generated with an additional .MauiHybrid launcher project. You can then open and continue developing your application in your favorite IDE.

2. Via Visual Studio 2022

Install the OpenSilver extension.
Start by creating a new OpenSilver project.
In the project creation wizard, you will see an additional configuration panel to select the desired MAUI Platforms.
Choose the platforms you wish to target and complete the wizard.

3. Via Visual Studio Code

Install the OpenSilver extension.
Initiate the creation of a new application.
When prompted, select the MAUI Platforms you want to include.
If you choose not to select any platforms, the generated OpenSilver application will not include the MAUI Hybrid Launcher.

Running the MAUI Hybrid Launcher

To run your OpenSilver application using the MAUI Hybrid Launcher, follow these steps:

Set the Startup Project: Choose the .MauiHybrid launcher as the startup project in your solution.
Select the Target Platform: Ensure you have selected the appropriate target platform before running the application.
IDE Recommendations:
- For macOS and Linux, we recommend using Visual Studio Code with the OpenSilver extension.
- For Windows, we recommend using Visual Studio 2022 with the OpenSilver extension.

Running on Windows (Example)

To run your generated application as a native Windows desktop app:

Set the Startup Project:
- In your solution, choose the .MauiHybrid project as the startup project.
Select the Target Platform:
- Make sure that "Windows" is selected as your target platform.
Run the Application:
- Click the run button (or press F5) to launch the app.

Leveraging MAUI Native Features

One of the strengths of the MAUI Hybrid Launcher is that it gives you access to native features via .NET MAUI. For example, the Microsoft.Maui.Essentials package provides APIs for accessing device hardware and native functions.

Thread Considerations

OpenSilver’s core logic runs on its own dedicated thread, while many native operations require execution on the MAUI UI thread. Use MainThread.BeginInvokeOnMainThread from the Microsoft.Maui.Essentials package to marshal calls onto the MAUI UI thread.

Example: Accessing User Location

Below is an example demonstrating how to request location permissions, obtain the user’s location, and update the UI:

// Run the native API calls on the MAUI UI thread.
MainThread.BeginInvokeOnMainThread(async () =>
{
    // Check the current location permission status.
    var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();

    // If permission is not granted, request it.
    if (status != PermissionStatus.Granted)
    {
        status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
    }

    // If permission is granted, fetch the location.
    if (status == PermissionStatus.Granted)
    {
        var request = new GeolocationRequest(GeolocationAccuracy.Medium);
        var location = await Geolocation.Default.GetLocationAsync(request);

        if (location != null)
        {
            // Switch back to the OpenSilver thread to update the UI.
            Dispatcher.BeginInvoke(() =>
            {
                TB.Text = location.ToString();
            });
        }
    }
    else
    {
        // Inform the user if permission was denied.
        Dispatcher.BeginInvoke(() =>
        {
            MessageBox.Show("Location permission denied.");
        });
    }
});

Important: Ensure proper permissions are configured for all platforms. For example, for Android, add the following permissions to AndroidManifest.xml:

ACCESS_COARSE_LOCATION

ACCESS_FINE_LOCATION

Publishing to App Stores

Since OpenSilver leverages the official MAUI Hybrid technology, you can follow the standard publishing processes provided by Microsoft. For detailed steps, refer to the official MAUI deployment guides:

Android: MAUI Android Deployment
iOS: MAUI iOS Deployment
macOS: MAUI Mac Catalyst Deployment
Windows: MAUI Windows Deployment Overview

Known Issues

Path Length Limitations

There is a known issue related to the internal path size limitations in MAUI. This can result in build failures due to the generated temporary file paths exceeding 256 characters.
Workaround: Place your project folder as close to the root directory as possible (for example, C:\MyProject) to reduce the overall path length.

Windows Launch Failure (Code 3221226356 / 0xc0000374)

Sometimes, when attempting to run the application on Windows, it may fail with exit code 3221226356 (0xc0000374). More details: Official issue on GitHub.
Workaround: Try running the application again.

Conclusion

The MAUI Hybrid Launcher extends OpenSilver applications into fully native experiences across multiple platforms. Whether you’re building for Windows, macOS, Android, or iOS, you now have a streamlined way to leverage both OpenSilver’s rich UI capabilities and MAUI’s native functionalities.