reviewed

samples/nhibernate/custom-mappings/sample.md

@@ -1,13 +1,13 @@
 ---
 title: NServiceBus.NHibernate custom saga mapping sample
-summary: NServiceBus sample that creates a custom saga mapping to change how NHibernate creates the database schema using different techniques.
-reviewed: 2022-03-25
+summary: An NServiceBus sample demonstrating a custom saga mapping to change how NHibernate creates the database schema using different techniques.
+reviewed: 2024-12-28
 component: NHibernate
 related:
  - persistence/nhibernate
 ---
 
-Sometimes the database schema that is generated by `NServiceBus.NHibernate` is insufficient for saga data types. For example, storing strings with a different string length, wanting to use complex types, needing to store DateTime values with a high precision, or wanting to tweak the eager versus lazy loading rules might be better options. A custom mapping will be required to achieve these changes.
+Sometimes, the database schema generated by `NServiceBus.NHibernate` is insufficient for saga data types. For example, storing strings with a different string length, wanting to use complex types, needing to store DateTime values with high precision, or wanting to tweak the eager versus lazy loading rules might be better options. A custom mapping will be required to achieve these changes.
 
 Custom mappings can be added by:
 
@@ -16,48 +16,48 @@ Custom mappings can be added by:
 * NHibernate.Mapping.Attributes
 * Loquacious Configuration (native fluent API)
 
-There are other options, but these are the most frequently used. The performance difference between these options can have small variances, but those will occur during endpoint startup, not when the endpoint is processing messages.
+Other options exist, but these are the most frequently used. Minor variances in performance can exist between these options, but those will occur during endpoint startup, not when the endpoint is processing messages.
 
 > [!NOTE]
 > There is no requirement to create a custom mapping for all sagas if a custom mapping is needed by only one saga.
 
 > [!NOTE]
-> When creating a custom mapping, the mapping of the **primary key** and **unique indexes** must be included.
+> When creating a custom mapping, mapping the **primary key** and **unique indexes** is required.
 
-When using a custom mapping, ensure that a unique index exists for every column referenced by a `.ToSaga()` saga mapping expression. Not adding a unique constraint can result in duplicate saga entities as the second insert will **not** fail when inserting the same value if multiple messages are processed concurrently and they reference the same saga instance.
+When using a custom mapping, ensure a unique index exists for every column referenced by a `.ToSaga()` saga mapping expression. Not adding a unique constraint can result in duplicate saga entities. The second insert will **not** fail when inserting the same value if multiple messages are processed concurrently and they reference the same saga instance.
 
 ## Prerequisites
 
-This sample requires an instance of SQL Server at `.\SqlExpress` and the database `Samples.CustomNhMappings` to run properly.
+This sample requires an instance of SQL Server at `.\SqlExpress` and the database `Samples.CustomNhMappings` to run correctly.
 
 ## Custom .hbm.xml mapping
 
 Using NHibernate mapping files is the native way to customize the mappings. The mapping files are xml files that are either embedded as a resource in the assembly or available on the file system.
 
-For more information, see: [how to create a simple NHibernate based application](https://nhibernate.info/doc/tutorials/first-nh-app/your-first-nhibernate-based-application.html).
+For more information, see [how to create a simple NHibernate-based application](https://nhibernate.info/doc/tutorials/first-nh-app/your-first-nhibernate-based-application.html).
 
 ### Mapping
 
-The `.hbm.xml` contents is as follows
+The `.hbm.xml` content is as follows:
 
 snippet: hmlxml
 
 ### Configuration
 
-Create a custom NHibernate configuration object and use the following example to add mappings from the file system.
+Create a custom NHibernate configuration object and add mappings from the file system using the following example:
 
 snippet: AddMappingsFromFilesystem
 
 ## Use Fluent NHibernate
 
-[Fluent NHibernate](http://www.fluentnhibernate.org) provides a type-safe mapping approach where the mapping is specified in code (not as `.hbm.xml`) but the mapping is still separate from the classes. The benefit of this approach is the compile time feedback provided when a mapping is not valid.
+[Fluent NHibernate](http://www.fluentnhibernate.org) provides a type-safe mapping approach where the mapping is specified in code (not as `.hbm.xml`), but the mapping is still separate from the classes. The benefit of this approach is the compile-time feedback provided when a mapping is invalid.
 
 To use it with NServiceBus:
 
 1. Install the `FluentNHibernate` package via NuGet.
 1. Create a custom NHibernate configuration
    * via FluentNHibernate
-   * or by creating a new Configuration instance and pass it to FluentNHibernate
+   * or by creating a new Configuration instance and passing it to FluentNHibernate
 1. Pass it to the NServiceBus NHibernate configuration.
 
 ### Mapping
@@ -72,7 +72,7 @@ snippet: FluentConfiguration
 
 ## Use NHibernate.Mapping.Attributes
 
-Saga data classes can be decorated with [NHibernate.Mapping.Attributes](https://nhibernate.info/doc/nhibernate-reference/mapping-attributes.html). Saga types will have a dependency on the NHibernate.Mapping.Attributes assembly, but this keeps the classes, mapping and schema data very close.
+Saga data classes can be decorated with [NHibernate.Mapping.Attributes](https://nhibernate.info/doc/nhibernate-reference/mapping-attributes.html). Saga types will have a dependency on the NHibernate.Mapping.Attributes assembly, but this keeps the classes, mapping, and schema data very close.
 
 NHibernate.Mapping.Attributes needs to know what types to scan to generate an NHibernate mapping configuration that can be passed to the NServiceBus NHibernate configuration.
 
@@ -87,13 +87,13 @@ snippet: AttributesMapping
 
 ### Configuration
 
-Initialize the NHibernate attribute based mappings:
+Initialize the NHibernate attribute-based mappings:
 
 snippet: AttributesConfiguration
 
 ## Use the Loquacious mapping by code API
 
-[NHibernate Loquacious API](https://nhibernate.info/doc/howto/mapping/a-fully-working-skeleton-for-sexy-loquacious-nh.html) is a native mapping for NHibernate that is provided via code. Just like FluentNhibernate, the mapping is declared in code, but it uses a different syntax more closely aligned to NHibernate's xml schema. NHibernate Loquacious can help create a type-safe configuration, and it can also create custom mappings. The benefit of using NHibernate Loquacious is that this API is already available via the NHibernate package so it requires no additional downloads.
+[NHibernate Loquacious API](https://nhibernate.info/doc/howto/mapping/a-fully-working-skeleton-for-sexy-loquacious-nh.html) is a native mapping for NHibernate that is provided via code. Like FluentNhibernate, the mapping is declared in code, but it uses a different syntax that is more closely aligned to NHibernate's xml schema. NHibernate Loquacious can help create type-safe configurations and custom mappings. The benefit of using NHibernate Loquacious is that this API is already available via the NHibernate package, requiring no additional downloads.
 
 To use it: