diff --git a/aspnetcore/blazor/includes/js-interop/7.0/import-export-interop-mappings.md b/aspnetcore/blazor/includes/js-interop/7.0/import-export-interop-mappings.md new file mode 100644 index 000000000000..4200d3e4e41b --- /dev/null +++ b/aspnetcore/blazor/includes/js-interop/7.0/import-export-interop-mappings.md @@ -0,0 +1,48 @@ +The following table indicates the supported type mappings. + +| .NET | JavaScript | `Nullable` | `Task` `Promise` | `JSMarshalAs` optional | :::no-loc text="Array of"::: | +| --- | --- | :---: | :---: | :---: | :---: | +| `Boolean` | `Boolean` | | | | | +| `Byte` | `Number` | | | | | +| `Char` | `String` | | | | | +| `Int16` | `Number` | | | | | +| `Int32` | `Number` | | | | | +| `Int64` | `Number` | | | | | +| `Int64` | `BigInt` | | | | | +| `Single` | `Number` | | | | | +| `Double` | `Number` | | | | | +| `IntPtr` | `Number` | | | | | +| `DateTime` | `Date` | | | | | +| `DateTimeOffset` | `Date` | | | | | +| `Exception` | `Error` | | | | | +| `JSObject` | `Object` | | | | | +| `String` | `String` | | | | | +| `Object` | `Any` | | | | | +| `Span` | `MemoryView` | | | | | +| `Span` | `MemoryView` | | | | | +| `Span` | `MemoryView` | | | | | +| `ArraySegment` | `MemoryView` | | | | | +| `ArraySegment` | `MemoryView` | | | | | +| `ArraySegment` | `MemoryView` | | | | | +| `Task` | `Promise` | | | | | +| `Action` | `Function` | | | | | +| `Action` | `Function` | | | | | +| `Action` | `Function` | | | | | +| `Action` | `Function` | | | | | +| `Func` | `Function` | | | | | +| `Func` | `Function` | | | | | +| `Func` | `Function` | | | | | +| `Func` | `Function` | | | | | + +The following conditions apply to type mapping and marshalled values: + +* The :::no-loc text="Array of"::: column indicates if the .NET type can be marshalled as a JS [`Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array). Example: C# `int[]` (`Int32`) mapped to JS `Array` of `Number`s. +* When passing a JS value to C# with a value of the wrong type, the framework throws an exception in most cases. The framework doesn't perform compile-time type checking in JS. +* `JSObject`, `Exception`, `Task` and `ArraySegment` create `GCHandle` and a proxy. You can trigger disposal in developer code or allow [.NET garbage collection (GC)](/dotnet/standard/garbage-collection/) to dispose of the objects later. These types carry significant performance overhead. +* `Array`: Marshaling an array creates a copy of the array in JS or .NET. +* `MemoryView` + * `MemoryView` is a JS class for the .NET WebAssembly runtime to marshal `Span` and `ArraySegment`. + * Unlike marshaling an array, marshaling a `Span` or `ArraySegment` doesn't create a copy of the underlying memory. + * `MemoryView` can only be properly instantiated by the .NET WebAssembly runtime. Therefore, it isn't possible to import a JS function as a .NET method that has a parameter of `Span` or `ArraySegment`. + * `MemoryView` created for a `Span` is only valid for the duration of the interop call. As `Span` is allocated on the call stack, which doesn't persist after the interop call, it isn't possible to export a .NET method that returns a `Span`. + * `MemoryView` created for an `ArraySegment` survives after the interop call and is useful for sharing a buffer. Calling `dispose()` on a `MemoryView` created for an `ArraySegment` disposes the proxy and unpins the underlying .NET array. We recommend calling `dispose()` in a `try-finally` block for `MemoryView`. diff --git a/aspnetcore/blazor/includes/js-interop/7.0/size-limits.md b/aspnetcore/blazor/includes/js-interop/7.0/size-limits.md new file mode 100644 index 000000000000..c8d54e562ff6 --- /dev/null +++ b/aspnetcore/blazor/includes/js-interop/7.0/size-limits.md @@ -0,0 +1,53 @@ +*This section only applies to Blazor Server apps. In Blazor WebAssembly, the framework doesn't impose a limit on the size of JavaScript (JS) interop inputs and outputs.* + +In Blazor Server, JS interop calls are limited in size by the maximum incoming SignalR message size permitted for hub methods, which is enforced by (default: 32 KB). JS to .NET SignalR messages larger than throw an error. The framework doesn't impose a limit on the size of a SignalR message from the hub to a client. + +When SignalR logging isn't set to [Debug](xref:Microsoft.Extensions.Logging.LogLevel) or [Trace](xref:Microsoft.Extensions.Logging.LogLevel), a message size error only appears in the browser's developer tools console: + +> Error: Connection disconnected with error 'Error: Server returned an error on close: Connection closed with an error.'. + +When [SignalR server-side logging](xref:signalr/diagnostics#server-side-logging) is set to [Debug](xref:Microsoft.Extensions.Logging.LogLevel) or [Trace](xref:Microsoft.Extensions.Logging.LogLevel), server-side logging surfaces an for a message size error. + +`appsettings.Development.json`: + +```json +{ + "DetailedErrors": true, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information", + "Microsoft.AspNetCore.SignalR": "Debug" + } + } +} +``` + +Error: + +> System.IO.InvalidDataException: The maximum message size of 32768B was exceeded. The message size can be configured in AddHubOptions. + +Increase the limit by setting in `Program.cs`. The following example sets the maximum receive message size to 64 KB: + +```csharp +builder.Services.AddServerSideBlazor() + .AddHubOptions(options => options.MaximumReceiveMessageSize = 64 * 1024); +``` + +Increasing the SignalR incoming message size limit comes at the cost of requiring more server resources, and it exposes the server to increased risks from a malicious user. Additionally, reading a large amount of content in to memory as strings or byte arrays can also result in allocations that work poorly with the garbage collector, resulting in additional performance penalties. + +Consider the following guidance when developing code that transfers a large amount of data between JS and Blazor in Blazor Server apps: + +* Leverage the native streaming interop support to transfer data larger than the SignalR incoming message size limit: + * + * +* General tips: + * Don't allocate large objects in JS and C# code. + * Free consumed memory when the process is completed or cancelled. + * Enforce the following additional requirements for security purposes: + * Declare the maximum file or data size that can be passed. + * Declare the minimum upload rate from the client to the server. + * After the data is received by the server, the data can be: + * Temporarily stored in a memory buffer until all of the segments are collected. + * Consumed immediately. For example, the data can be stored immediately in a database or written to disk as each segment is received. diff --git a/aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md b/aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md index 3bd9b9df8a78..d2c9fae3a7cc 100644 --- a/aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md +++ b/aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md @@ -2155,7 +2155,7 @@ In the preceding example: ## Size limits on JavaScript interop calls -[!INCLUDE[](~/blazor/includes/js-interop/6.0/size-limits.md)] +[!INCLUDE[](~/blazor/includes/js-interop/7.0/size-limits.md)] ## JavaScript `[JSImport]`/`[JSExport]` interop diff --git a/aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md b/aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md index d7d57244c81f..cdf537b27823 100644 --- a/aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md +++ b/aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md @@ -2434,7 +2434,7 @@ For information on using a byte array when calling .NET from JavaScript, see ). The approaches described in this article should be used to replace the obsolete unmarshalled JS interop API when migrating to .NET 7. - +> [!NOTE] +> This article focuses on JS interop in Blazor WebAssembly apps. For guidance on calling .NET in JavaScript apps, see . ## Obsolete JavaScript interop API @@ -118,6 +112,8 @@ The app's namespace for the preceding `CallJavaScript1` partial class is `Blazor In the imported method signature, you can use .NET types for parameters and return values, which are marshalled automatically by the runtime. Use `JSMarshalAsAttribute` to control how the imported method parameters are marshalled. For example, you might choose to marshal a `long` as or . You can pass / callbacks as parameters, which are marshalled as callable JS functions. You can pass both JS and managed object references, and they are marshaled as proxy objects, keeping the object alive across the boundary until the proxy is garbage collected. You can also import and export asynchronous methods with a result, which are marshaled as [JS promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise). Most of the marshalled types work in both directions, as parameters and as return values, on both imported and exported methods, which are covered in the [Call .NET from JavaScript](#call-net-from-javascript) section later in this article. +[!INCLUDE[](~/blazor/includes/js-interop/7.0/import-export-interop-mappings.md)] + The module name in the `[JSImport]` attribute and the call to load the module in the component with `JSHost.ImportAsync` must match and be unique in the app. When authoring a library for deployment in a NuGet package, we recommend using the NuGet package namespace as a prefix in module names. In the following example, the module name reflects the `Contoso.InteropServices.JavaScript` package and a folder of user message interop classes (`UserMessages`): ```csharp @@ -363,12 +359,9 @@ await JSHost.ImportAsync("Interop", "../js/interop.js"); > [!IMPORTANT] > In this section's example, JS interop is used to mutate a DOM element *purely for demonstration purposes* after the component is rendered in [`OnAfterRender`](xref:blazor/components/lifecycle#after-component-render-onafterrenderasync). Typically, you should only mutate the DOM with JS when the object doesn't interact with Blazor. The approach shown in this section is similar to cases where a third-party JS library is used in a Razor component, where the component interacts with the JS library via JS interop, the third-party JS library interacts with part of the DOM, and Blazor isn't involved directly with the DOM updates to that part of the DOM. For more information, see . - +* +* In the `dotnet/runtime` GitHub repository: + * [.NET WebAssembly runtime](https://github.com/dotnet/runtime/blob/main/src/mono/wasm/runtime/) + * [`dotnet.d.ts` file (.NET WebAssembly runtime configuration)](https://github.com/dotnet/runtime/blob/main/src/mono/wasm/runtime/dotnet.d.ts) diff --git a/aspnetcore/client-side/dotnet-interop.md b/aspnetcore/client-side/dotnet-interop.md index f2ea79d77f5d..e53b5fdf028c 100644 --- a/aspnetcore/client-side/dotnet-interop.md +++ b/aspnetcore/client-side/dotnet-interop.md @@ -179,54 +179,7 @@ internal static partial string GetHRef(); In the imported method signature, you can use .NET types for parameters and return values, which are marshalled automatically by the runtime. Use `JSMarshalAsAttribute` to control how the imported method parameters are marshalled. For example, you might choose to marshal a `long` as or . You can pass / callbacks as parameters, which are marshalled as callable JS functions. You can pass both JS and managed object references, and they are marshaled as proxy objects, keeping the object alive across the boundary until the proxy is garbage collected. You can also import and export asynchronous methods with a result, which are marshaled as [JS promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise). Most of the marshalled types work in both directions, as parameters and as return values, on both imported and exported methods. -The following table indicates the supported type mappings. - -| .NET | JavaScript | `Nullable` | `Task` `Promise` | `JSMarshalAs` optional | :::no-loc text="Array of"::: | -| --- | --- | :---: | :---: | :---: | :---: | -| `Boolean` | `Boolean` | | | | | -| `Byte` | `Number` | | | | | -| `Char` | `String` | | | | | -| `Int16` | `Number` | | | | | -| `Int32` | `Number` | | | | | -| `Int64` | `Number` | | | | | -| `Int64` | `BigInt` | | | | | -| `Single` | `Number` | | | | | -| `Double` | `Number` | | | | | -| `IntPtr` | `Number` | | | | | -| `DateTime` | `Date` | | | | | -| `DateTimeOffset` | `Date` | | | | | -| `Exception` | `Error` | | | | | -| `JSObject` | `Object` | | | | | -| `String` | `String` | | | | | -| `Object` | `Any` | | | | | -| `Span` | `MemoryView` | | | | | -| `Span` | `MemoryView` | | | | | -| `Span` | `MemoryView` | | | | | -| `ArraySegment` | `MemoryView` | | | | | -| `ArraySegment` | `MemoryView` | | | | | -| `ArraySegment` | `MemoryView` | | | | | -| `Task` | `Promise` | | | | | -| `Action` | `Function` | | | | | -| `Action` | `Function` | | | | | -| `Action` | `Function` | | | | | -| `Action` | `Function` | | | | | -| `Func` | `Function` | | | | | -| `Func` | `Function` | | | | | -| `Func` | `Function` | | | | | -| `Func` | `Function` | | | | | - -The following conditions apply to type mapping and marshalled values: - -* The :::no-loc text="Array of"::: column indicates if the .NET type can be marshalled as a JS [`Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array). Example: C# `int[]` (`Int32`) mapped to JS `Array` of `Number`s. -* When passing a JS value to C# with a value of the wrong type, the framework throws an exception in most cases. The framework doesn't perform compile-time type checking in JS. -* `JSObject`, `Exception`, `Task` and `ArraySegment` create `GCHandle` and a proxy. You can trigger disposal in developer code or allow [.NET garbage collection (GC)](/dotnet/standard/garbage-collection/) to dispose of the objects later. These types carry significant performance overhead. -* `Array`: Marshaling an array creates a copy of the array in JS or .NET. -* `MemoryView` - * `MemoryView` is a JS class for the .NET WebAssembly runtime to marshal `Span` and `ArraySegment`. - * Unlike marshaling an array, marshaling a `Span` or `ArraySegment` doesn't create a copy of the underlying memory. - * `MemoryView` can only be properly instantiated by the .NET WebAssembly runtime. Therefore, it isn't possible to import a JS function as a .NET method that has a parameter of `Span` or `ArraySegment`. - * `MemoryView` created for a `Span` is only valid for the duration of the interop call. As `Span` is allocated on the call stack, which doesn't persist after the interop call, it isn't possible to export a .NET method that returns a `Span`. - * `MemoryView` created for an `ArraySegment` survives after the interop call and is useful for sharing a buffer. Calling `dispose()` on a `MemoryView` created for an `ArraySegment` disposes the proxy and unpins the underlying .NET array. We recommend calling `dispose()` in a `try-finally` block for `MemoryView`. +[!INCLUDE[](~/blazor/includes/js-interop/7.0/import-export-interop-mappings.md)] To export a .NET method so it can be called from JS, use the `JSExportAttribute`. diff --git a/aspnetcore/migration/60-70.md b/aspnetcore/migration/60-70.md index 7f2cbf7a4fbf..9730259d834f 100644 --- a/aspnetcore/migration/60-70.md +++ b/aspnetcore/migration/60-70.md @@ -114,20 +114,12 @@ For more information, see the following content in the *Data binding* article: * [Introduction](xref:blazor/components/data-binding?view=aspnetcore-7.0) * [Bind across more than two components](xref:blazor/components/data-binding?view=aspnetcore-7.0#bind-across-more-than-two-components) - - ### .NET WebAssembly build tools for .NET 6 projects You can now use the .NET WebAssembly build tools with a .NET 6 project when working with the .NET 7 SDK. The new `wasm-tools-net6` workload includes the .NET WebAssembly build tools for .NET 6 projects so that they can be used with the .NET 7 SDK. The existing `wasm-tools` workload installs the .NET WebAssembly build tools for .NET 7 projects. However, the .NET 7 version of the .NET WebAssembly build tools are incompatible with existing projects built with .NET 6. Projects using the .NET WebAssembly build tools that need to support both .NET 6 and .NET 7 must use multi-targeting. diff --git a/aspnetcore/release-notes/aspnetcore-7.0.md b/aspnetcore/release-notes/aspnetcore-7.0.md index 0222ccfe31c0..9c752a9df14a 100644 --- a/aspnetcore/release-notes/aspnetcore-7.0.md +++ b/aspnetcore/release-notes/aspnetcore-7.0.md @@ -406,18 +406,8 @@ JavaScript `[JSImport]`/`[JSExport]` interop API is a new low-level mechanism fo For more information: -* : Pertains only to Blazor WebAssebmly apps. -* Preview coverage is *coming soon* for running .NET code from JS apps that don't depend on the Blazor UI component model. - - +* : Pertains only to Blazor WebAssembly apps. +* : Pertains only to JavaScript apps that don't depend on the Blazor UI component model. ### Conditional registration of the authentication state provider