What is the difference between Serialization and Marshaling?

How to serialize and deserialize JSON using C# - .NET | Microsoft Docs https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?pivots=dotnet-5-0

This article shows how to use the System.Text.Json namespace to serialize to and deserialize from JavaScript Object Notation (JSON). If you're porting existing code from Newtonsoft.Json, see How to migrate to System.Text.Json.

The directions and sample code use the library directly, not through a framework such as ASP.NET Core.

Most of the serialization sample code sets JsonSerializerOptions.WriteIndented to true to "pretty-print" the JSON (with indentation and whitespace for human readability). For production use, you would typically accept the default value of false for this setting.

This article shows how to use the System.Text.Json namespace to serialize to and deserialize from JavaScript Object Notation (JSON). If you're porting existing code from Newtonsoft.Json, see How to migrate to System.Text.Json.

The directions and sample code use the library directly, not through a framework such as ASP.NET Core.

Most of the serialization sample code sets JsonSerializerOptions.WriteIndented to true to "pretty-print" the JSON (with indentation and whitespace for human readability). For production use, you would typically accept the default value of false for this setting.

The code examples refer to the following class and variants of it:

C#Copy

 

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

Namespaces

The System.Text.Json namespace contains all the entry points and the main types. The System.Text.Json.Serialization 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:

C#Copy

 

using System.Text.Json;
using System.Text.Json.Serialization;

Important

Attributes from the System.Runtime.Serialization namespace aren't supported in System.Text.Json.

How to write .NET objects as JSON (serialize)

To write JSON to a string or to a file, call the JsonSerializer.Serialize method.

The following example creates JSON as a string:

C#Copy

 

string jsonString = JsonSerializer.Serialize(weatherForecast);

The following example uses synchronous code to create a JSON file:

C#Copy

 

jsonString = JsonSerializer.Serialize(weatherForecast);
File.WriteAllText(fileName, jsonString);

The following example uses asynchronous code to create a JSON file:

C#Copy

 

using FileStream createStream = File.Create(fileName);
await JsonSerializer.SerializeAsync(createStream, weatherForecast);

The preceding examples use type inference for the type being serialized. An overload of Serialize() takes a generic type parameter:

C#Copy

 

jsonString = JsonSerializer.Serialize<WeatherForecastWithPOCOs>(weatherForecast);

Serialization example

Here's an example class that contains collection-type properties and a user-defined type:

C#Copy

 

public class WeatherForecastWithPOCOs
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
    public string SummaryField;
    public IList<DateTimeOffset> DatesAvailable { get; set; }
    public Dictionary<string, HighLowTemps> TemperatureRanges { get; set; }
    public string[] SummaryWords { get; set; }
}

public class HighLowTemps
{
    public int High { get; set; }
    public int Low { get; set; }
}

Tip

"POCO" stands for plain old CLR object. A POCO is a .NET type that doesn't depend on any framework-specific types, for example, through inheritance or attributes.

The JSON output from serializing an instance of the preceding type looks like the following example. The JSON output is minified (whitespace, indentation, and new-line characters are removed) by default:

JSONCopy

 

{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot","DatesAvailable":["2019-08-01T00:00:00-07:00","2019-08-02T00:00:00-07:00"],"TemperatureRanges":{"Cold":{"High":20,"Low":-10},"Hot":{"High":60,"Low":20}},"SummaryWords":["Cool","Windy","Humid"]}

The following example shows the same JSON, but formatted (that is, pretty-printed with whitespace and indentation):

JSONCopy

 

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "DatesAvailable": [
    "2019-08-01T00:00:00-07:00",
    "2019-08-02T00:00:00-07:00"
  ],
  "TemperatureRanges": {
    "Cold": {
      "High": 20,
      "Low": -10
    },
    "Hot": {
      "High": 60,
      "Low": 20
    }
  },
  "SummaryWords": [
    "Cool",
    "Windy",
    "Humid"
  ]
}

Serialize to UTF-8

To serialize to UTF-8, call the JsonSerializer.SerializeToUtf8Bytes method:

C#Copy

 

byte[] jsonUtf8Bytes;
var options = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast, options);

