New Blazor JS interop

[guardrex]

Per dotnet/blazor-samples#41 ...

there is new JavaScript interop available for .Net 7.

I created simple demo to show the new JavaScript interop in Blazor.

I'm not sure if you want to adopt it as is, but perhaps you could have look at it and extend one of the existing sample apps.

https://github.com/pavelsavara/blazor-wasm-hands-pose

There is also non-Blazor demo which has more complex interop logic

https://github.com/pavelsavara/dotnet-wasm-todo-mvc

(also please ping me on IM to discuss how to collaborate on further docs about the feature, thank you)

It's best if we have a section and extend the snippet sample apps, as opposed to adding a new sample app. Every sample app adds overhead costs 💸☹️.

cc: @pavelsavara

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 57ed3088-2f9b-f51a-fd17-0c0de2949c57
• Version Independent ID: 49fa31d8-72a6-01a1-027d-6edeac9e0fc4
• Content: ASP.NET Core Blazor JavaScript interoperability (JS interop)
• Content Source: aspnetcore/blazor/javascript-interoperability/index.md
• Product: aspnet-core
• Technology: aspnetcore-blazor
• GitHub Login: @guardrex
• Microsoft Alias: riande

[guardrex]

Ignore ME here! 😆

This was my first (FLAWED & FAILED) attempt. I had better luck this afternoon. See the next comment.

@pavelsavara ... The first step for updates is merely to convert the obsolete explanations and examples for unmarshalled JS calls for the 7.0 docs. There are two sections/examples, a simple example with general remarks and a more complicated example in another article.

Let's see if we can get me straight on the simple example first, then I'll see what I can do with the other example. After that, I'll chat with Dan to see how much coverage we'll host beyond that and ask about the sample app situation on your original dotnet/blazor-samples repo issue.

I tried something here, but it 💥😢 on me. Obviously, I didn't wire it up right! 🙈🤣

Our 6.0 demo of the simple use case is ...

https://docs.microsoft.com/en-us/aspnet/core/blazor/performance?view=aspnetcore-6.0#consider-the-use-of-unmarshalled-calls

Here's what I set up ...

1. Use <AllowUnsafeBlocks>true</AllowUnsafeBlocks> in the project file.

2. I'll show this JS both ways because I wasn't sure which way might work (a raw FN, as we have today in that section example -AND- a global FN version). BTW ... We're not using modules in most cases because (1) we want to show the lowest common demoninator for implementing JS code, and (2) we want to preserve as much doc space as we can in code examples. If you end up telling me that this approach MUST involve the JS in a module, ok then ... yeah ... that will probably explain my problem.

   Both of the following approaches failed.

   In wwwroot/index.html below the Blazor script link:

   <script>
     function jsInteropCall() {
       return BINDING.js_to_mono_obj("Hello world");
     }
   </script>

   ... or ...

   <script>
     window.jsInteropCall = () => {
       return BINDING.js_to_mono_obj("Hello world");
     }
   </script>

3. RegisteredComponentsInterop.cs:

   using System.Runtime.InteropServices.JavaScript;
   
   internal sealed partial class RegisteredComponentsInterop
   {
   
       [JSImport("jsInteropCall")]
       public static partial string JSInteropCall();
   }

4. In the Index component ...

   @page "/"
   @using System.Runtime.InteropServices.JavaScript
   
   <h1>Unmarshalled interop</h1>
   
   <p>
       value: @value
   </p>
   
   @code {
       private string? value;
   
       protected override void OnInitialized()
       {
           value = RegisteredComponentsInterop.JSInteropCall();
       }
   }

BTW --- Tried that in OnAfterRender, too ... no 🎲🎲.

🥁🥁🥁🥁 plz ... and the error is ......

Unhandled exception rendering component: Error: Assert failed: jsInteropCall must be a Function but was undefined

So, where did I go off the rails there? 😄

Oh, I'm going to look at your sample app in a sec. I haven't quite reached that yet.

UPDATE: I'm going to look at your sample app on Friday morning. My 🧠is a bit 🥘 at this point. 😄

UPDATE 2: ... and I did just take a quick look and noticed ...

With Net7 RC1 or later do:

dotnet workload install wasm-tools

I installed it and restarted the system. Again, no 🎲🎲 ... same error.

[guardrex]

@pavelsavara ... Ok ... Came back this afternoon to try again, and I had better luck 🍀 ...

1. <AllowUnsafeBlocks>true</AllowUnsafeBlocks> in the project file.

2. wwwroot/js/scripts.js:

   export function jsInteropCall() {
     return 'Hello World!';
   }

3. RegisteredComponentsInterop.cs:

   using System.Runtime.InteropServices.JavaScript;
   
   internal sealed partial class RegisteredComponentsInterop
   {
       [JSImport("jsInteropCall", "Interop")]
       public static partial string JSInteropCall();
   }

