Add JSON mapping for complex properties model building support (#36299)

Part of #31252

Author: AndriySvyryd

src/EFCore.Relational/Extensions/RelationalComplexCollectionBuilderExtensions.cs

@@ -0,0 +1,74 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.EntityFrameworkCore;
+
+/// <summary>
+///     Relational database specific extension methods for <see cref="ComplexCollectionBuilder" />.
+/// </summary>
+/// <remarks>
+///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see> for more information and examples.
+/// </remarks>
+public static class RelationalComplexCollectionBuilderExtensions
+{
+    /// <summary>
+    ///     Configures the complex collection to be stored as a JSON column.
+    /// </summary>
+    /// <param name="complexCollectionBuilder">The builder for the complex collection being configured.</param>
+    /// <param name="jsonColumnName">The name of the JSON column. If not specified, the complex collection name is used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexCollectionBuilder ToJson(
+        this ComplexCollectionBuilder complexCollectionBuilder,
+        string? jsonColumnName = null)
+    {
+        Check.NullButNotEmpty(jsonColumnName);
+
+        var complexProperty = complexCollectionBuilder.Metadata;
+        complexProperty.ComplexType.SetContainerColumnName(jsonColumnName ?? complexProperty.Name);
+
+        return complexCollectionBuilder;
+    }
+
+    /// <summary>
+    ///     Configures the complex collection to be stored as a JSON column.
+    /// </summary>
+    /// <param name="complexCollectionBuilder">The builder for the complex collection being configured.</param>
+    /// <param name="jsonColumnName">The name of the JSON column. If not specified, the complex collection name is used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexCollectionBuilder<TComplex> ToJson<TComplex>(
+        this ComplexCollectionBuilder<TComplex> complexCollectionBuilder,
+        string? jsonColumnName = null)
+        where TComplex : class
+        => (ComplexCollectionBuilder<TComplex>)ToJson((ComplexCollectionBuilder)complexCollectionBuilder, jsonColumnName);
+
+    /// <summary>
+    ///     Configures the complex property contained in a JSON column to map to a specific JSON property,
+    ///     rather than using the property name.
+    /// </summary>
+    /// <param name="complexCollectionBuilder">The builder for the property being configured.</param>
+    /// <param name="name">JSON property name to be used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexCollectionBuilder HasJsonPropertyName(
+        this ComplexCollectionBuilder complexCollectionBuilder,
+        string? name)
+    {
+        Check.NullButNotEmpty(name);
+
+        complexCollectionBuilder.Metadata.SetJsonPropertyName(name);
+
+        return complexCollectionBuilder;
+    }
+
+    /// <summary>
+    ///     Configures the complex property contained in a JSON column to map to a specific JSON property,
+    ///     rather than using the property name.
+    /// </summary>
+    /// <param name="complexCollectionBuilder">The builder for the property being configured.</param>
+    /// <param name="name">JSON property name to be used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexCollectionBuilder<TComplex> HasJsonPropertyName<TComplex>(
+        this ComplexCollectionBuilder<TComplex> complexCollectionBuilder,
+        string? name)
+        where TComplex : notnull
+        => (ComplexCollectionBuilder<TComplex>)HasJsonPropertyName((ComplexCollectionBuilder)complexCollectionBuilder, name);
+}

src/EFCore.Relational/Extensions/RelationalComplexPropertyBuilderExtensions.cs

@@ -0,0 +1,75 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.EntityFrameworkCore;
+
+/// <summary>
+///     Relational database specific extension methods for <see cref="ComplexPropertyBuilder" />.
+/// </summary>
+/// <remarks>
+///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see> for more information and examples.
+/// </remarks>
+public static class RelationalComplexPropertyBuilderExtensions
+{
+    /// <summary>
+    ///     Configures the complex property to be stored as a JSON column.
+    /// </summary>
+    /// <param name="complexPropertyBuilder">The builder for the complex property being configured.</param>
+    /// <param name="jsonColumnName">The name of the JSON column. If not specified, the complex property name is used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexPropertyBuilder ToJson(
+        this ComplexPropertyBuilder complexPropertyBuilder,
+        string? jsonColumnName = null)
+    {
+        Check.NullButNotEmpty(jsonColumnName);
+
+        var complexProperty = complexPropertyBuilder.Metadata;
+
+        complexProperty.ComplexType.SetContainerColumnName(jsonColumnName ?? complexProperty.Name);
+
+        return complexPropertyBuilder;
+    }
+
+    /// <summary>
+    ///     Configures the complex property to be stored as a JSON column.
+    /// </summary>
+    /// <param name="complexPropertyBuilder">The builder for the complex property being configured.</param>
+    /// <param name="jsonColumnName">The name of the JSON column. If not specified, the complex property name is used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexPropertyBuilder<TComplex> ToJson<TComplex>(
+        this ComplexPropertyBuilder<TComplex> complexPropertyBuilder,
+        string? jsonColumnName = null)
+        where TComplex : class
+        => (ComplexPropertyBuilder<TComplex>)ToJson((ComplexPropertyBuilder)complexPropertyBuilder, jsonColumnName);
+
+    /// <summary>
+    ///     Configures the complex property of an entity mapped to a JSON column, mapping the complex property to a specific JSON property,
+    ///     rather than using the complex property name.
+    /// </summary>
+    /// <param name="complexPropertyBuilder">The builder for the complex property being configured.</param>
+    /// <param name="name">JSON property name to be used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexPropertyBuilder HasJsonPropertyName(
+        this ComplexPropertyBuilder complexPropertyBuilder,
+        string? name)
+    {
+        Check.NullButNotEmpty(name);
+
+        complexPropertyBuilder.Metadata.SetJsonPropertyName(name);
+
+        return complexPropertyBuilder;
+    }
+
+    /// <summary>
+    ///     Configures the complex property of an entity mapped to a JSON column, mapping the complex property to a specific JSON property,
+    ///     rather than using the complex property name.
+    /// </summary>
+    /// <param name="complexPropertyBuilder">The builder for the complex property being configured.</param>
+    /// <param name="name">JSON property name to be used.</param>
+    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
+    public static ComplexPropertyBuilder<TComplex> HasJsonPropertyName<TComplex>(
+        this ComplexPropertyBuilder<TComplex> complexPropertyBuilder,
+        string? name)
+        where TComplex : notnull
+        => (ComplexPropertyBuilder<TComplex>)HasJsonPropertyName((ComplexPropertyBuilder)complexPropertyBuilder, name);
+}

src/EFCore.Relational/Extensions/RelationalComplexPropertyExtensions.cs

