Skip to content

RDoc-1555 - explain how to use JsonIgnore to ignore a property while serializing, beautify serialization and deserialization #2437

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

RDoc-1555 - explain how to use JsonIgnore to ignore a property while serializing, beautify serialization and deserialization #2437

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
108 changes: 61 additions & 47 deletions docs/client-api/configuration/content/_deserialization-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@ 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";

<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.
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:
* [CustomizeJsonDeserializer](../../../client-api/configuration/deserialization.mdx#customizejsondeserializer)
Expand All @@ -16,83 +17,96 @@ by which entities are deserialized as they are received by the client.
* [Number Deserialization](../../../client-api/configuration/deserialization.mdx#number-deserialization)

</Admonition>
## Deserialization

<ContentFrame>

## CustomizeJsonDeserializer

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

<TabItem value="customize_json_deserializer" label="customize_json_deserializer">
<CodeBlock language="csharp">
{`Conventions =
\{
```csharp
Conventions =
{
Serialization = new NewtonsoftJsonSerializationConventions
\{
{
CustomizeJsonDeserializer = serializer => throw new CodeOmitted()
\}
\}
`}
</CodeBlock>
</TabItem>
}
}
```

</ContentFrame>

---

<ContentFrame>

## DeserializeEntityFromBlittable

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

<TabItem value="DeserializeEntityFromBlittable" label="DeserializeEntityFromBlittable">
<CodeBlock language="csharp">
{`Conventions =
\{
```csharp
Conventions =
{
Serialization = new NewtonsoftJsonSerializationConventions
\{
{
DeserializeEntityFromBlittable = (type, blittable) => throw new CodeOmitted()
\}
\}
`}
</CodeBlock>
</TabItem>
}
}
```

</ContentFrame>

---

<ContentFrame>

## PreserveDocumentPropertiesNotFoundOnModel

* Some document properties are not deserialized to an object.
* Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `true`
* Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `true`
to **preserve** such properties when the document is saved.
* Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `false`
* Set the `PreserveDocumentPropertiesNotFoundOnModel` convention to `false`
to **remove** such properties when the document is saved.
* Default: `true`

<TabItem value="preserve_doc_props_not_found_on_model" label="preserve_doc_props_not_found_on_model">
<CodeBlock language="csharp">
{`Conventions =
\{
```csharp
Conventions =
{
PreserveDocumentPropertiesNotFoundOnModel = true
\}
`}
</CodeBlock>
</TabItem>
}
```

</ContentFrame>

---

<ContentFrame>

## DefaultRavenSerializationBinder

Use the `DefaultRavenSerializationBinder` convention and its methods to
prevent gadgets from running RCE (Remote Code Execution) attacks while
data is deserialized by the client.
Use the `DefaultRavenSerializationBinder` convention and its methods to
prevent gadgets from running RCE (Remote Code Execution) attacks while
data is deserialized by the client.

Read about this security convention and maintaining deserialization security
[here](../../../client-api/security/deserialization-security.mdx).

</ContentFrame>

Read about this security convention and maintaining deserialization security
[here](../../../client-api/security/deserialization-security.mdx).
---

<ContentFrame>

## Number Deserialization

* RavenDB client supports all common numeric value types (including `int`, `long`,
* 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
* 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 custom deserialization.

</ContentFrame>
163 changes: 97 additions & 66 deletions docs/client-api/configuration/content/_serialization-csharp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,120 +2,151 @@ 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";

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

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

* In this page:
* [Ignoring a property](../../../client-api/configuration/serialization.mdx#ignoring-a-property)
* [CustomizeJsonSerializer](../../../client-api/configuration/serialization.mdx#customizejsonserializer)
* [JsonContractResolver](../../../client-api/configuration/serialization.mdx#jsoncontractresolver)
* [BulkInsert.TrySerializeEntityToJsonStream](../../../client-api/configuration/serialization.mdx#bulkinserttryserializeentitytojsonstream)
* [IgnoreByRefMembers and IgnoreUnsafeMembers](../../../client-api/configuration/serialization.mdx#ignorebyrefmembers-and-ignoreunsafemembers)

</Admonition>
## Serialization

<ContentFrame>

## Ignoring a property

* By default, RavenDB serializes **all** properties and **all** public fields of an entity.
* Decorate a property with `[JsonIgnore]` to exclude it from serialization.
The decorated property will not be stored in the document and will not be available for indexing.
* `[JsonIgnore]` is from the `Newtonsoft.Json` namespace.

```csharp
public class Shirt
{
public string Id { get; set; }

// Stored in the document
public decimal Price { get; set; }

// Not stored - computed from Price at runtime
[JsonIgnore]
public decimal PriceWithTax => Price * 1.2m;
}
```

</ContentFrame>

---

<ContentFrame>

## CustomizeJsonSerializer

* The `JsonSerializer` object is used by the client to serialize entities
* The `JsonSerializer` object is used by the client to serialize entities
sent by the client to the server.
* Use the `CustomizeJsonSerializer ` convention to modify `JsonSerializer`
* Use the `CustomizeJsonSerializer` convention to modify `JsonSerializer`
by registering a serialization customization action.

<TabItem value="customize_json_serializer" label="customize_json_serializer">
<CodeBlock language="csharp">
{`Serialization = new NewtonsoftJsonSerializationConventions
\{
```csharp
Serialization = new NewtonsoftJsonSerializationConventions
{
CustomizeJsonSerializer = serializer => throw new CodeOmitted()
\}
`}
</CodeBlock>
</TabItem>
}
```

</ContentFrame>

---

<ContentFrame>

## JsonContractResolver

* The default `JsonContractResolver` convention used by RavenDB will serialize
* The default `JsonContractResolver` convention used by RavenDB will serialize
**all** properties and **all** public fields.
* Change this behavior by providing your own implementation of the `IContractResolver`
* Change this behavior by providing your own implementation of the `IContractResolver`
interface.

<TabItem value="json_contract_resolver" label="json_contract_resolver">
<CodeBlock language="csharp">
{`Serialization = new NewtonsoftJsonSerializationConventions
\{
```csharp
Serialization = new NewtonsoftJsonSerializationConventions
{
JsonContractResolver = new CustomJsonContractResolver()
\}
`}
</CodeBlock>
</TabItem>

<TabItem value="custom_json_contract_resolver" label="custom_json_contract_resolver">
<CodeBlock language="csharp">
{`public class CustomJsonContractResolver : IContractResolver
\{
}
```

```csharp
public class CustomJsonContractResolver : IContractResolver
{
public JsonContract ResolveContract(Type type)
\{
{
throw new CodeOmitted();
\}
\}
`}
</CodeBlock>
</TabItem>
}
}
```

* You can also customize the behavior of the **default resolver** by inheriting
* You can also customize the behavior of the **default resolver** by inheriting
from `DefaultRavenContractResolver` and overriding specific methods.

<TabItem value="custom_json_contract_resolver_based_on_default" label="custom_json_contract_resolver_based_on_default">
<CodeBlock language="csharp">
{`public class CustomizedRavenJsonContractResolver : DefaultRavenContractResolver
\{
```csharp
public class CustomizedRavenJsonContractResolver : DefaultRavenContractResolver
{
public CustomizedRavenJsonContractResolver(ISerializationConventions conventions) : base(conventions)
\{
\}
{
}

protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization)
\{
{
throw new CodeOmitted();
\}
\}
`}
</CodeBlock>
</TabItem>
}
}
```

</ContentFrame>

---

<ContentFrame>

## BulkInsert.TrySerializeEntityToJsonStream

* Adjust [Bulk Insert](../../../client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx)
behavior by using the `TrySerializeEntityToJsonStream` convention to register a custom
* Adjust [Bulk Insert](../../../client-api/bulk-insert/how-to-work-with-bulk-insert-operation.mdx)
behavior by using the `TrySerializeEntityToJsonStream` convention to register a custom
serialization implementation.

<TabItem value="TrySerializeEntityToJsonStream" label="TrySerializeEntityToJsonStream">
<CodeBlock language="csharp">
{`BulkInsert =
\{
```csharp
BulkInsert =
{
TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(),
\}
`}
</CodeBlock>
</TabItem>
}
```

</ContentFrame>

---

<ContentFrame>

## IgnoreByRefMembers and IgnoreUnsafeMembers

* By default, if you try to store an entity with `ref` or unsafe members,
the Client will throw an exception when [`session.SaveChanges()`](../../../client-api/session/saving-changes.mdx)
* By default, if you try to store an entity with `ref` or unsafe members,
the Client will throw an exception when [`session.SaveChanges()`](../../../client-api/session/saving-changes.mdx)
is called.
* Set the `IgnoreByRefMembers` convention to `true` to simply ignore `ref`
* Set the `IgnoreByRefMembers` convention to `true` to simply ignore `ref`
members when an attempt to store an entity with `ref` members is made.
The entity will be uploaded to the server with all non-`ref` members without
The entity will be uploaded to the server with all non-`ref` members without
throwing an exception.
The document structure on the server-side will not contain fields for those
The document structure on the server-side will not contain fields for those
`ref` members.
* Set the `IgnoreUnsafeMembers` convention to `true` to ignore all pointer
* Set the `IgnoreUnsafeMembers` convention to `true` to ignore all pointer
members in the same manner.
* `IgnoreByRefMembers` default value: `false`
* `IgnoreUnsafeMembers` default value: `false`




</ContentFrame>
Binary file modified versioned_docs/version-6.2/client-api/configuration/content/_deserialization-csharp.mdx
View file
Open in desktop
Binary file not shown.
Loading
Loading