A Serialize overload that takes a Utf8JsonWriter is also available.

Serializing to UTF-8 is about 5-10% faster than using the string-based methods. The difference is because the bytes (as UTF-8) don't need to be converted to strings (UTF-16).

Serialization behavior

• By default, all public properties are serialized. You can specify properties to ignore.
• The default encoder escapes non-ASCII characters, HTML-sensitive characters within the ASCII-range, and characters that must be escaped according to the RFC 8259 JSON spec.
• By default, JSON is minified. You can pretty-print the JSON.
• By default, casing of JSON names matches the .NET names. You can customize JSON name casing.
• By default, circular references are detected and exceptions thrown. You can preserve references and handle circular references.
• By default, fields are ignored. You can include fields.

When you use System.Text.Json indirectly in an ASP.NET Core app, some default behaviors are different. For more information, see Web defaults for JsonSerializerOptions.

Supported types include:

• .NET primitives that map to JavaScript primitives, such as numeric types, strings, and Boolean.
• User-defined plain old CLR objects (POCOs).
• One-dimensional and jagged arrays (T[][]).
• Collections and dictionaries from the following namespaces.
  • System.Collections
  • System.Collections.Generic
  • System.Collections.Immutable
  • System.Collections.Concurrent
  • System.Collections.Specialized
  • System.Collections.ObjectModel

You can implement custom converters to handle additional types or to provide functionality that isn't supported by the built-in converters.

How to read JSON as .NET objects (deserialize)

To deserialize from a string or a file, call the JsonSerializer.Deserialize method.

The following example reads JSON from a string and creates an instance of the WeatherForecastWithPOCOs class shown earlier for the serialization example:

C#Copy

 

weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithPOCOs>(jsonString);

To deserialize from a file by using synchronous code, read the file into a string, as shown in the following example:

C#Copy

 

jsonString = File.ReadAllText(fileName);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString);

To deserialize from a file by using asynchronous code, call the DeserializeAsync method:

C#Copy

 

using FileStream openStream = File.OpenRead(fileName);
weatherForecast = await JsonSerializer.DeserializeAsync<WeatherForecast>(openStream);

Deserialize from UTF-8

To deserialize from UTF-8, call a JsonSerializer.Deserialize overload that takes a ReadOnlySpan<byte> or a Utf8JsonReader, as shown in the following examples. The examples assume the JSON is in a byte array named jsonUtf8Bytes.

C#Copy

 

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan);

C#Copy

 

var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader);

Deserialization behavior

The following behaviors apply when deserializing JSON:

• By default, property name matching is case-sensitive. You can specify case-insensitivity.
• If the JSON contains a value for a read-only property, the value is ignored and no exception is thrown.
• Non-public constructors are ignored by the serializer.
• Deserialization to immutable objects or read-only properties is supported. See Immutable types and Records.
• By default, enums are supported as numbers. You can serialize enum names as strings.
• By default, fields are ignored. You can include fields.
• By default, comments or trailing commas in the JSON throw exceptions. You can allow comments and trailing commas.
• The default maximum depth is 64.

When you use System.Text.Json indirectly in an ASP.NET Core app, some default behaviors are different. For more information, see Web defaults for JsonSerializerOptions.

You can implement custom converters to provide functionality that isn't supported by the built-in converters.

Serialize to formatted JSON

To pretty-print the JSON output, set JsonSerializerOptions.WriteIndented to true:

C#Copy

 

var options = new JsonSerializerOptions
{
    WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Here's an example type to be serialized and pretty-printed JSON output:

C#Copy

 

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string Summary { get; set; }
}

JSONCopy

 

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Include fields

Use the JsonSerializerOptions.IncludeFields global setting or the [JsonInclude] attribute to include fields when serializing or deserializing, as shown in the following example:

