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