Skip to content

Change Json.NET to System.Text.Json #3758

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Mar 25, 2020
Merged

Change Json.NET to System.Text.Json #3758

Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1bcc5a5
Change Json.NET to System.Text.Json
tdykstra Jan 10, 2020
4630528
move serializer advice to remarks
tdykstra Mar 25, 2020
01bfb71
fix indentation
tdykstra Mar 25, 2020
eab8044
fix typo
tdykstra Mar 25, 2020
5a47156
fix link
tdykstra Mar 25, 2020
5768f70
4.6.1 --> 4.7.2
tdykstra Mar 25, 2020
5a1d082
include use s.t.j/newtonsoft advice in summary
tdykstra Mar 25, 2020
7324933
fix typo
tdykstra Mar 25, 2020
4350324
Update xml/System.Web.Script.Serialization/JavaScriptSerializer.xml
tdykstra Mar 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions xml/System.Web.Script.Serialization/JavaScriptSerializer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,19 @@
<Interfaces />
<Docs>
<summary>
<see href="https://www.newtonsoft.com/json">Json.NET</see> should be used for serialization and deserialization. Provides serialization and deserialization functionality for AJAX-enabled applications.</summary>
Provides serialization and deserialization functionality for AJAX-enabled applications.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we are truly recommending against this in favor of Newontosft.Json for < netfx 4.7.2, should we consider obsoleting the API in .NET Core going forward or is there no need for that/the usage too high? Of course for net4.7.2+ and .net core S.T.Json is the way to go :)

cc @terrajobst, @GrabYourPitchforks

</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The <xref:System.Web.Script.Serialization.JavaScriptSerializer> class is used internally by the asynchronous communication layer to serialize and deserialize the data that is passed between the browser and the Web server. You cannot access that instance of the serializer. However, this class exposes a public API. Therefore, you can use the class when you want to work with JavaScript Object Notation (JSON) in managed code.

> [!IMPORTANT]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please share the internal docs link so I can take a quick glance at how this will end up looking like on the docs page.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ahsonkhan When the CI finishes, click on "Details", then scroll down to the preview link for this API.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see it:
https://opbuildstorageprod.blob.core.windows.net/report/2020%5C3%5C25%5C500c749d-de78-3d4a-00e4-269d599bf9ec%5CPullRequest%5C202003250031355427-3758%5Cworkflow_report.html?sv=2016-05-31&sr=b&sig=NFFwGrzp7innzIOjl3ukNRilz7HD1L0hOknTawYzb98%3D&st=2020-03-25T01%3A43%3A15Z&se=2020-04-25T01%3A48%3A15Z&sp=r

image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I got it. I took one of the other links and just navigated to the JavaScriptSerializer type:
https://review.docs.microsoft.com/en-us/dotnet/api/system.web.script.serialization.javascriptserializer?view=netframework-4.8&branch=pr-en-us-3758

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does it say that this page isn't available for netfx 4.8?
https://review.docs.microsoft.com/en-us/dotnet/api/system.text.json?view=netcore-3.1&branch=pr-en-us-3758&viewFallbackFrom=netframework-4.8
image

That could confuse users when we just said that for netfx 4.7.2+ use S.T.J. Is the platform support matrix in the docs incomplete? I would have expected anything that is netstanard2.0 compatible to have an entry in the appropriate netfx versions of the page (rather than redirecting to the .NET core version).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see it
That's odd. But I'm glad you found it by navigating into another API.
Why does it say that this page isn't available for netfx 4.8?
It's also not showing up in NetStandard2.0. Do you see the same problem in the production MS Docs site?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see the same problem in the production MS Docs site?

Yes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joelmartinez can you help us figure out why System.Text.Json is not showing up in the expected monikers?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think @mimisasouvanh might be better point of contact here.

> For .NET Framework 4.6.1 and later versions, the APIs in the <xref:System.Text.Json> namespace should be used for serialization and deserialization. For earlier versions of .NET Framework, use [Newtonsoft.Json](https://www.newtonsoft.com/json).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be .NET Framework 4.7.2 or later. Even though S.T.Json is ns2.0 compatible, 4.6.1 support has an asterisk/footnote, so I think if we are going to recommend something, let's be a bit conservative and suggest 4.7.2 instead.

https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-implementation-support

2 The versions listed here represent the rules that NuGet uses to determine whether a given .NET Standard library is applicable. While NuGet considers .NET Framework 4.6.1 as supporting .NET Standard 1.5 through 2.0, there are several issues with consuming .NET Standard libraries that were built for those versions from .NET Framework 4.6.1 projects. For .NET Framework projects that need to use such libraries, we recommend that you upgrade the project to target .NET Framework 4.7.2 or higher.


The <xref:System.Web.Script.Serialization.JavaScriptSerializer> class is used internally by the asynchronous communication layer to serialize and deserialize the data that is passed between the browser and the Web server. You cannot access that instance of the serializer. However, this class exposes a public API. Therefore, you can use the class when you want to work with JavaScript Object Notation (JSON) in managed code.

To serialize an object, use the <xref:System.Web.Script.Serialization.JavaScriptSerializer.Serialize%2A> method. To deserialize a JSON string, use the <xref:System.Web.Script.Serialization.JavaScriptSerializer.Deserialize%2A> or <xref:System.Web.Script.Serialization.JavaScriptSerializer.DeserializeObject%2A> methods. To serialize and deserialize types that are not natively supported by <xref:System.Web.Script.Serialization.JavaScriptSerializer>, implement custom converters by using the <xref:System.Web.Script.Serialization.JavaScriptConverter> class. Then register the converters by using the <xref:System.Web.Script.Serialization.JavaScriptSerializer.RegisterConverters%2A> method.
To serialize an object, use the <xref:System.Web.Script.Serialization.JavaScriptSerializer.Serialize%2A> method. To deserialize a JSON string, use the <xref:System.Web.Script.Serialization.JavaScriptSerializer.Deserialize%2A> or <xref:System.Web.Script.Serialization.JavaScriptSerializer.DeserializeObject%2A> methods. To serialize and deserialize types that are not natively supported by <xref:System.Web.Script.Serialization.JavaScriptSerializer>, implement custom converters by using the <xref:System.Web.Script.Serialization.JavaScriptConverter> class. Then register the converters by using the <xref:System.Web.Script.Serialization.JavaScriptSerializer.RegisterConverters%2A> method.

## Mapping Between Managed Types and JSON
The following table shows the mapping between managed types and JSON for the serialization process. These managed types are natively supported by <xref:System.Web.Script.Serialization.JavaScriptSerializer>. When you are deserializing from a JSON string to a managed type, the same mapping applies. However, deserialization can be asymmetric; not all serializable managed types can be deserialized from JSON.
Expand Down