From 1c1a1c22e6b78b84a9886fd4f0e59b788efd26a3 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sun, 19 Jan 2025 10:37:27 -0800 Subject: [PATCH 1/3] move http example out of main overview page for STJ --- docs/fundamentals/toc.yml | 2 ++ .../system-text-json/httpclient-extensions.md | 16 +++++++++++++ .../system-text-json/overview.md | 23 ++++--------------- 3 files changed, 23 insertions(+), 18 deletions(-) create mode 100644 docs/standard/serialization/system-text-json/httpclient-extensions.md diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index f3c21c755d52a..d00ba970ad050 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -761,6 +761,8 @@ items: href: ../standard/serialization/system-text-json/preserve-references.md - name: Serialize polymorphic types href: ../standard/serialization/system-text-json/polymorphism.md + - name: Serialize/deserialize network payloads + href: ../standard/serialization/system-text-json/httpclient-extensions.md - name: Read/write JSON without using JsonSerializer items: - name: Use DOM diff --git a/docs/standard/serialization/system-text-json/httpclient-extensions.md b/docs/standard/serialization/system-text-json/httpclient-extensions.md new file mode 100644 index 0000000000000..a0e90169b94ea --- /dev/null +++ b/docs/standard/serialization/system-text-json/httpclient-extensions.md @@ -0,0 +1,16 @@ +--- +title: "Serialize and deserialize network payloads" +description: Learn how to serialize and deserialize JSON payloads from the network in a single line of code using extension methods on HttpClient. +ms.date: 01/19/2025 +dev_langs: + - CSharp + - VB +--- +# Serialize and deserialize network payloads + +Serializing and deserializing JSON payloads from the network are common operations. Extension methods on [HttpClient](xref:System.Net.Http.Json.HttpClientJsonExtensions) and [HttpContent](xref:System.Net.Http.Json.HttpContentJsonExtensions) let you do these operations in a single line of code. These extension methods use [web defaults for JsonSerializerOptions](configure-options.md#web-defaults-for-jsonserializeroptions). + +The following example illustrates use of and : + +:::code language="csharp" source="snippets/how-to-contd/csharp/HttpClientExtensionMethods.cs" highlight="23,30"::: +:::code language="vb" source="snippets/how-to-contd/vb/HttpClientExtensionMethods.vb"::: diff --git a/docs/standard/serialization/system-text-json/overview.md b/docs/standard/serialization/system-text-json/overview.md index b4b28779ed549..47d9912408dd6 100644 --- a/docs/standard/serialization/system-text-json/overview.md +++ b/docs/standard/serialization/system-text-json/overview.md @@ -1,5 +1,5 @@ --- -title: "Serialize and deserialize JSON using C# - .NET" +title: "Serialize and deserialize JSON using C#" description: This overview describes the System.Text.Json namespace functionality for serializing to and deserializing from JSON in .NET. ms.date: 10/18/2021 no-loc: [System.Text.Json, Newtonsoft.Json] @@ -13,9 +13,9 @@ helpviewer_keywords: - "objects, serializing" --- -# JSON serialization and deserialization (marshalling and unmarshalling) in .NET - overview +# JSON serialization and deserialization in .NET - overview -The 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 namespace provides functionality for serializing to and deserializing from (or marshalling and unmarshalling) 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 `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. @@ -31,15 +31,13 @@ For framework versions earlier than .NET Core 3.0, install the [System.Text.Json * .NET Standard 2.0 and later * .NET Framework 4.6.2 and later -* .NET Core 2.1 and later -* .NET 5 and later +* .NET 8 and later ## Namespaces and APIs * 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. +* The namespace contains extension methods for [serializing and deserializing JSON payloads from the network](httpclient-extensions.md). > [!IMPORTANT] > @@ -48,17 +46,6 @@ The code examples shown in this article require `using` directives for one or bo > * Attributes from the namespace. > * The attribute and the interface. These types are used only for [Binary and XML serialization](/previous-versions/dotnet/fundamentals/serialization/binary/binary-serialization). -### HttpClient and HttpContent extension methods - -Serializing and deserializing JSON payloads from the network are common operations. Extension methods on [HttpClient](xref:System.Net.Http.Json.HttpClientJsonExtensions) and [HttpContent](xref:System.Net.Http.Json.HttpContentJsonExtensions) let you do these operations in a single line of code. These extension methods use [web defaults for JsonSerializerOptions](configure-options.md#web-defaults-for-jsonserializeroptions). - -The following example illustrates use of and : - -:::code language="csharp" source="snippets/how-to-contd/csharp/HttpClientExtensionMethods.cs" highlight="23,30"::: -:::code language="vb" source="snippets/how-to-contd/vb/HttpClientExtensionMethods.vb" ::: - -There are also extension methods for System.Text.Json on [HttpContent](xref:System.Net.Http.Json.HttpContentJsonExtensions). - ## Reflection vs. source generation By default, `System.Text.Json` gathers the metadata it needs to access properties of objects for serialization and deserialization *at run time* using [reflection](/dotnet/csharp/advanced-topics/reflection-and-attributes/). As an alternative, `System.Text.Json` can use the C# [source generation](../../../csharp/roslyn-sdk/index.md#source-generators) feature to improve performance, reduce private memory usage, and facilitate [assembly trimming](../../../core/deploying/trimming/trim-self-contained.md), which reduces app size. From 00dd8b2aa5edcbef150fce48c2b5d215cdf7e783 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sun, 19 Jan 2025 10:43:34 -0800 Subject: [PATCH 2/3] update date --- docs/standard/serialization/system-text-json/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/serialization/system-text-json/overview.md b/docs/standard/serialization/system-text-json/overview.md index 47d9912408dd6..93983fb484184 100644 --- a/docs/standard/serialization/system-text-json/overview.md +++ b/docs/standard/serialization/system-text-json/overview.md @@ -1,7 +1,7 @@ --- title: "Serialize and deserialize JSON using C#" description: This overview describes the System.Text.Json namespace functionality for serializing to and deserializing from JSON in .NET. -ms.date: 10/18/2021 +ms.date: 01/19/2025 no-loc: [System.Text.Json, Newtonsoft.Json] dev_langs: - CSharp From a25b9d74ce28accddeaca0661b96ed45cc395813 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 21 Jan 2025 11:23:10 -0800 Subject: [PATCH 3/3] fix build warning and change H1 --- docs/core/whats-new/dotnet-5.md | 2 +- docs/fundamentals/toc.yml | 2 +- .../serialization/system-text-json/httpclient-extensions.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/whats-new/dotnet-5.md b/docs/core/whats-new/dotnet-5.md index 416202fac3f94..6c60ce3d6d844 100644 --- a/docs/core/whats-new/dotnet-5.md +++ b/docs/core/whats-new/dotnet-5.md @@ -134,7 +134,7 @@ For more information on project templates from the .NET CLI, see [`dotnet new`]( There are new features in and for [System.Text.Json](../../standard/serialization/system-text-json/overview.md): - [Preserve references and handle circular references](../../standard/serialization/system-text-json/preserve-references.md) -- [HttpClient and HttpContent extension methods](../../standard/serialization/system-text-json/overview.md#httpclient-and-httpcontent-extension-methods) +- [Serialization extension methods on HttpClient](../../standard/serialization/system-text-json/httpclient-extensions.md) - [Allow or write numbers in quotes](../../standard/serialization/system-text-json/invalid-json.md#allow-or-write-numbers-in-quotes) - [Support immutable types and C# 9 Records](../../standard/serialization/system-text-json/immutability.md) - [Support non-public property accessors](../../standard/serialization/system-text-json/immutability.md) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index d00ba970ad050..b10289eafdfa6 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -761,7 +761,7 @@ items: href: ../standard/serialization/system-text-json/preserve-references.md - name: Serialize polymorphic types href: ../standard/serialization/system-text-json/polymorphism.md - - name: Serialize/deserialize network payloads + - name: Use extension methods on HttpClient href: ../standard/serialization/system-text-json/httpclient-extensions.md - name: Read/write JSON without using JsonSerializer items: diff --git a/docs/standard/serialization/system-text-json/httpclient-extensions.md b/docs/standard/serialization/system-text-json/httpclient-extensions.md index a0e90169b94ea..c3d6e4d267b8b 100644 --- a/docs/standard/serialization/system-text-json/httpclient-extensions.md +++ b/docs/standard/serialization/system-text-json/httpclient-extensions.md @@ -1,12 +1,12 @@ --- -title: "Serialize and deserialize network payloads" -description: Learn how to serialize and deserialize JSON payloads from the network in a single line of code using extension methods on HttpClient. +title: "Serialization extension methods on HttpClient" +description: Learn how to serialize and deserialize JSON payloads from the network in a single line of code using extension methods on HttpClient and HttpContent. ms.date: 01/19/2025 dev_langs: - CSharp - VB --- -# Serialize and deserialize network payloads +# Serialization extension methods on HttpClient Serializing and deserializing JSON payloads from the network are common operations. Extension methods on [HttpClient](xref:System.Net.Http.Json.HttpClientJsonExtensions) and [HttpContent](xref:System.Net.Http.Json.HttpContentJsonExtensions) let you do these operations in a single line of code. These extension methods use [web defaults for JsonSerializerOptions](configure-options.md#web-defaults-for-jsonserializeroptions).