diff --git a/aspnetcore/blazor/javascript-interoperability/index.md b/aspnetcore/blazor/javascript-interoperability/index.md index b538a861d4d3..d82c3a6143bb 100644 --- a/aspnetcore/blazor/javascript-interoperability/index.md +++ b/aspnetcore/blazor/javascript-interoperability/index.md @@ -34,6 +34,29 @@ For more information, see . +## Object serialization + +Blazor uses for serialization with the following requirements and default behaviors: + +* Types must have a default constructor, [`get`/`set` accessors](/dotnet/csharp/programming-guide/classes-and-structs/using-properties) must be public, and fields are never serialized. +* Global default serialization isn't customizable to avoid breaking existing component libraries, impacts on performance and security, and reductions in reliability. +* Serializing .NET member names results in lowercase JSON key names. +* JSON is deserialized as C# instances, which permit mixed casing. Internal casting for assignment to C# model properties works as expected in spite of any case differences between JSON key names and C# property names. + + API is available for custom serialization. Properties can be annotated with a [`[JsonConverter]` attribute](xref:System.Text.Json.Serialization.JsonConverterAttribute) to override default serialization for an existing data type. + +For more information, see the following resources in the .NET documentation: + +* [JSON serialization and deserialization (marshalling and unmarshalling) in .NET](/dotnet/standard/serialization/system-text-json-overview) +* [How to customize property names and values with `System.Text.Json`](/dotnet/standard/serialization/system-text-json-customize-properties) +* [How to write custom converters for JSON serialization (marshalling) in .NET](/dotnet/standard/serialization/system-text-json-converters-how-to) + +JSON serializer support for and is planned for ASP.NET Core 7.0, which is scheduled for release by the end of 2022. For more information, see [Support `DateOnly` and `TimeOnly` in `JsonSerializer` (dotnet/runtime #53539)](https://github.com/dotnet/runtime/issues/53539). + +Blazor supports optimized byte array JS interop that avoids encoding/decoding byte arrays into Base64. The app can apply custom serialization and pass the resulting bytes. For more information, see . + +Blazor supports unmarshalled JS interop when a high volume of .NET objects are rapidly serialized or when large .NET objects or many .NET objects must be serialized. For more information, see . + ## JavaScript initializers [!INCLUDE[](~/blazor/includes/js-initializers.md)] @@ -235,6 +258,27 @@ For more information, see . +## Object serialization + +Blazor uses for serialization with the following requirements and default behaviors: + +* Types must have a default constructor, [`get`/`set` accessors](/dotnet/csharp/programming-guide/classes-and-structs/using-properties) must be public, and fields are never serialized. +* Global default serialization isn't customizable to avoid breaking existing component libraries, impacts on performance and security, and reductions in reliability. +* Serializing .NET member names results in lowercase JSON key names. +* JSON is deserialized as C# instances, which permit mixed casing. Internal casting for assignment to C# model properties works as expected in spite of any case differences between JSON key names and C# property names. + + API is available for custom serialization. Properties can be annotated with a [`[JsonConverter]` attribute](xref:System.Text.Json.Serialization.JsonConverterAttribute) to override default serialization for an existing data type. + +For more information, see the following resources in the .NET documentation: + +* [JSON serialization and deserialization (marshalling and unmarshalling) in .NET](/dotnet/standard/serialization/system-text-json-overview) +* [How to customize property names and values with `System.Text.Json`](/dotnet/standard/serialization/system-text-json-customize-properties) +* [How to write custom converters for JSON serialization (marshalling) in .NET](/dotnet/standard/serialization/system-text-json-converters-how-to) + +JSON serializer support for and is planned for ASP.NET Core 7.0, which is scheduled for release by the end of 2022. For more information, see [Support `DateOnly` and `TimeOnly` in `JsonSerializer` (dotnet/runtime #53539)](https://github.com/dotnet/runtime/issues/53539). + +Blazor supports unmarshalled JS interop when a high volume of .NET objects are rapidly serialized or when large .NET objects or many .NET objects must be serialized. For more information, see . + ## Location of JavaScript Load JavaScript (JS) code using any of the following approaches: @@ -254,7 +298,7 @@ Load JavaScript (JS) code using any of the following approaches: *The approach in this section isn't generally recommended.* -Place the script (``) in the `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): +Place the script (``) in the `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): ```html @@ -275,7 +319,7 @@ Loading JS from the `` isn't the best approach for the following reasons: ### Load a script in `` markup -Place the script (``) inside the closing `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): +Place the script (``) inside the closing `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): ```html @@ -294,7 +338,7 @@ The `{webassembly|server}` placeholder in the preceding markup is either `webass ### Load a script from an external JS file (`.js`) -Place the script (``) with a script `src` path inside the closing `` tag after the Blazor script reference. +Place the script (``) with a script `src` path inside the closing `` tag after the Blazor script reference. In `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): @@ -425,6 +469,25 @@ For more information, see . +## Object serialization + +Blazor uses for serialization with the following requirements and default behaviors: + +* Types must have a default constructor, [`get`/`set` accessors](/dotnet/csharp/programming-guide/classes-and-structs/using-properties) must be public, and fields are never serialized. +* Global default serialization isn't customizable to avoid breaking existing component libraries, impacts on performance and security, and reductions in reliability. +* Serializing .NET member names results in lowercase JSON key names. +* JSON is deserialized as C# instances, which permit mixed casing. Internal casting for assignment to C# model properties works as expected in spite of any case differences between JSON key names and C# property names. + + API is available for custom serialization. Properties can be annotated with a [`[JsonConverter]` attribute](xref:System.Text.Json.Serialization.JsonConverterAttribute) to override default serialization for an existing data type. + +For more information, see the following resources in the .NET documentation: + +* [JSON serialization and deserialization (marshalling and unmarshalling) in .NET](/dotnet/standard/serialization/system-text-json-overview) +* [How to customize property names and values with `System.Text.Json`](/dotnet/standard/serialization/system-text-json-customize-properties) +* [How to write custom converters for JSON serialization (marshalling) in .NET](/dotnet/standard/serialization/system-text-json-converters-how-to) + +JSON serializer support for and is planned for ASP.NET Core 7.0, which is scheduled for release by the end of 2022. For more information, see [Support `DateOnly` and `TimeOnly` in `JsonSerializer` (dotnet/runtime #53539)](https://github.com/dotnet/runtime/issues/53539). + ## Location of JavaScript Load JavaScript (JS) code using any of the following approaches: @@ -444,7 +507,7 @@ Load JavaScript (JS) code using any of the following approaches: *The approach in this section isn't generally recommended.* -Place the script (``) in the `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): +Place the script (``) in the `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): ```html @@ -465,7 +528,7 @@ Loading JS from the `` isn't the best approach for the following reasons: ### Load a script in `` markup -Place the script (``) inside the closing `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): +Place the script (``) inside the closing `` element markup of `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server): ```html @@ -484,7 +547,7 @@ The `{webassembly|server}` placeholder in the preceding markup is either `webass ### Load a script from an external JS file (`.js`) -Place the script (``) with a script `src` path inside the closing `` tag after the Blazor script reference. +Place the script (``) with a script `src` path inside the closing `` tag after the Blazor script reference. In `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server):