Skip to content

Serialization and Deserialization pages: add converters and FHIR examples, explain bulk insert serialization function #2712

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

Open
reebhub wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Serialization and Deserialization pages: add converters and FHIR examples, explain bulk insert serialization function #2712

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
99 changes: 42 additions & 57 deletions docs/client-api/configuration/content/_deserialization-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
import Admonition from '@theme/Admonition';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
import ContentFrame from "@site/src/components/ContentFrame";
import Panel from "@site/src/components/Panel";

<Admonition type="note" title="">

Use the methods described in this page to customize the [conventions](../../../client-api/configuration/conventions.mdx)
by which entities are deserialized as they are received by the client.

* In this page:
* The C# client deserializes documents loaded from the server into entities using the
[Newtonsoft.Json](https://www.newtonsoft.com/json/help/html/SerializingJSON.htm) library (also known as Json.NET).
* Use the [conventions](../../../client-api/configuration/conventions.mdx) described in this article
to customize the deserialization (e.g., to preserve document properties that your entity class does not define).
* In this article:
* [CustomizeJsonDeserializer](../../../client-api/configuration/deserialization.mdx#customizejsondeserializer)
* [DeserializeEntityFromBlittable](../../../client-api/configuration/deserialization.mdx#deserializeentityfromblittable)
* [PreserveDocumentPropertiesNotFoundOnModel](../../../client-api/configuration/deserialization.mdx#preservedocumentpropertiesnotfoundonmodel)
Expand All @@ -18,35 +16,34 @@ by which entities are deserialized as they are received by the client.

</Admonition>

<ContentFrame>

## CustomizeJsonDeserializer

* The `JsonSerializer` object is used by the client to deserialize entities
loaded from the server.
* Use the `CustomizeJsonDeserializer` convention to modify `JsonSerializer`
by registering a deserialization customization action.

```csharp
Conventions =
{
Serialization = new NewtonsoftJsonSerializationConventions
{
CustomizeJsonDeserializer = serializer => throw new CodeOmitted()
}
}
```

</ContentFrame>

---

<ContentFrame>

## DeserializeEntityFromBlittable

* Use the `DeserializeEntityFromBlittable` convention to customize entity
deserialization from a blittable JSON.
<Panel heading="CustomizeJsonDeserializer">

* The client uses `JsonSerializer` objects of the [Newtonsoft.Json](https://www.newtonsoft.com/json/help/html/SerializingJSON.htm)
library to **deserialize** documents loaded from the server into entities.
* Use the `CustomizeJsonDeserializer` convention to register an action that modifies only the `JsonSerializer` objects
used to load documents (e.g., to keep a property's default value when the loaded document holds `null` for this property).
<br /><br />
```csharp
Conventions =
{
Serialization = new NewtonsoftJsonSerializationConventions
{
CustomizeJsonDeserializer = serializer => throw new CodeOmitted()
}
}
```
<br />
* Note that an action registered using [CustomizeJsonSerializer](../../../client-api/configuration/serialization.mdx#customizejsonserializer)
also applies when loading documents, and runs before the `CustomizeJsonDeserializer` action.
A [converter](../../../client-api/configuration/serialization.mdx#adding-a-converter) registered using `CustomizeJsonSerializer`
therefore does not need to be registered using `CustomizeJsonDeserializer` as well.

</Panel>

<Panel heading="DeserializeEntityFromBlittable">

Use the `DeserializeEntityFromBlittable` convention to customize entity
deserialization from a blittable JSON.

```csharp
Conventions =
Expand All @@ -58,13 +55,9 @@ Conventions =
}
```

</ContentFrame>

---
</Panel>

<ContentFrame>

## PreserveDocumentPropertiesNotFoundOnModel
<Panel heading="PreserveDocumentPropertiesNotFoundOnModel">

* Some document properties are not deserialized to an object.
* Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `true`
Expand All @@ -80,13 +73,9 @@ Conventions =
}
```

</ContentFrame>

---

<ContentFrame>
</Panel>

## DefaultRavenSerializationBinder
<Panel heading="DefaultRavenSerializationBinder">

Use the `DefaultRavenSerializationBinder` convention and its methods to
prevent gadgets from running RCE (Remote Code Execution) attacks while
Expand All @@ -95,18 +84,14 @@ data is deserialized by the client.
Read about this security convention and maintaining deserialization security
[here](../../../client-api/security/deserialization-security.mdx).

</ContentFrame>

---

<ContentFrame>
</Panel>

## Number Deserialization
<Panel heading="Number Deserialization">

* RavenDB client supports all common numeric value types (including `int`, `long`,
`double`, `decimal`, etc.) out of the box.
* Note that although deserialization of `decimals` is fully supported, there are
[server side limitations](../../../server/kb/numbers-in-ravendb.mdx) to numbers in this range.
* Other number types, like `BigInteger`, must be handled using custom deserialization.
* Other number types, like `BigInteger`, must be handled using a [converter](../../../client-api/configuration/serialization.mdx#adding-a-converter).

</ContentFrame>
</Panel>
Loading
Loading