From ac83ad64221c7c8cab3b283f1c4de08dd07ea71e Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Tue, 28 Jan 2025 12:01:57 -0800 Subject: [PATCH 1/3] add convention packs section --- source/fundamentals/serialization.txt | 51 ++++++++++++++++++++++ source/fundamentals/serialization/poco.txt | 3 ++ source/whats-new.txt | 13 ++++++ 3 files changed, 67 insertions(+) diff --git a/source/fundamentals/serialization.txt b/source/fundamentals/serialization.txt index f5a0bfce..b9aac1f4 100644 --- a/source/fundamentals/serialization.txt +++ b/source/fundamentals/serialization.txt @@ -140,6 +140,54 @@ Implementing the `IBsonArraySerializer interface enables the driver to access serialization information for individual items in an array. +.. _csharp-convention-packs: + +Convention Packs +---------------- + +Convention packs allow you to define and apply +**conventions** to your classes and their members during serialization. +Conventions modify how data is mapped between your +{+language+} objects and MongoDB documents without requiring you to decorate +each class with attributes. + +The {+driver-short+} provides built-in convention packs that you can use to +customize the serialization process. The following table describes some of the +built-in convention packs: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Convention Pack + - Description + + * - `CamelCaseElementNameConvention <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.CamelCaseElementNameConvention.html>`__ + - Converts element names to camel case during serialization and deserialization. + + * - `EnumRepresentationConvention <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.EnumRepresentationConvention.html>`__ + - Converts enum values to a specified representation during serialization + and deserialization. + + * - `IgnoreExtraElementsConvention <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.IgnoreExtraElementsConvention.html>`__ + - Specifies whether to ignore extra elements in a document during deserialization. + + * - `ObjectSerializerAllowedTypesConvention <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ObjectSerializerAllowedTypesConvention.html>`__ + - Specifies which types are allowed to be serialized using an object + serializer. + +For a full list of available convention packs, see the `Conventions +<{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.html>`__ +page in the API Documentation. + +You can register a convention pack by passing an instance of the pack to the +``ConventionRegistry.Register()`` method, as shown in the following example: + +.. code-block:: csharp + + var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() }; + ConventionRegistry.Register("CamelCaseConvention", camelCaseConvention, t => true); + Additional Information ---------------------- @@ -157,3 +205,6 @@ guide, see the following API documentation: - `SerializerRegistry <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.SerializerRegistry.html>`__ - `BsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html>`__ - `IBsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.IBsonSerializer.html>`__ +- `ConventionPack <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionPack.html>`__ +- `ConventionRegistry <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.ConventionRegistry.html>`__ +- `Register() <{+new-api-root+}/MongoDB.Bson.Serialization.Conventions.ConventionRegistry.Register.html#MongoDB_Bson_Serialization_Conventions_ConventionRegistry_Register_System_String_MongoDB_Bson_Serialization_Conventions_IConventionPack_System_Func_System_Type_System_Boolean__>`__ diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index 143d3059..20cbe5be 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -168,6 +168,9 @@ MongoDB collection. var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() }; ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true); + + For more information about convention packs, see the + :ref:`csharp-convention-packs` section of the Serialization guide. Select Type Representation ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/whats-new.txt b/source/whats-new.txt index d7009d26..84105730 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 3.2 ` * :ref:`Version 3.1 ` * :ref:`Version 3.0 ` * :ref:`Version 2.30 ` @@ -33,6 +34,18 @@ Learn what's new in: .. _upcoming-breaking-changes: +.. _csharp-version-3.2: + +What's New in 3.2 +----------------- + +The 3.2 driver release includes the following new features: + +- Adds a new ``ObjectSerializerAllowedTypesConvention`` convention pack that + allows you to specify which types are allowed to be serialized and + deserialized by the object serializer. To learn more about convention packs, + see the :ref:`csharp-convention-packs` guide. + .. _csharp-version-3.1: What's New in 3.1 From f288908ed52cc59dfc7556ed1078f8d88b999395 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Wed, 29 Jan 2025 07:38:36 -0800 Subject: [PATCH 2/3] feedback --- source/fundamentals/serialization.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/serialization.txt b/source/fundamentals/serialization.txt index b9aac1f4..4d8cf802 100644 --- a/source/fundamentals/serialization.txt +++ b/source/fundamentals/serialization.txt @@ -147,7 +147,7 @@ Convention Packs Convention packs allow you to define and apply **conventions** to your classes and their members during serialization. -Conventions modify how data is mapped between your +Conventions specify how data is mapped between your {+language+} objects and MongoDB documents without requiring you to decorate each class with attributes. @@ -157,7 +157,7 @@ built-in convention packs: .. list-table:: :header-rows: 1 - :widths: 30 70 + :widths: 40 60 * - Convention Pack - Description @@ -176,9 +176,9 @@ built-in convention packs: - Specifies which types are allowed to be serialized using an object serializer. -For a full list of available convention packs, see the `Conventions +To view a full list of available convention packs, see the `Conventions <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.html>`__ -page in the API Documentation. +class reference in the API Documentation. You can register a convention pack by passing an instance of the pack to the ``ConventionRegistry.Register()`` method, as shown in the following example: From aa640e803831bd43d225076c96e694ddd01544a8 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 6 Feb 2025 11:29:24 -0800 Subject: [PATCH 3/3] Tech review feedback --- source/fundamentals/serialization.txt | 19 ++++++++++--------- source/fundamentals/serialization/poco.txt | 4 ++-- source/whats-new.txt | 6 +++--- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/source/fundamentals/serialization.txt b/source/fundamentals/serialization.txt index 4d8cf802..a3f8de15 100644 --- a/source/fundamentals/serialization.txt +++ b/source/fundamentals/serialization.txt @@ -140,26 +140,26 @@ Implementing the `IBsonArraySerializer interface enables the driver to access serialization information for individual items in an array. -.. _csharp-convention-packs: +.. _csharp-conventions: -Convention Packs ----------------- +Conventions +----------- Convention packs allow you to define and apply -**conventions** to your classes and their members during serialization. +**conventions** to your classes and their members that the driver uses during serialization. Conventions specify how data is mapped between your {+language+} objects and MongoDB documents without requiring you to decorate each class with attributes. -The {+driver-short+} provides built-in convention packs that you can use to +The {+driver-short+} provides built-in conventions that you can use to customize the serialization process. The following table describes some of the -built-in convention packs: +built-in conventions: .. list-table:: :header-rows: 1 :widths: 40 60 - * - Convention Pack + * - Convention - Description * - `CamelCaseElementNameConvention <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.CamelCaseElementNameConvention.html>`__ @@ -176,11 +176,12 @@ built-in convention packs: - Specifies which types are allowed to be serialized using an object serializer. -To view a full list of available convention packs, see the `Conventions +To view a full list of available conventions, see the `Conventions <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Conventions.html>`__ class reference in the API Documentation. -You can register a convention pack by passing an instance of the pack to the +You can register a convention by instantiating a ``ConventionPack`` with the +specified conventions, then passing it to the ``ConventionRegistry.Register()`` method, as shown in the following example: .. code-block:: csharp diff --git a/source/fundamentals/serialization/poco.txt b/source/fundamentals/serialization/poco.txt index 20cbe5be..a7fab8a5 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/fundamentals/serialization/poco.txt @@ -169,8 +169,8 @@ MongoDB collection. var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() }; ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true); - For more information about convention packs, see the - :ref:`csharp-convention-packs` section of the Serialization guide. + For more information about conventions, see the + :ref:`csharp-conventions` section of the Serialization guide. Select Type Representation ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/whats-new.txt b/source/whats-new.txt index 84105730..4bc099ff 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -41,10 +41,10 @@ What's New in 3.2 The 3.2 driver release includes the following new features: -- Adds a new ``ObjectSerializerAllowedTypesConvention`` convention pack that +- Adds a new ``ObjectSerializerAllowedTypesConvention`` convention that allows you to specify which types are allowed to be serialized and - deserialized by the object serializer. To learn more about convention packs, - see the :ref:`csharp-convention-packs` guide. + deserialized by the object serializer. To learn more about conventions, + see the :ref:`csharp-conventions` guide. .. _csharp-version-3.1: