|
| 1 | +# Serialization |
| 2 | + |
| 3 | +RestSharp has JSON and XML serializers built in. |
| 4 | + |
| 5 | +:::tip |
| 6 | +The default behavior of RestSharp is to swallow deserialization errors and return `null` in the `Data` |
| 7 | +property of the response. Read more about it in the [Error Handling](error-handling.md). |
| 8 | +::: |
| 9 | + |
| 10 | +## JSON |
| 11 | + |
| 12 | +The default JSON serializer uses `System.Text.Json`, which is a part of .NET since .NET 6. For earlier versions, it is added as a dependency. There are also a few serializers provided as additional packages. |
| 13 | + |
| 14 | +## XML |
| 15 | + |
| 16 | +The default XML serializer is `DotNetXmlSerializer`, which uses `System.Xml.Serialization` library from .NET. |
| 17 | + |
| 18 | +In previous versions of RestSharp, the default XML serializer was a custom RestSharp XML serializer. To make the code library size smaller, that serializer is now available as a separate package [`RestSharp.Serializers.Xml`](https://www.nuget.org/packages/RestSharp.Serializers.Xml). |
| 19 | +You can add it back if necessary by installing the package and adding it to the client: |
| 20 | + |
| 21 | +```csharp |
| 22 | +client.UseXmlSerializer(); |
| 23 | +``` |
| 24 | + |
| 25 | +As before, you can supply three optional arguments for a custom namespace, custom root element, and if you want to use `SerializeAs` and `DeserializeAs` attributed. |
| 26 | + |
| 27 | +## NewtonsoftJson (aka Json.Net) |
| 28 | + |
| 29 | +The `NewtonsoftJson` package is the most popular JSON serializer for .NET. It handles all possible scenarios and is very configurable. Such a flexibility comes with the cost of performance. If you need speed, keep the default JSON serializer. |
| 30 | + |
| 31 | +RestSharp support Json.Net serializer via a separate package [`RestSharp.Serializers.NewtonsoftJson`](https://www.nuget.org/packages/RestSharp.Serializers.NewtonsoftJson). |
| 32 | + |
| 33 | +::: warning |
| 34 | +Please note that `RestSharp.Newtonsoft.Json` package is not provided by RestSharp, is marked as obsolete on NuGet, and no longer supported by its creator. |
| 35 | +::: |
| 36 | + |
| 37 | +Use the extension method provided by the package to configure the client: |
| 38 | + |
| 39 | +```csharp |
| 40 | +client.UseNewtonsoftJson(); |
| 41 | +``` |
| 42 | + |
| 43 | +The serializer configures some options by default: |
| 44 | + |
| 45 | +```csharp |
| 46 | +JsonSerializerSettings DefaultSettings = new JsonSerializerSettings { |
| 47 | + ContractResolver = new CamelCasePropertyNamesContractResolver(), |
| 48 | + DefaultValueHandling = DefaultValueHandling.Include, |
| 49 | + TypeNameHandling = TypeNameHandling.None, |
| 50 | + NullValueHandling = NullValueHandling.Ignore, |
| 51 | + Formatting = Formatting.None, |
| 52 | + ConstructorHandling = ConstructorHandling.AllowNonPublicDefaultConstructor |
| 53 | +}; |
| 54 | +``` |
| 55 | + |
| 56 | +If you need to use different settings, you can supply your instance of |
| 57 | +`JsonSerializerSettings` as a parameter for the extension method. |
| 58 | + |
| 59 | +## Custom |
| 60 | + |
| 61 | +You can also implement your custom serializer. To support both serialization and |
| 62 | +deserialization, you must implement the `IRestSerializer` interface. |
| 63 | + |
| 64 | +Here is an example of a custom serializer that uses `System.Text.Json`: |
| 65 | + |
| 66 | +```csharp |
| 67 | +public class SimpleJsonSerializer : IRestSerializer { |
| 68 | + public string Serialize(object obj) => JsonSerializer.Serialize(obj); |
| 69 | + |
| 70 | + public string Serialize(Parameter bodyParameter) => Serialize(bodyParameter.Value); |
| 71 | + |
| 72 | + public T Deserialize<T>(IRestResponse response) => JsonSerializer.Deserialize<T>(response.Content); |
| 73 | + |
| 74 | + public string[] SupportedContentTypes { get; } = { |
| 75 | + "application/json", "text/json", "text/x-json", "text/javascript", "*+json" |
| 76 | + }; |
| 77 | + |
| 78 | + public string ContentType { get; set; } = "application/json"; |
| 79 | + |
| 80 | + public DataFormat DataFormat { get; } = DataFormat.Json; |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +The value of the `SupportedContentTypes` property will be used to match the |
| 85 | +serializer with the response `Content-Type` headers. |
| 86 | + |
| 87 | +The `ContentType` property will be used when making a request so the |
| 88 | +server knows how to handle the payload. |
0 commit comments