@@ -0,0 +1,62 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.EntityFrameworkCore;
+
+/// <summary>
+///     Complex property extension methods for relational database metadata.
+/// </summary>
+/// <remarks>
+///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see> for more information and examples.
+/// </remarks>
+public static class RelationalComplexPropertyExtensions
+{
+    /// <summary>
+    ///     Gets the value of JSON property name used for the given complex property of an entity mapped to a JSON column.
+    /// </summary>
+    /// <remarks>
+    ///     Unless configured explicitly, complex property name is used.
+    /// </remarks>
+    /// <param name="complexProperty">The complex property.</param>
+    /// <returns>
+    ///     The value for the JSON property used to store the value of this complex property.
+    ///     <see langword="null" /> is returned for complex properties of entities that are not mapped to a JSON column.
+    /// </returns>
+    public static string? GetJsonPropertyName(this IReadOnlyComplexProperty complexProperty)
+        => (string?)complexProperty.FindAnnotation(RelationalAnnotationNames.JsonPropertyName)?.Value
+            ?? (!complexProperty.DeclaringType.IsMappedToJson() ? null : complexProperty.Name);
+
+    /// <summary>
+    ///     Sets the value of JSON property name used for the given complex property of an entity mapped to a JSON column.
+    /// </summary>
+    /// <param name="complexProperty">The complex property.</param>
+    /// <param name="name">The name to be used.</param>
+    public static void SetJsonPropertyName(this IMutableComplexProperty complexProperty, string? name)
+        => complexProperty.SetOrRemoveAnnotation(
+            RelationalAnnotationNames.JsonPropertyName,
+            Check.NullButNotEmpty(name));
+
+    /// <summary>
+    ///     Sets the value of JSON property name used for the given complex property of an entity mapped to a JSON column.
+    /// </summary>
+    /// <param name="complexProperty">The complex property.</param>
+    /// <param name="name">The name to be used.</param>
+    /// <param name="fromDataAnnotation">Indicates whether the configuration was specified using a data annotation.</param>
+    /// <returns>The configured value.</returns>
+    public static string? SetJsonPropertyName(
+        this IConventionComplexProperty complexProperty,
+        string? name,
+        bool fromDataAnnotation = false)
+        => (string?)complexProperty.SetOrRemoveAnnotation(
+            RelationalAnnotationNames.JsonPropertyName,
+            Check.NullButNotEmpty(name),
+            fromDataAnnotation)?.Value;
+
+    /// <summary>
+    ///     Gets the <see cref="ConfigurationSource" /> for the JSON property name for a given complex property.
+    /// </summary>
+    /// <param name="complexProperty">The complex property.</param>
+    /// <returns>The <see cref="ConfigurationSource" /> for the JSON property name for a given complex property.</returns>
+    public static ConfigurationSource? GetJsonPropertyNameConfigurationSource(this IConventionComplexProperty complexProperty)
+        => complexProperty.FindAnnotation(RelationalAnnotationNames.JsonPropertyName)?.GetConfigurationSource();
+}

src/EFCore.Relational/Extensions/RelationalComplexTypeExtensions.cs

@@ -22,4 +22,34 @@ public static class RelationalComplexTypeExtensions
         => complexType.FindAnnotation(RelationalAnnotationNames.ContainerColumnName)?.Value is string columnName
             ? columnName
             : complexType.ComplexProperty.DeclaringType.GetContainerColumnName();
+
+    /// <summary>
+    ///     Sets the name of the container column to which the complex type is mapped.
+    /// </summary>
+    /// <param name="complexType">The complex type to set the container column name for.</param>
+    /// <param name="columnName">The name to set.</param>
+    public static void SetContainerColumnName(this IMutableComplexType complexType, string? columnName)
+        => complexType.SetOrRemoveAnnotation(RelationalAnnotationNames.ContainerColumnName, columnName);
+
+    /// <summary>
+    ///     Sets the name of the container column to which the complex type is mapped.
+    /// </summary>
+    /// <param name="complexType">The complex type to set the container column name for.</param>
+    /// <param name="columnName">The name to set.</param>
+    /// <param name="fromDataAnnotation">Indicates whether the configuration was specified using a data annotation.</param>
+    /// <returns>The configured value.</returns>
+    public static string? SetContainerColumnName(
+        this IConventionComplexType complexType,
+        string? columnName,
+        bool fromDataAnnotation = false)
+        => (string?)complexType.SetAnnotation(RelationalAnnotationNames.ContainerColumnName, columnName, fromDataAnnotation)?.Value;
+
+    /// <summary>
+    ///     Gets the <see cref="ConfigurationSource" /> for the container column name.
+    /// </summary>
+    /// <param name="complexType">The complex type to set the container column name for.</param>
+    /// <returns>The <see cref="ConfigurationSource" /> for the container column name.</returns>
+    public static ConfigurationSource? GetContainerColumnNameConfigurationSource(this IConventionComplexType complexType)
+        => complexType.FindAnnotation(RelationalAnnotationNames.ContainerColumnName)
+            ?.GetConfigurationSource();
 }