/maui-hybridwebview

name: maui-hybridwebview
description: >
  Guidance for embedding web content in .NET MAUI apps using HybridWebView,
  including JavaScript–C# interop, bidirectional communication, raw messaging,
  and trimming/NativeAOT considerations.
  USE FOR: "HybridWebView", "JavaScript interop", "embed web content", "JS to C# interop",
  "C# to JavaScript", "web view interop", "raw message", "InvokeJavaScriptAsync",
  "web content MAUI".
  DO NOT USE FOR: deep linking from external URLs (use maui-deep-linking),
  REST API calls (use maui-rest-api), or Blazor Hybrid apps (different from HybridWebView).

HybridWebView in .NET MAUI

`HybridWebView` hosts HTML/JS/CSS content inside a .NET MAUI app with bidirectional C#↔JS communication. It is **not** a general browser control — it is designed for local web content shipped with the app.

Common gotchas

| Issue | Fix | |---|---| | Blank white screen | Web assets missing from `Resources/Raw/wwwroot` or `DefaultFile` not set | | JS interop silently fails | Missing `<script src="_hwv/HybridWebView.js"></script>` in HTML | | `InvokeJavaScriptAsync` returns null | Return type missing `[JsonSerializable]` attribute in `JsonSerializerContext` | | JS → C# calls do nothing | `SetInvokeJavaScriptTarget` not called before JS invokes C# methods | | Serialization crash with trimming | Not using source-generated `JsonSerializerContext` |

⚠️ Bridge script is mandatory

The HTML page **must** include the bridge script **before** any app scripts:

<!-- ✅ Correct order -->
<script src="_hwv/HybridWebView.js"></script>
<script src="scripts/app.js"></script>

<!-- ❌ Wrong — app.js loads before bridge, interop calls fail silently -->
<script src="scripts/app.js"></script>
<script src="_hwv/HybridWebView.js"></script>

JSON serialization — every type must be registered

Every parameter type **and** return type used in `InvokeJavaScriptAsync` must have a `[JsonSerializable]` entry:

// ✅ Correct — all interop types registered
[JsonSerializable(typeof(int))]
[JsonSerializable(typeof(string))]
[JsonSerializable(typeof(Person))]
internal partial class MyJsonContext : JsonSerializerContext { }

// ❌ Wrong — adding a new type to interop without registering it
// This causes silent null returns or runtime exceptions

> **Rule**: When you add a new type to the interop surface, you **must** add a `[JsonSerializable(typeof(T))]` attribute to the context. Forgetting this is the #1 cause of mysterious interop failures.

SetInvokeJavaScriptTarget — timing matters

// ✅ Set target BEFORE the web page loads and JS calls C#
myHybridWebView.SetInvokeJavaScriptTarget(new MyJsBridge());

// ❌ Setting it after JS already tried to call — calls are lost

⚠️ Call `SetInvokeJavaScriptTarget` during page construction or `OnAppearing`, not lazily.

Exception handling (.NET 9+)

JS exceptions thrown during `InvokeJavaScriptAsync` are forwarded to .NET. Always wrap interop calls:

// ✅ Catches JS errors
try
{
    var result = await myHybridWebView.InvokeJavaScriptAsync<string>(
        "riskyFunction", MyJsonContext.Default.String);
}
catch (Exception ex)
{
    Debug.WriteLine($"JS error: {ex.Message}");
}

// ❌ Unhandled JS exception crashes the interop pipeline
var result = await myHybridWebView.InvokeJavaScriptAsync<string>(
    "riskyFunction", MyJsonContext.Default.String);

Trimming / NativeAOT pitfalls

Trimming is **disabled by default** in MAUI projects. If you enable it:

• ⚠️ You **must** use source-generated `JsonSerializerContext` (not reflection-based serialization)
• ⚠️ Set `JsonSerializerIsReflectionEnabledByDefault` to `false`
• Using `JsonSerializerContext` as shown above is recommended **regardless** of trimming settings

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
</PropertyGroup>

Decision framework — typed interop vs raw messages

| Need | Use | |---|---| | Structured data exchange with type safety | `InvokeJavaScriptAsync` / `InvokeDotNet` with `JsonSerializerContext` | | Simple string payloads, fire-and-forget | `SendRawMessage` / `RawMessageReceived` | | Calling C# from JS with return values | `InvokeDotNet` (target must be set first) | | Multiple JS functions to call | Typed interop — one `InvokeJavaScriptAsync` per function |

Quick checklist

• [ ] Web content is under `Resources/Raw/wwwroot`
• [ ] `index.html` includes `<script src="_hwv/HybridWebView.js"></script>` **before** app scripts
• [ ] `DefaultFile` is set (or defaults to `index.html`)
• [ ] Every interop type has a `[JsonSerializable]` entry in a `JsonSerializerContext`
• [ ] `SetInvokeJavaScriptTarget` is called before JS invokes C# methods
• [ ] `InvokeJavaScriptAsync` calls are wrapped in try/catch (.NET 9+)
• [ ] If trimming enabled: source-generated JSON serialization configured