C#Copy

 

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace Fields
{
    public class Forecast
    {
        public DateTime Date;
        public int TemperatureC;
        public string Summary;
    }

    public class Forecast2
    {
        [JsonInclude]
        public DateTime Date;
        [JsonInclude]
        public int TemperatureC;
        [JsonInclude]
        public string Summary;
    }

    public class Program
    {
        public static void Main()
        {
            var json =
                @"{""Date"":""2020-09-06T11:31:01.923395-07:00"",""TemperatureC"":-1,""Summary"":""Cold""} ";
            Console.WriteLine($"Input JSON: {json}");

            var options = new JsonSerializerOptions
            {
                IncludeFields = true,
            };
            var forecast = JsonSerializer.Deserialize<Forecast>(json, options);

            Console.WriteLine($"forecast.Date: {forecast.Date}");
            Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
            Console.WriteLine($"forecast.Summary: {forecast.Summary}");

            var roundTrippedJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine($"Output JSON: {roundTrippedJson}");

            options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
            var forecast2 = JsonSerializer.Deserialize<Forecast2>(json);

            Console.WriteLine($"forecast2.Date: {forecast2.Date}");
            Console.WriteLine($"forecast2.TemperatureC: {forecast2.TemperatureC}");
            Console.WriteLine($"forecast2.Summary: {forecast2.Summary}");

            roundTrippedJson =
                JsonSerializer.Serialize<Forecast2>(forecast2, options);

            Console.WriteLine($"Output JSON: {roundTrippedJson}");
        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
//forecast.Date: 9/6/2020 11:31:01 AM
//forecast.TemperatureC: -1
//forecast.Summary: Cold
//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}
//forecast2.Date: 9/6/2020 11:31:01 AM
//forecast2.TemperatureC: -1
//forecast2.Summary: Cold
//Output JSON: { "date":"2020-09-06T11:31:01.923395-07:00","temperatureC":-1,"summary":"Cold"}

To ignore read-only fields, use the JsonSerializerOptions.IgnoreReadOnlyFields global setting.

HttpClient and HttpContent extension methods

Serializing and deserializing JSON payloads from the network are common operations. Extension methods on HttpClient and HttpContent let you do these operations in a single line of code. These extension methods use web defaults for JsonSerializerOptions.

The following example illustrates use of HttpClientJsonExtensions.GetFromJsonAsync and HttpClientJsonExtensions.PostAsJsonAsync:

C#Copy

 

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace HttpClientExtensionMethods
{
    public class User
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Username { get; set; }
        public string Email { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            using HttpClient client = new()
            {
                BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
            };

            // Get the user information.
            User user = await client.GetFromJsonAsync<User>("users/1");
            Console.WriteLine($"Id: {user.Id}");
            Console.WriteLine($"Name: {user.Name}");
            Console.WriteLine($"Username: {user.Username}");
            Console.WriteLine($"Email: {user.Email}");

            // Post a new user.
            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
            Console.WriteLine(
                $"{(response.IsSuccessStatusCode ? "Success" : "Error")} - {response.StatusCode}");
        }
    }
}

// Produces output like the following example but with different names:
//
//Id: 1
//Name: Tyler King
//Username: Tyler
//Email: Tyler @contoso.com
//Success - Created

There are also extension methods for System.Text.Json on HttpContent.

See also

• System.Text.Json overview
• How to write custom converters
• How to migrate from Newtonsoft.Json
• DateTime and DateTimeOffset support in System.Text.Json
• System.Text.Json API reference

Marshal vs Serialize - What's the difference? | WikiDiff https://wikidiff.com/marshal/serialize

terminology - What is the difference between Serialization and Marshaling? - Stack Overflow https://stackoverflow.com/questions/770474/what-is-the-difference-between-serialization-and-marshaling

http://en.wikipedia.org/wiki/Marshalling_(computer_science) http://en.wikipedia.org/wiki/Marshalling_(computer_science)

In computer science, marshalling or marshaling is the process of transforming the memory representation of an object to a data format suitable for storage or transmission,^{[citation needed]} and it is typically used when data must be moved between different parts of a computer program or from one program to another. Marshalling is similar to serialization and is used to communicate to remote objects with an object, in this case a serialized object. It simplifies complex communication, using composite objects in order to communicate instead of primitives. The inverse of marshalling is called unmarshalling (or demarshalling, similar to deserialization).

Contents

• 1Usage
  • 1.1Example
• 2Comparison with serialization
• 3Unmarshalling
  • 3.1Usage
    • 3.1.1Overview
    • 3.1.2JAXB
    • 3.1.3XmlSerializer
    • 3.1.4XML and executable representation
  • 3.2Unmarshaller in JAXB
  • 3.3Unmarshalling XML Data
    • 3.3.1Unmarshal a global XML root element
    • 3.3.2Unmarshal a local XML root element
  • 3.4Comparison with deserialization
• 4See also
• 5Notes
• 6References

Usage[edit]

Marshalling is used within implementations of different remote procedure call (RPC) mechanisms, where it is necessary to transport data between processes and/or between threads. In Microsoft's Component Object Model (COM), interface pointers must be marshalled when crossing COM apartment boundaries.^[1][2] In the .NET Framework, the conversion between an unmanaged type and a CLR type, as in the P/Invoke process, is also an example of an action that requires marshalling to take place.^[3]

Additionally, marshalling is used extensively within scripts and applications that use the XPCOM technologies provided within the Mozilla application framework. The Mozilla Firefox browser is a popular application built with this framework, that additionally allows scripting languages to use XPCOM through XPConnect (Cross-Platform Connect).

Example[edit]

In the Microsoft Windows family of operating systems the entire set of device drivers for Direct3D are kernel-mode drivers. The user-mode portion of the API is handled by the DirectX runtime provided by Microsoft.

This is an issue because calling kernel-mode operations from user-mode requires performing a system call, and this inevitably forces the CPU to switch to "kernel mode". This is a slow operation, taking on the order of microseconds to complete.^[4] During this time, the CPU is unable to perform any operations. As such, minimizing the number of times this switching operation must be performed would optimize performance to a substantive degree.

Linux OpenGL drivers are split in two: a kernel-driver and a user-space driver. The user-space driver does all the translation of OpenGL commands into machine code to be submitted to the GPU. To reduce the number of system calls, the user-space driver implements marshalling. If the GPU's command buffer is full of rendering data, the API could simply store the requested rendering call in a temporary buffer and, when the command buffer is close to being empty, it can perform a switch to kernel-mode and add a number of stored commands all at once.

Comparison with serialization[edit]

To "serialize" an object means to convert its state into a byte stream in such a way that the byte stream can be converted back into a copy of the object.

The term "marshal" is used for a specific type of "serialization" in the Python standard library^[5] - storing internal python objects:

The marshal module exists mainly to support reading and writing the “pseudo-compiled” code for Python modules of .pyc files.

...

If you’re serializing and de-serializing Python objects, use the pickle module instead

— The Python Standard Library^[6]

In the Java-related RFC 2713, marshalling is used when serialising objects for remote invocation:

To "marshal" an object means to record its state and codebase(s) in such a way that when the marshalled object is "unmarshalled," a copy of the original object is obtained, possibly by automatically loading the class definitions of the object. You can marshal any object that is serializable or remote (that is, implements the java.rmi.Remote interface). Marshalling is like serialization, except marshalling also records codebases. Marshalling is different from serialization in that marshalling treats remote objects specially.

...

Any object whose methods can be invoked [on an object in another Java virtual machine] must implement the java.rmi.Remote interface. When such an object is invoked, its arguments are marshalled and sent from the local virtual machine to the remote one,

where the arguments are unmarshalled and used.

— Schema for Representing Java(tm) Objects in an LDAP Directory (RFC 2713)^[7]

In Microsoft .NET, marshalling is also used to refer to serialization when using remote calls:

When you marshal an object by value, a copy of the object is created and serialized to the server. Any method calls made on that object are done on the server

— How To Marshal an Object to a Remote Server by Value by Using Visual Basic .NET (Q301116)^[8]

Unmarshalling[edit]

In computer science, unmarshalling or demarshaling refers to the process of transforming a representation of an object that was used for storage or transmission to a representation of the object that can be internally processed by a computer program. A serialized object which was used for communication cannot usually be processed by a computer program. An unmarshalling interface takes the serialized object and transforms it into a internal data structure. In computer science the internal data structure can be referred to as executable.

For example a process might receive data as a string that presents data a JSON object. Before the data can be used it needs to be unmarshalled into a map data structure, or something more complex.

Unmarshalling (similar to deserialization) is the reverse process of marshalling.