HybridWebView: Invoke JS methods from .NET

[Eilon]

Description of Change

Before we get started: HUGE thank you to @rbrundritt for working on a key part of this for async JavaScript method support!

Enable C# code to invoke methods running in JS in the WebView. The methods can be invoked as async, have optional return values, and optional parameters. The parameters and return values are serialized using JSON.

Example

With some simple JavaScript code like this:

function AddNumbers(x, y) {
    return x + y;
}

And you can invoke it from C# like this:

var x = 123m;
var y = 321m;
var sum = await hybridWebView.InvokeJavaScriptAsync<decimal>(
    "AddNumbers", // JavaScript method name
    JsInvokeContext.Default.Decimal, // JSON serialization info for return type
    new object[] { x, y }, // parameter values
    new[] { JsInvokeContext.Default.Decimal, JsInvokeContext.Default.Decimal }); // JSON serialization info for each parameter
);

// sum is now 444

[JsonSourceGenerationOptions(WriteIndented = true)]
[JsonSerializable(typeof(decimal))]
[JsonSerializable(typeof(Dictionary<string, string>))]
internal partial class JsInvokeContext : JsonSerializerContext
{
    // This type's attributes specify JSON serialization info to preserve type structure for optimized/trimmed builds
}

And then with a bit more complex async JavaScript code like this:

        async function GetAsyncData() {
            const response = await fetch("/asyncdata.txt");
            if (!response.ok) {
                    throw new Error(`HTTP error: ${response.status}`);
            }
            return await response.json();
        }

You can invoke it from C# like this:

var jsonDictionaryResult = await hybridWebView.InvokeJavaScriptAsync<Dictionary<string,string>>(
    "GetAsyncData", // JavaScript method name
    JsInvokeContext.Default.DictionaryStringString, // JSON serialization info for return type
    null, // this method has no parameter values
    null); // this method doesn't JSON serialization info for each parameter
);

// result is now a dictionary containing the JSON data from the web request, such as [key1]=value1, [key2]=value2

Issues Fixed

Fixes #22303

[Eilon]

@mattleibow - this is the follow-up to a comment you had on an earlier PR. I added this 'container type' for better future-proofing.

[Eilon]

There are now a few places in the code where the Windows code that uses WebView2 does a "ensure WebView2 is initialized, and then execute" pattern. This is because WebView2 is the only webview we use that has an async pattern to ensure it is ready. For that reason in places where the code is synchronous but needs WebView2 to be ready, it dispatches the work item to an async task, and awaits ready-ness, and then does what it wants. This is the same pattern we did in BlazorWebView.

[Eilon]

Tested locally on Windows, Android Emulator, iOS Simulator, and MacCatalyst. Will add more automated tests now.

[Eilon]

Everything on CI is passing except for the Android emulator tests Core_API_23 job. It's failing for every net9 build on the CI with the same error (android.util.AndroidException: INSTRUMENTATION_FAILED: com.microsoft.maui.core.devicetests/com.microsoft.maui.core.devicetests.TestInstrumentation), so I'm ignoring that.

[jfversluis]

Also fixes #6446?

[tj-devel709]

Overall looks good to me! Just some small things!

[PureWeen]

• Device Tests and MAUI-Public have both completed with green . Github was down so the checkmarks just aren't updating
• RunOniOS failure is unrelated to this PR

[mattleibow]

This PR is mostly good with regards to code and implementation, however it is starting to break the "rules" of the architecture and separation.

The XAML controls should not have much processing (especially platform-specific processing) and instead let the handler do it all. Also, if there is any platform specific code in the XAML controls, then it is highly likely that it should have been in Core.

In the cases where there is no implementation for commands/mappers, the XAML control must still pass the message/event/command to the handler and let the handler control its behavior. This allows for the Community Toolkit (and developers) customize the behavior.

I also see the code in the XAML layer deciding that the best way to communicate is via JSON. This may be fine, but is it the most correct? Are there cases where there may be communication in a binary form or some custom/alternate serialization. A developer may wish to use their own models and objects that are processed in a different library.

[mattleibow]

This processing should be done in Core and fire specific methods in Controls. There is no need for XAML objects to be post processing and parsing strings.

[mattleibow]

There should be almost no #if things in Controls as it really is there for cases where it is not possible to do it any way else.

No matter if the operation is not supported, the Controls layer should always send the command to the handler where the work is done. If the handler decides it is not supported, then the handler can throw. This also allows the user to override the full operation if need be to make it work.

[mattleibow]

Most of this function, and especially this code should be in Core via a command. The handler should be doing this instead of checking the platform. Android knows it does not need this, so it does not need to have this code.

[mattleibow]

Instead of having the processing done in Controls, it should be here with maybe an event args with the message type:

void MessageReceived(HybridWebViewMessageRecieved  message);

class HybridWebViewMessageRecieved {
}

class HybridWebViewRawMessageRecieved : HybridWebViewMessageRecieved {
}

class HybridWebViewInvokeMessageRecieved : HybridWebViewMessageRecieved {
}

This allows for easy extension and possibly better handler-specific implementations instead of parsing in XAML controls.