From 4827297834bf479dbad8fc47bcafe285c0365992 Mon Sep 17 00:00:00 2001 From: reeb Date: Sun, 10 May 2026 03:50:53 +0300 Subject: [PATCH] RDoc-1555 - explain how to use [JsonIgnore] to ignore a property while serializing, beautify `serialization` and `deserialization` --- .../content/_deserialization-csharp.mdx | 108 +++++++----- .../content/_serialization-csharp.mdx | 163 +++++++++++------- .../content/_deserialization-csharp.mdx | Bin 3578 -> 3578 bytes .../content/_serialization-csharp.mdx | 163 +++++++++++------- .../content/_deserialization-csharp.mdx | Bin 3578 -> 3578 bytes .../content/_serialization-csharp.mdx | 163 +++++++++++------- .../content/_deserialization-csharp.mdx | Bin 3578 -> 3578 bytes .../content/_serialization-csharp.mdx | 163 +++++++++++------- 8 files changed, 449 insertions(+), 311 deletions(-) diff --git a/docs/client-api/configuration/content/_deserialization-csharp.mdx b/docs/client-api/configuration/content/_deserialization-csharp.mdx index c80996f0ca..b2d4586e79 100644 --- a/docs/client-api/configuration/content/_deserialization-csharp.mdx +++ b/docs/client-api/configuration/content/_deserialization-csharp.mdx @@ -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"; -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) @@ -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) -## Deserialization + + ## 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. - - -{`Conventions = -\{ +```csharp +Conventions = +{ Serialization = new NewtonsoftJsonSerializationConventions - \{ + { CustomizeJsonDeserializer = serializer => throw new CodeOmitted() - \} -\} -`} - - + } +} +``` + + + +--- + + ## DeserializeEntityFromBlittable -* Use the `DeserializeEntityFromBlittable` convention to customize entity +* Use the `DeserializeEntityFromBlittable` convention to customize entity deserialization from a blittable JSON. - - -{`Conventions = -\{ +```csharp +Conventions = +{ Serialization = new NewtonsoftJsonSerializationConventions - \{ + { DeserializeEntityFromBlittable = (type, blittable) => throw new CodeOmitted() - \} -\} -`} - - + } +} +``` + + + +--- + + ## 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` - - -{`Conventions = -\{ +```csharp +Conventions = +{ PreserveDocumentPropertiesNotFoundOnModel = true -\} -`} - - +} +``` + + + +--- + + ## 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). + + -Read about this security convention and maintaining deserialization security -[here](../../../client-api/security/deserialization-security.mdx). +--- + ## 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. + diff --git a/docs/client-api/configuration/content/_serialization-csharp.mdx b/docs/client-api/configuration/content/_serialization-csharp.mdx index 9c86eb3531..403f79e063 100644 --- a/docs/client-api/configuration/content/_serialization-csharp.mdx +++ b/docs/client-api/configuration/content/_serialization-csharp.mdx @@ -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"; -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) -## Serialization + + + +## 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; +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ CustomizeJsonSerializer = serializer => throw new CodeOmitted() -\} -`} - - +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ JsonContractResolver = new CustomJsonContractResolver() -\} -`} - - - - - -{`public class CustomJsonContractResolver : IContractResolver -\{ +} +``` + +```csharp +public class CustomJsonContractResolver : IContractResolver +{ public JsonContract ResolveContract(Type type) - \{ + { throw new CodeOmitted(); - \} -\} -`} - - + } +} +``` -* 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. - - -{`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(); - \} -\} -`} - - + } +} +``` + + + +--- + + ## 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. - - -{`BulkInsert = -\{ +```csharp +BulkInsert = +{ TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(), -\} -`} - - +} +``` + + + +--- + + ## 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` - - - + diff --git a/versioned_docs/version-6.2/client-api/configuration/content/_deserialization-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_deserialization-csharp.mdx index c80996f0ca032073a5689c809a4b5da2d47c85ff..b4191f5ca9b01ff1c7c97efee6131b5c12427449 100644 GIT binary patch delta 681 zcmew*{Y!en9GlGCg8ZTq1?T*{lGMBsx1z+{RE4yn{9FYkhvLkVRQ=+jWc}oPprSmW zbg@3NI;DxT=1sO_bl=>>IEjg$%LZA_Zn7Fn_T)({8Iymr*h(ZMBqSGSBo-BL0o9ZN z4a&^VD^{@On!JE-o7s8|=8abai!sqR2*1&ST4;e2+~Rzo|Fa zV~j{K6=;>Rvclx^9Ga7xIC>`YbM{Q0!xJ=0)H8Ic+q|wJJ0JnjjrvLx| delta 643 zcmew*{Y!enoQb#QFe*$gV{~UyP}sbeaT1e|va*6pYH?~&W@1ieRbokIe%|CbmTaJ+ zlPnoP(va1*-X`8DY>+`BtJK^Dm6ZWvO`}#}q5rGI7OB{>|pf z7&G}aYk+)AEf)|a)NGLoDE zcZmagj0ypl*l}?wD^G6V)SCRAy$9%|W)2X^&l!Rdo&`mq5G+fLPsvY?FDS|{D2~s| zFNsgfFU?Dd2L^C1FtBpq4ku1E9*>D(3uK_rsyWSN@CNN2&OD$Gytv$f0Fn*Z;Q#;t diff --git a/versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx b/versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx index 9c86eb3531..403f79e063 100644 --- a/versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/configuration/content/_serialization-csharp.mdx @@ -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"; -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) -## Serialization + + + +## 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; +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ CustomizeJsonSerializer = serializer => throw new CodeOmitted() -\} -`} - - +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ JsonContractResolver = new CustomJsonContractResolver() -\} -`} - - - - - -{`public class CustomJsonContractResolver : IContractResolver -\{ +} +``` + +```csharp +public class CustomJsonContractResolver : IContractResolver +{ public JsonContract ResolveContract(Type type) - \{ + { throw new CodeOmitted(); - \} -\} -`} - - + } +} +``` -* 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. - - -{`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(); - \} -\} -`} - - + } +} +``` + + + +--- + + ## 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. - - -{`BulkInsert = -\{ +```csharp +BulkInsert = +{ TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(), -\} -`} - - +} +``` + + + +--- + + ## 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` - - - + diff --git a/versioned_docs/version-7.0/client-api/configuration/content/_deserialization-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_deserialization-csharp.mdx index c80996f0ca032073a5689c809a4b5da2d47c85ff..b4191f5ca9b01ff1c7c97efee6131b5c12427449 100644 GIT binary patch delta 681 zcmew*{Y!en9GlGCg8ZTq1?T*{lGMBsx1z+{RE4yn{9FYkhvLkVRQ=+jWc}oPprSmW zbg@3NI;DxT=1sO_bl=>>IEjg$%LZA_Zn7Fn_T)({8Iymr*h(ZMBqSGSBo-BL0o9ZN z4a&^VD^{@On!JE-o7s8|=8abai!sqR2*1&ST4;e2+~Rzo|Fa zV~j{K6=;>Rvclx^9Ga7xIC>`YbM{Q0!xJ=0)H8Ic+q|wJJ0JnjjrvLx| delta 643 zcmew*{Y!enoQb#QFe*$gV{~UyP}sbeaT1e|va*6pYH?~&W@1ieRbokIe%|CbmTaJ+ zlPnoP(va1*-X`8DY>+`BtJK^Dm6ZWvO`}#}q5rGI7OB{>|pf z7&G}aYk+)AEf)|a)NGLoDE zcZmagj0ypl*l}?wD^G6V)SCRAy$9%|W)2X^&l!Rdo&`mq5G+fLPsvY?FDS|{D2~s| zFNsgfFU?Dd2L^C1FtBpq4ku1E9*>D(3uK_rsyWSN@CNN2&OD$Gytv$f0Fn*Z;Q#;t diff --git a/versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx b/versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx index 9c86eb3531..403f79e063 100644 --- a/versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/configuration/content/_serialization-csharp.mdx @@ -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"; -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) -## Serialization + + + +## 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; +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ CustomizeJsonSerializer = serializer => throw new CodeOmitted() -\} -`} - - +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ JsonContractResolver = new CustomJsonContractResolver() -\} -`} - - - - - -{`public class CustomJsonContractResolver : IContractResolver -\{ +} +``` + +```csharp +public class CustomJsonContractResolver : IContractResolver +{ public JsonContract ResolveContract(Type type) - \{ + { throw new CodeOmitted(); - \} -\} -`} - - + } +} +``` -* 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. - - -{`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(); - \} -\} -`} - - + } +} +``` + + + +--- + + ## 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. - - -{`BulkInsert = -\{ +```csharp +BulkInsert = +{ TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(), -\} -`} - - +} +``` + + + +--- + + ## 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` - - - + diff --git a/versioned_docs/version-7.1/client-api/configuration/content/_deserialization-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_deserialization-csharp.mdx index c80996f0ca032073a5689c809a4b5da2d47c85ff..b4191f5ca9b01ff1c7c97efee6131b5c12427449 100644 GIT binary patch delta 681 zcmew*{Y!en9GlGCg8ZTq1?T*{lGMBsx1z+{RE4yn{9FYkhvLkVRQ=+jWc}oPprSmW zbg@3NI;DxT=1sO_bl=>>IEjg$%LZA_Zn7Fn_T)({8Iymr*h(ZMBqSGSBo-BL0o9ZN z4a&^VD^{@On!JE-o7s8|=8abai!sqR2*1&ST4;e2+~Rzo|Fa zV~j{K6=;>Rvclx^9Ga7xIC>`YbM{Q0!xJ=0)H8Ic+q|wJJ0JnjjrvLx| delta 643 zcmew*{Y!enoQb#QFe*$gV{~UyP}sbeaT1e|va*6pYH?~&W@1ieRbokIe%|CbmTaJ+ zlPnoP(va1*-X`8DY>+`BtJK^Dm6ZWvO`}#}q5rGI7OB{>|pf z7&G}aYk+)AEf)|a)NGLoDE zcZmagj0ypl*l}?wD^G6V)SCRAy$9%|W)2X^&l!Rdo&`mq5G+fLPsvY?FDS|{D2~s| zFNsgfFU?Dd2L^C1FtBpq4ku1E9*>D(3uK_rsyWSN@CNN2&OD$Gytv$f0Fn*Z;Q#;t diff --git a/versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx b/versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx index 9c86eb3531..403f79e063 100644 --- a/versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx +++ b/versioned_docs/version-7.1/client-api/configuration/content/_serialization-csharp.mdx @@ -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"; -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) -## Serialization + + + +## 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; +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ CustomizeJsonSerializer = serializer => throw new CodeOmitted() -\} -`} - - +} +``` + + + +--- + + ## 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. - - -{`Serialization = new NewtonsoftJsonSerializationConventions -\{ +```csharp +Serialization = new NewtonsoftJsonSerializationConventions +{ JsonContractResolver = new CustomJsonContractResolver() -\} -`} - - - - - -{`public class CustomJsonContractResolver : IContractResolver -\{ +} +``` + +```csharp +public class CustomJsonContractResolver : IContractResolver +{ public JsonContract ResolveContract(Type type) - \{ + { throw new CodeOmitted(); - \} -\} -`} - - + } +} +``` -* 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. - - -{`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(); - \} -\} -`} - - + } +} +``` + + + +--- + + ## 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. - - -{`BulkInsert = -\{ +```csharp +BulkInsert = +{ TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(), -\} -`} - - +} +``` + + + +--- + + ## 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` - - - +