4. Pages/Index.razor:

   @page "/"
   @using System.Runtime.InteropServices.JavaScript
   
   <p>
       value: @value
   </p>
   
   @code {
       private string? value;
   
       protected override async Task OnAfterRenderAsync(bool firstRender)
       {
           if (firstRender)
           {
               await JSHost.ImportAsync("Interop", "../js/scripts.js");
               value = RegisteredComponentsInterop.JSInteropCall();
               StateHasChanged();
           }
       }
   }

... and that seems to work 🎉.

Lot's of ❓tho about what devs need to read on it ... best practices and critical info on things like ...

• First of all, is this even unmarshalled interop at all???? ... or is this just ✨ NEW and IMPROVED ✨ JS interop? If that's the case, then we'll need to discuss what the actual replacement is for the unmarshalled approach with the new API, if that's even a thing any longer. My first goal for the updates is to deal with the two sections we have for unmarshalled interop at ...
  • https://docs.microsoft.com/en-us/aspnet/core/blazor/performance?view=aspnetcore-6.0#consider-the-use-of-unmarshalled-calls
  • https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/call-javascript-from-dotnet?view=aspnetcore-6.0#unmarshalled-javascript-interop
  • NOTE TO SELF: I potentially need to update the text in the Object serialization section of the JS interop Overview topic.
• <AllowUnsafeBlocks> ... Security concerns?
• You want .mjs? ... or is just .js ok in this context?
• Anything in particular to say about the module and its exports for this approach?
• Naming remarks on the class and module (e.g., where I just placed RegisteredComponentsInterop to get this working)?
• Do you like using OnAfterRender for module import, or would initialization be better?

... stuff like that. Whatever you feel is the best general approach for the most common basic use case.

[pavelsavara]

2. `wwwroot/js/scripts.js`:

All previous options how Blazor could deploy the JS file are still there. My favorite is next to the razor component.

   ```
       protected override async Task OnAfterRenderAsync(bool firstRender)
               await JSHost.ImportAsync("RegisteredComponentsInterop", "../js/scripts.js");
   ```

I'm not really Blazor expert yet, but this seems that the script download would be delayed too late and slow down the first render with the JS code impact. Is there event which could do it earlier ?

* First of all, is this even unmarshalled interop at all???? ... or is this just ✨ **_NEW and IMPROVED_** ✨ JS interop? If that's the case, then we'll need to discuss what the actual replacement is for the **unmarshalled** approach with the new API, if that's even a thing any longer. My first goal for the updates is to deal with the two sections we have for unmarshalled interop at ...

This is marshaled interop and it's so fast you could replace any legacy unmarshaled interop with it. And you should because IJSUnmarshalledRuntime is now obsolete.
@danroth27 would be better guide to help you to express Blazor oficial position and wording on this.

* `<AllowUnsafeBlocks>` ... Security concerns?

It means that (user and) the code generator in Roslyn compiler could use pointers. Not a security concern. Rather developer would not be prevented from using lower level concepts in that assembly.

* You want `.mjs`? ... or is just `.js` ok in this context?

.js is ok on the web. It makes difference on NodeJS, which you are not targeting with Blazor.

* Anything in particular to say about the module and its exports for this approach?

It's standard ES6 module. The module name in the JSImport and ImportAsync should match each other and they need to be unique in the app. Therefore if you are authoring NuGet package, you should use your namespace/prefix.

* Naming remarks on the class and module (e.g., where I just placed `RegisteredComponentsInterop` to get this working)?

So far I did my as public static class Interop nested in the real class which is using it.

* Do you like using `OnAfterRender` for module import, or would initialization be better?

JS download takes time.
As early as possible. Maybe non-blocking async cal in parallel with other work.
Developers could also prefetch it.

[pavelsavara]

Link to ES6 modules doc, you could probably even link it from our docs https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

[pavelsavara]

Also the new API is only available in the browser (not on server side). The code analyzer would complain about it with CA1416.
The correct way how to solve it is to use

if (OperatingSystem.IsBrowser())
{
    //only call the new interop from here
}

[pavelsavara]

• There is also JSExport which you should explore.
• Could should show how to pass callback on JSImport method and how to register DOM event.

[pavelsavara]

I don't know what was Blazor previous guidance on Blazor component instances together with JSInProcessRuntime calls. For example when you have grid on the page with multiple rows. Each row is Blazor component with the JS interop. How does the DOM event handler hit the correct C# instance of the row ?

• With this new interop we could marshal C# instance during registration and pass it back on the JSExport call
• We could also capture it in C# closure of the callback passed to JSImport call
• We could use existing ways how Blazor does this with JSInProcessRuntime - I don't know what it is, sorry

[pavelsavara]

  * https://docs.microsoft.com/en-us/aspnet/core/blazor/performance?view=aspnetcore-6.0#consider-the-use-of-unmarshalled-calls
  * https://docs.microsoft.com/en-us/aspnet/core/blazor/javascript-interoperability/call-javascript-from-dotnet?view=aspnetcore-6.0#unmarshalled-javascript-interop

Ideally these 2 articles would not be part of Net 7 because we don't want people to use it for new code. The JS APIs on BINDING and MONO objects are now also deprecated. They are also un-fixably unsafe during GC.