diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 883dcc2ffd567..6a5bdea33724f 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2314,6 +2314,8 @@ items: href: ../standard/serialization/system-text-json/customize-properties.md - name: Ignore properties href: ../standard/serialization/system-text-json/ignore-properties.md + - name: Require properties + href: ../standard/serialization/system-text-json/required-properties.md - name: Allow invalid JSON href: ../standard/serialization/system-text-json/invalid-json.md - name: Handle overflow JSON, use JsonElement or JsonNode @@ -2328,6 +2330,8 @@ items: href: ../standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md - name: Migrate from Newtonsoft.Json href: ../standard/serialization/system-text-json/migrate-from-newtonsoft.md + - name: Visual Basic support + href: ../standard/serialization/system-text-json/visual-basic-support.md - name: Supported collection types href: ../standard/serialization/system-text-json/supported-collection-types.md - name: Advanced diff --git a/docs/standard/serialization/binary-serialization.md b/docs/standard/serialization/binary-serialization.md index 4d73e51d1ec6f..e485e4ed08cd7 100644 --- a/docs/standard/serialization/binary-serialization.md +++ b/docs/standard/serialization/binary-serialization.md @@ -14,9 +14,9 @@ author: "ViktorHofer" --- # Binary serialization -Serialization can be defined as the process of storing the state of an object to a storage medium. During this process, the public and private fields of the object and the name of the class, including the assembly containing the class, are converted to a stream of bytes, which is then written to a data stream. When the object is subsequently deserialized, an exact clone of the original object is created. +Serialization is the process of storing the state of an object to a storage medium. In binary serialization, the public and private fields of the object and the name of the class, including the assembly containing the class, are converted to a stream of bytes, which is then written to a data stream. When the object is subsequently deserialized, an exact clone of the original object is created. -When implementing a serialization mechanism in an object-oriented environment, you have to make a number of tradeoffs between ease of use and flexibility. The process can be automated to a large extent, provided you are given sufficient control over the process. For example, situations may arise where simple binary serialization is not sufficient, or there might be a specific reason to decide which fields in a class need to be serialized. The following sections examine the robust serialization mechanism provided with .NET and highlight a number of important features that allow you to customize the process to meet your needs. +When implementing a serialization mechanism in an object-oriented environment, you often need to make tradeoffs between ease of use and flexibility. The process can be automated to a large extent, provided you are given sufficient control over the process. For example, situations may arise where simple binary serialization is not sufficient, or there might be a specific reason to decide which fields in a class need to be serialized. The following sections examine the robust serialization mechanism provided with .NET and highlight a number of important features that allow you to customize the process to meet your needs. > [!NOTE] > The state of a UTF-8 or UTF-7 encoded object is not preserved if the object is serialized and deserialized using different .NET versions. @@ -344,12 +344,3 @@ Contains classes that can be used for serializing and deserializing objects. - [XML and SOAP Serialization](xml-and-soap-serialization.md)\ Describes the XML serialization mechanism that is included with the common language runtime. - -- [Security and Serialization](/previous-versions/dotnet/framework/code-access-security/security-and-serialization)\ -Describes the secure coding guidelines to follow when writing code that performs serialization. - -- [.NET Remoting](/previous-versions/dotnet/netframework-4.0/72x4h507(v=vs.100))\ -Describes the various methods in .NET Framework for remote communications. - -- [XML Web Services Created Using ASP.NET and XML Web Service Clients](/previous-versions/dotnet/netframework-4.0/7bkzywba(v=vs.100))\ -Articles that describe and explain how to program XML Web services created using ASP.NET. diff --git a/docs/standard/serialization/custom-serialization.md b/docs/standard/serialization/custom-serialization.md index 194a52f5a1507..9c6a267b34506 100644 --- a/docs/standard/serialization/custom-serialization.md +++ b/docs/standard/serialization/custom-serialization.md @@ -26,7 +26,7 @@ Custom serialization is the process of controlling the serialization and deseria [!INCLUDE [binary-serialization-warning](../../../includes/binary-serialization-warning.md)] > [!IMPORTANT] -> In versions previous to .NET Framework 4.0, serialization of custom user data in a partially trusted assembly was accomplished using `GetObjectData`. In .NET Framework version 4.0 - 4.8, that method is marked with the attribute, which prevents execution in partially trusted assemblies. To work around this condition, implement the interface. +> In versions previous to .NET Framework 4.0, serialization of custom user data in a partially trusted assembly was accomplished using `GetObjectData`. In .NET Framework versions 4.0 - 4.8, that method is marked with the attribute, which prevents execution in partially trusted assemblies. To work around this condition, implement the interface. ## Running custom methods during and after serialization @@ -173,4 +173,3 @@ End Class - [Binary Serialization](binary-serialization.md) - [XML and SOAP Serialization](xml-and-soap-serialization.md) -- [Security and Serialization](/previous-versions/dotnet/framework/code-access-security/security-and-serialization) diff --git a/docs/standard/serialization/index.md b/docs/standard/serialization/index.md index 1521bd5bd6029..8a368cec4491d 100644 --- a/docs/standard/serialization/index.md +++ b/docs/standard/serialization/index.md @@ -18,19 +18,19 @@ Serialization is the process of converting the state of an object into a form th .NET features the following serialization technologies: -- [Binary serialization](binary-serialization.md) preserves type fidelity, which is useful for preserving the state of an object between different invocations of an application. For example, you can share an object between different applications by serializing it to the Clipboard. You can serialize an object to a stream, to a disk, to memory, over the network, and so forth. Remoting uses serialization to pass objects "by value" from one computer or application domain to another. +- [JSON serialization](system-text-json/overview.md) serializes only public properties and does not preserve type fidelity. JSON is an open standard that is an attractive choice for sharing data across the web. -- [XML and SOAP serialization](xml-and-soap-serialization.md) serializes only public properties and fields and does not preserve type fidelity. This is useful when you want to provide or consume data without restricting the application that uses the data. Because XML is an open standard, it is an attractive choice for sharing data across the Web. SOAP is likewise an open standard, which makes it an attractive choice. +- [Binary serialization](binary-serialization.md) preserves *type fidelity*, which means that the complete state of the object is recorded and when you deserialize, an exact copy is created. This type of serialization is useful for preserving the state of an object between different invocations of an application. For example, you can share an object between different applications by serializing it to the Clipboard. You can serialize an object to a stream, to a disk, to memory, over the network, and so forth. Remoting uses serialization to pass objects "by value" from one computer or application domain to another. -- [JSON serialization](system-text-json/overview.md) serializes only public properties and does not preserve type fidelity. JSON is an open standard that is an attractive choice for sharing data across the web. +- [XML and SOAP serialization](xml-and-soap-serialization.md) serializes only `public` properties and fields and does not preserve type fidelity. This is useful when you want to provide or consume data without restricting the application that uses the data. Because XML is an open standard, it is an attractive choice for sharing data across the Web. SOAP is likewise an open standard, which makes it an attractive choice. ## Reference - +\ +Contains classes that can be used to serialize objects into JSON format documents or streams. + +\ Contains classes that can be used for serializing and deserializing objects. - +\ Contains classes that can be used to serialize objects into XML format documents or streams. - - -Contains classes that can be used to serialize objects into JSON format documents or streams. diff --git a/docs/standard/serialization/selective-serialization.md b/docs/standard/serialization/selective-serialization.md index 2a7009d6156c9..94149634b0312 100644 --- a/docs/standard/serialization/selective-serialization.md +++ b/docs/standard/serialization/selective-serialization.md @@ -31,4 +31,3 @@ If possible, make an object that could contain security-sensitive data nonserial - [Binary Serialization](binary-serialization.md) - [XML and SOAP Serialization](xml-and-soap-serialization.md) -- [Security and Serialization](/previous-versions/dotnet/framework/code-access-security/security-and-serialization) diff --git a/docs/standard/serialization/serialization-guidelines.md b/docs/standard/serialization/serialization-guidelines.md index bdf7b8e09540c..9ee81d9c61f42 100644 --- a/docs/standard/serialization/serialization-guidelines.md +++ b/docs/standard/serialization/serialization-guidelines.md @@ -141,4 +141,3 @@ This article lists the guidelines to consider when designing an API to be serial - [Binary Serialization](binary-serialization.md) - [.NET Remoting](/previous-versions/dotnet/netframework-4.0/72x4h507(v=vs.100)) - [XML and SOAP Serialization](xml-and-soap-serialization.md) -- [Security and Serialization](/previous-versions/dotnet/framework/code-access-security/security-and-serialization) diff --git a/docs/standard/serialization/system-text-json/converters-how-to.md b/docs/standard/serialization/system-text-json/converters-how-to.md index 2111e28d95aa1..74c8faf813021 100644 --- a/docs/standard/serialization/system-text-json/converters-how-to.md +++ b/docs/standard/serialization/system-text-json/converters-how-to.md @@ -53,7 +53,7 @@ You can also write custom converters to customize or extend `System.Text.Json` w In the code you write for a custom converter, be aware of the substantial performance penalty for using new instances. For more information, see [Reuse JsonSerializerOptions instances](configure-options.md#reuse-jsonserializeroptions-instances). -Visual Basic can't be used to write custom converters but can call converters that are implemented in C# libraries. For more information, see [Visual Basic support](how-to.md#visual-basic-support). +Visual Basic can't be used to write custom converters but can call converters that are implemented in C# libraries. For more information, see [Visual Basic support](visual-basic-support.md). ## Custom converter patterns diff --git a/docs/standard/serialization/system-text-json/how-to.md b/docs/standard/serialization/system-text-json/how-to.md index 9e3e1878bcb47..37e0f8b2b711a 100644 --- a/docs/standard/serialization/system-text-json/how-to.md +++ b/docs/standard/serialization/system-text-json/how-to.md @@ -40,15 +40,6 @@ The code samples in this article: :::code language="csharp" source="snippets/system-text-json-how-to/csharp/SerializeBasic.cs" id="wf"::: :::code language="vb" source="snippets/system-text-json-how-to/vb/WeatherForecast.vb" id="WF"::: -## Visual Basic support - -Parts of System.Text.Json use [ref structs](../../../csharp/language-reference/builtin-types/ref-struct.md), which are not supported by Visual Basic. If you try to use System.Text.Json ref struct APIs with Visual Basic you get BC40000 compiler errors. The error message indicates that the problem is an obsolete API, but the actual issue is lack of ref struct support in the compiler. The following parts of System.Text.Json aren't usable from Visual Basic: - -* The class. Since the method takes a `Utf8JsonReader` parameter, this limitation means you can't use Visual Basic to write custom converters. A workaround for this is to implement custom converters in a C# library assembly, and reference that assembly from your VB project. This assumes that all you do in Visual Basic is register the converters into the serializer. You can't call the `Read` methods of the converters from Visual Basic code. -* Overloads of other APIs that include a type. Most methods include overloads that use `String` instead of `ReadOnlySpan`. - -These restrictions are in place because ref structs cannot be used safely without language support, even when just "passing data through." Subverting this error will result in Visual Basic code that can corrupt memory and should not be done. - ## Namespaces The namespace contains all the entry points and the main types. The namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. The code examples shown in this article require `using` directives for one or both of these namespaces: @@ -170,7 +161,9 @@ You can [implement custom converters](converters-how-to.md) to handle additional ## How to read JSON as .NET objects (deserialize) -A common way to deserialize JSON is to first create a class with properties and fields that represent one or more of the JSON properties. Then, to deserialize from a string or a file, call the method. For the generic overloads, you pass the type of the class you created as the generic type parameter. For the non-generic overloads, you pass the type of the class you created as a method parameter. You can deserialize either synchronously or asynchronously. Any JSON properties that aren't represented in your class are ignored. +A common way to deserialize JSON is to first create a class with properties and fields that represent one or more of the JSON properties. Then, to deserialize from a string or a file, call the method. For the generic overloads, you pass the type of the class you created as the generic type parameter. For the non-generic overloads, you pass the type of the class you created as a method parameter. You can deserialize either synchronously or asynchronously. + +Any JSON properties that aren't represented in your class are ignored. Also, if any properties on the type are [required](required-properties.md) but not present in the JSON payload, deserialization will fail. The following example shows how to deserialize a JSON string: diff --git a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md index 13764be824dc2..6966590433106 100644 --- a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md +++ b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md @@ -28,7 +28,7 @@ We're investing in adding the features that have most often been requested. If y Most of this article is about how to use the API, but it also includes guidance on how to use the (which represents the Document Object Model or DOM), , and types. -In Visual Basic, you can't use , which also means you can't write custom converters. Most of the workarounds presented here require that you write custom converters. You can write a custom converter in C# and register it in a Visual Basic project. For more information, see [Visual Basic support](how-to.md#visual-basic-support). +In Visual Basic, you can't use , which also means you can't write custom converters. Most of the workarounds presented here require that you write custom converters. You can write a custom converter in C# and register it in a Visual Basic project. For more information, see [Visual Basic support](visual-basic-support.md). ## Table of differences between Newtonsoft.Json and System.Text.Json diff --git a/docs/standard/serialization/system-text-json/overview.md b/docs/standard/serialization/system-text-json/overview.md index ba7444e6edfd4..5a31683f583e2 100644 --- a/docs/standard/serialization/system-text-json/overview.md +++ b/docs/standard/serialization/system-text-json/overview.md @@ -13,21 +13,17 @@ helpviewer_keywords: # JSON serialization and deserialization (marshalling and unmarshalling) in .NET - overview -The `System.Text.Json` namespace provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). +The `System.Text.Json` namespace provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). *Serialization* is the process of converting the state of an object, that is, the values of its properties, into a form that can be stored or transmitted. The serialized form doesn't include any information about an object's associated methods. *Deserialization* reconstructs an object from the serialized form. -The library design emphasizes high performance and low memory allocation over an extensive feature set. Built-in UTF-8 support optimizes the process of reading and writing JSON text encoded as UTF-8, which is the most prevalent encoding for data on the web and files on disk. +The `System.Text.Json` library design emphasizes high performance and low memory allocation over an extensive feature set. Built-in UTF-8 support optimizes the process of reading and writing JSON text encoded as UTF-8, which is the most prevalent encoding for data on the web and files on disk. The library also provides classes for working with an in-memory [document object model (DOM)](use-dom-utf8jsonreader-utf8jsonwriter.md#json-dom-choices). This feature enables random access to the elements in a JSON file or string. -There are some limitations on what parts of the library that you can use from Visual Basic code. For more information, see [Visual Basic support](how-to.md#visual-basic-support). - -## Run-time reflection vs. compile-time source generation - -By default, `System.Text.Json` uses run-time [reflection](../../../csharp/programming-guide/concepts/reflection.md) to gather the metadata it needs to access properties of objects for serialization and deserialization. As an alternative, `System.Text.Json` can use the C# [source generation](../../../csharp/roslyn-sdk/source-generators-overview.md) feature to improve performance, reduce private memory usage, and facilitate [assembly trimming](../../../core/deploying/trimming/trim-self-contained.md), which reduces app size. For more information, see [How to choose reflection or source generation in System.Text.Json](source-generation-modes.md). +There are some limitations on what parts of the library you can use from Visual Basic code. For more information, see [Visual Basic support](visual-basic-support.md). ## How to get the library -The library is built-in as part of the shared framework for .NET Core 3.0 and later versions. The source generation feature is built-in as part of the shared framework for .NET 6 and later versions. Use of source generation requires .NET 5 SDK or later. +The library is built-in as part of the shared framework for .NET Core 3.0 and later versions. The [source generation feature](source-generation-modes.md#source-generation---metadata-collection-mode) is built-in as part of the shared framework for .NET 6 and later versions. Use of source generation requires .NET 5 SDK or later. For framework versions earlier than .NET Core 3.0, install the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json) NuGet package. The package supports: @@ -36,6 +32,10 @@ For framework versions earlier than .NET Core 3.0, install the [System.Text.Json * .NET Core 2.1 and later * .NET 5 and later +## Run-time reflection vs. compile-time source generation + +By default, `System.Text.Json` uses [reflection](../../../csharp/programming-guide/concepts/reflection.md) to gather the metadata it needs to access properties of objects for serialization and deserialization *at run time*. As an alternative, `System.Text.Json` can use the C# [source generation](../../../csharp/roslyn-sdk/source-generators-overview.md) feature to improve performance, reduce private memory usage, and facilitate [assembly trimming](../../../core/deploying/trimming/trim-self-contained.md), which reduces app size. For more information, see [How to choose reflection or source generation in System.Text.Json](source-generation-modes.md). + ## Security information For information about security threats that were considered when designing , and how they can be mitigated, see [`System.Text.Json` Threat Model](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/docs/ThreatModel.md). @@ -68,6 +68,7 @@ The `System.Text.Json` types are thread-safe, including: * [Enable case-insensitive matching](character-casing.md) * [Customize property names and values](customize-properties.md) * [Ignore properties](ignore-properties.md) +* [Require properties](required-properties.md) * [Allow invalid JSON](invalid-json.md) * [Handle overflow JSON or use JsonElement or JsonNode](handle-overflow.md) * [Preserve references and handle circular references](preserve-references.md) diff --git a/docs/standard/serialization/system-text-json/required-properties.md b/docs/standard/serialization/system-text-json/required-properties.md new file mode 100644 index 0000000000000..e7976ecc1d63a --- /dev/null +++ b/docs/standard/serialization/system-text-json/required-properties.md @@ -0,0 +1,51 @@ +--- +title: Require properties for deserialization +description: "Learn how to mark properties as required for deserialization to succeed." +ms.date: 09/21/2022 +no-loc: [System.Text.Json, Newtonsoft.Json] +--- +# Required properties + +Starting in .NET 7, you can mark certain properties to signify that they must be present in the JSON payload for deserialization to succeed. If one or more of these required properties is not present, the methods throw a . + +There are two ways to mark a property or field as required for JSON deserialization: + +- By adding the [required modifier](../../../csharp/language-reference/keywords/required.md), which is new in C# 11. +- By annotating it with , which is new in .NET 7. + +From the serializer's perspective, these two demarcations are equivalent and both map to the same piece of metadata, which is . In most cases, you'd simply use the built-in C# keyword. However, in the following cases, you should use instead: + +- If you're using a programming language other than C# or a down-level version of C#. +- If you only want the requirement to apply to JSON deserialization. +- If you're using `System.Text.Json` serialization in [source generation](source-generation-modes.md#source-generation---metadata-collection-mode) mode. In this case, your code won't compile if you use the `required` modifier, as source generation occurs at compile time. + +The following code snippet shows an example of a property modified with the `required` keyword. This property must be present in the JSON payload for deserialization to succeed. + +```csharp +using System.Text.Json; + +// The following line throws a JsonException at run time. +Console.WriteLine(JsonSerializer.Deserialize("""{"Age": 42}""")); + +public class Person +{ + public required string Name { get; set; } + public int Age { get; set; } +} +``` + +Alternatively, you can use : + +```csharp +using System.Text.Json; + +// The following line throws a JsonException at run time. +Console.WriteLine(JsonSerializer.Deserialize("""{"Age": 42}""")); + +public class Person +{ + [JsonRequired] + public string Name { get; set; } + public int Age { get; set; } +} +``` diff --git a/docs/standard/serialization/system-text-json/source-generation-modes.md b/docs/standard/serialization/system-text-json/source-generation-modes.md index b2311dfd5de31..d947922865732 100644 --- a/docs/standard/serialization/system-text-json/source-generation-modes.md +++ b/docs/standard/serialization/system-text-json/source-generation-modes.md @@ -65,22 +65,22 @@ By default, `JsonSerializer` collects metadata at run time by using [reflection] ## Source generation - metadata collection mode -You can use source generation to move the metadata collection process from run time to compile time. During compilation, the metadata is collected and source code files are generated. The generated source code files are automatically compiled as an integral part of the application. This compile-time metadata collection eliminates run-time metadata collection, which improves performance of both serialization and deserialization. +You can use source generation to move the metadata collection process from run time to compile time. During compilation, the metadata is collected and source code files are generated. The generated source code files are automatically compiled as an integral part of the application. This technique eliminates run-time metadata collection, which improves performance of both serialization and deserialization. The performance improvements provided by source generation can be substantial. For example, [test results](https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-source-generator/#how-source-generation-provides-benefits) have shown up to 40% or more startup time reduction, private memory reduction, throughput speed increase (in serialization optimization mode), and app size reduction. -## Source generation - known issues +### Known issues -Reflection mode supports the use of non-public accessors of public properties. For example, you can apply [[JsonInclude]](xref:System.Text.Json.Serialization.JsonIncludeAttribute) to a property that has a `private` setter or getter. Source generation mode supports only public or internal accessors of public properties. Use of `[JsonInclude]` on non-public accessors in source generation mode results in a `NotSupportedException` at run time. +Only `public` properties and fields are supported by default\* in either serialization mode. However, reflection mode supports the use of `private` *accessors* while source-generation mode does not. For example, you can apply the [JsonInclude attribute](xref:System.Text.Json.Serialization.JsonIncludeAttribute) to a property that has a `private` setter or getter and it will be serialized in reflection mode. Source-generation mode supports only `public` or `internal` accessors of `public` properties. If you set `[JsonInclude]` on non-public accessors and choose source-generation mode, a `NotSupportedException` will be thrown at run time. -Reflection mode also supports deserialization to init-only properties. Source generation doesn't support this, because the metadata-only mode required for deserialization can't express the required initialization statically in source code. The reflection serializer uses run-time reflection to set properties after construction. +Reflection mode also supports deserialization to [init-only properties](../../../csharp/language-reference/keywords/init.md). Source generation doesn't support this, because the metadata-only mode required for deserialization can't express the required initialization statically in source code. The reflection serializer uses run-time reflection to set properties after construction. In both reflection and source generation modes: -* Only public properties and public fields are supported. -* Only public constructors can be used for deserialization. +* Only `public` properties and `public` fields are supported\*. +* Only `public` constructors can be used for deserialization. -For information about the outstanding request to add support for non-public members, see GitHub issue [dotnet/runtime#31511](https://github.com/dotnet/runtime/issues/31511). Even if that request is implemented, source generation mode will still be limited to support for public members. +\*Starting in .NET 7, you can use custom JSON contracts to include `private` properties and fields in serialization. For information about other known issues with source generation, see the [GitHub issues that are labeled "source-generator"](https://github.com/dotnet/runtime/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-System.Text.Json+label%3Asource-generator) in the *dotnet/runtime* repository. diff --git a/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md b/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md index 8e0c7e9f6db6c..f5461bc399fc9 100644 --- a/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md +++ b/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md @@ -249,7 +249,7 @@ To write `Timespan`, `Uri`, or `char` values, format them as strings (by calling ## Use `Utf8JsonReader` - is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a `ReadOnlySpan` or `ReadOnlySequence`. The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. The method uses `Utf8JsonReader` under the covers. The `Utf8JsonReader` can't be used directly from Visual Basic code. For more information, see [Visual Basic support](how-to.md#visual-basic-support). + is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a `ReadOnlySpan` or `ReadOnlySequence`. The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. The method uses `Utf8JsonReader` under the covers. The `Utf8JsonReader` can't be used directly from Visual Basic code. For more information, see [Visual Basic support](visual-basic-support.md). The following example shows how to use the class: diff --git a/docs/standard/serialization/system-text-json/visual-basic-support.md b/docs/standard/serialization/system-text-json/visual-basic-support.md new file mode 100644 index 0000000000000..399fbb2579b0d --- /dev/null +++ b/docs/standard/serialization/system-text-json/visual-basic-support.md @@ -0,0 +1,15 @@ +--- +title: Visual Basic support for System.Text.Json +description: Learn which parts of the System.Text.Json namespace aren't supported in Visual Basic. +ms.date: 09/21/2022 +no-loc: [System.Text.Json, Newtonsoft.Json] +--- + +# Visual Basic support + +Parts of System.Text.Json use [ref structs](../../../csharp/language-reference/builtin-types/ref-struct.md), which are not supported by Visual Basic. If you try to use System.Text.Json ref struct APIs with Visual Basic you get BC40000 compiler errors. The error message indicates that the problem is an obsolete API, but the actual issue is lack of ref struct support in the compiler. The following parts of System.Text.Json aren't usable from Visual Basic: + +* The class. Since the method takes a `Utf8JsonReader` parameter, this limitation means you can't use Visual Basic to write custom converters. A workaround for this is to implement custom converters in a C# library assembly, and reference that assembly from your VB project. This assumes that all you do in Visual Basic is register the converters into the serializer. You can't call the `Read` methods of the converters from Visual Basic code. +* Overloads of other APIs that include a type. Most methods include overloads that use `String` instead of `ReadOnlySpan`. + +These restrictions are in place because ref structs cannot be used safely without language support, even when just "passing data through." Subverting this error will result in Visual Basic code that can corrupt memory and should not be done.