Cosmos API review changes

src/EFCore.Cosmos/Extensions/CosmosLoggerExtensions.cs → src/EFCore.Cosmos/Diagnostics/Internal/CosmosLoggerExtensions.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
@@ -7,17 +7,29 @@
 using System.Linq;
 using System.Text;
 using JetBrains.Annotations;
-using Microsoft.EntityFrameworkCore.Cosmos.Storage;
+using Microsoft.EntityFrameworkCore.Cosmos.Storage.Internal;
 using Microsoft.EntityFrameworkCore.Diagnostics;
 using Microsoft.Extensions.Logging;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 
 // ReSharper disable once CheckNamespace
-namespace Microsoft.EntityFrameworkCore
+namespace Microsoft.EntityFrameworkCore.Cosmos.Diagnostics.Internal
 {
+    /// <summary>
+    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+    ///     any release. You should only use it directly in your code with extreme caution and knowing that
+    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+    /// </summary>
     public static class CosmosLoggerExtensions
     {
+        /// <summary>
+        ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+        ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+        ///     any release. You should only use it directly in your code with extreme caution and knowing that
+        ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+        /// </summary>
         public static void ExecutingSqlQuery(
             [NotNull] this IDiagnosticsLogger<DbLoggerCategory.Database.Command> diagnosticsLogger,
             CosmosSqlQuery cosmosSqlQuery)

src/EFCore.Cosmos/Extensions/CosmosDbContextOptionsExtensions.cs

@@ -3,16 +3,28 @@
 
 using System;
 using JetBrains.Annotations;
-using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure;
-using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure.Internal;
 using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure.Internal;
 using Microsoft.EntityFrameworkCore.Utilities;
 
 // ReSharper disable once CheckNamespace
 namespace Microsoft.EntityFrameworkCore
 {
+    /// <summary>
+    ///     Cosmos-specific extension methods for <see cref="DbContextOptionsBuilder" />.
+    /// </summary>
     public static class CosmosDbContextOptionsExtensions
     {
+        /// <summary>
+        ///     Configures the context to connect to an Azure Cosmos database.
+        /// </summary>
+        /// <typeparam name="TContext"> The type of context to be configured. </typeparam>
+        /// <param name="optionsBuilder"> The builder being used to configure the context. </param>
+        /// <param name="accountEndpoint"> The account end-point to connect to. </param>
+        /// <param name="accountKey"> The account key. </param>
+        /// <param name="databaseName"> The database name. </param>
+        /// <param name="cosmosOptionsAction">An optional action to allow additional Cosmos-specific configuration.</param>
+        /// <returns> The options builder so that further configuration can be chained. </returns>
         public static DbContextOptionsBuilder<TContext> UseCosmos<TContext>(
             [NotNull] this DbContextOptionsBuilder<TContext> optionsBuilder,
             [NotNull] string accountEndpoint,
@@ -27,6 +39,15 @@ public static DbContextOptionsBuilder<TContext> UseCosmos<TContext>(
                 databaseName,
                 cosmosOptionsAction);
 
+        /// <summary>
+        ///     Configures the context to connect to a Azure Cosmos database.
+        /// </summary>
+        /// <param name="optionsBuilder"> The builder being used to configure the context. </param>
+        /// <param name="accountEndpoint"> The account end-point to connect to. </param>
+        /// <param name="accountKey"> The account key. </param>
+        /// <param name="databaseName"> The database name. </param>
+        /// <param name="cosmosOptionsAction">An optional action to allow additional Cosmos-specific configuration.</param>
+        /// <returns> The options builder so that further configuration can be chained. </returns>
         public static DbContextOptionsBuilder UseCosmos(
             [NotNull] this DbContextOptionsBuilder optionsBuilder,
             [NotNull] string accountEndpoint,

src/EFCore.Cosmos/Extensions/CosmosEntityTypeBuilderExtensions.cs

@@ -31,7 +31,7 @@ public static EntityTypeBuilder ForCosmosToContainer(
             Check.NotNull(entityTypeBuilder, nameof(entityTypeBuilder));
             Check.NullButNotEmpty(name, nameof(name));
 
-            entityTypeBuilder.Metadata.SetCosmosContainerName(name);
+            entityTypeBuilder.Metadata.SetCosmosContainer(name);
 
             return entityTypeBuilder;
         }
@@ -69,7 +69,7 @@ public static IConventionEntityTypeBuilder ForCosmosToContainer(
                 return null;
             }
 
-            entityTypeBuilder.Metadata.SetCosmosContainerName(name, fromDataAnnotation);
+            entityTypeBuilder.Metadata.SetCosmosContainer(name, fromDataAnnotation);
 
             return entityTypeBuilder;
         }

src/EFCore.Cosmos/Extensions/CosmosEntityTypeExtensions.cs

@@ -3,7 +3,6 @@
 
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Cosmos.Metadata.Internal;
-using Microsoft.EntityFrameworkCore.Cosmos.Storage.Internal;
 using Microsoft.EntityFrameworkCore.Metadata;
 using Microsoft.EntityFrameworkCore.Utilities;
 
@@ -20,22 +19,22 @@ public static class CosmosEntityTypeExtensions
         /// </summary>
         /// <param name="entityType"> The entity type to get the container name for. </param>
         /// <returns> The name of the container to which the entity type is mapped. </returns>
-        public static string GetCosmosContainerName([NotNull] this IEntityType entityType) =>
+        public static string GetCosmosContainer([NotNull] this IEntityType entityType) =>
             entityType.BaseType != null
-                ? entityType.RootType().GetCosmosContainerName()
+                ? entityType.RootType().GetCosmosContainer()
                 : (string)entityType[CosmosAnnotationNames.ContainerName]
-                  ?? GetCosmosDefaultContainerName(entityType);
+                  ?? GetCosmosDefaultContainer(entityType);
 
-        private static string GetCosmosDefaultContainerName(IEntityType entityType)
-            => entityType.Model.GetCosmosDefaultContainerName()
+        private static string GetCosmosDefaultContainer(IEntityType entityType)
+            => entityType.Model.GetCosmosDefaultContainer()
                ?? entityType.ShortName();
 
         /// <summary>
         ///     Sets the name of the container to which the entity type is mapped.
         /// </summary>
         /// <param name="entityType"> The entity type to set the container name for. </param>
         /// <param name="name"> The name to set. </param>
-        public static void SetCosmosContainerName([NotNull] this IMutableEntityType entityType, [CanBeNull] string name)
+        public static void SetCosmosContainer([NotNull] this IMutableEntityType entityType, [CanBeNull] string name)
             => entityType.SetOrRemoveAnnotation(
                 CosmosAnnotationNames.ContainerName,
                 Check.NullButNotEmpty(name, nameof(name)));
@@ -46,7 +45,7 @@ public static void SetCosmosContainerName([NotNull] this IMutableEntityType enti
         /// <param name="entityType"> The entity type to set the container name for. </param>
         /// <param name="name"> The name to set. </param>
         /// <param name="fromDataAnnotation"> Indicates whether the configuration was specified using a data annotation. </param>
-        public static void SetCosmosContainerName(
+        public static void SetCosmosContainer(
             [NotNull] this IConventionEntityType entityType, [CanBeNull] string name, bool fromDataAnnotation = false)
             => entityType.SetOrRemoveAnnotation(
                 CosmosAnnotationNames.ContainerName,
@@ -58,7 +57,7 @@ public static void SetCosmosContainerName(
         /// </summary>
         /// <param name="entityType"> The entity type to find configuration source for. </param>
         /// <returns> The <see cref="ConfigurationSource" /> for the container to which the entity type is mapped. </returns>
-        public static ConfigurationSource? GetCosmosContainerNameConfigurationSource([NotNull] this IConventionEntityType entityType)
+        public static ConfigurationSource? GetCosmosContainerConfigurationSource([NotNull] this IConventionEntityType entityType)
             => entityType.FindAnnotation(CosmosAnnotationNames.ContainerName)
                 ?.GetConfigurationSource();
 
@@ -145,21 +144,5 @@ public static void SetCosmosPartitionKeyPropertyName(
         public static ConfigurationSource? GetCosmosPartitionKeyPropertyNameConfigurationSource([NotNull] this IConventionEntityType entityType)
             => entityType.FindAnnotation(CosmosAnnotationNames.PartitionKeyName)
                 ?.GetConfigurationSource();
-
-        /// <summary>
-        ///     Returns the store name of the property that is used to store the partition key.
-        /// </summary>
-        /// <param name="entityType"> The entity type to get the partition key property name for. </param>
-        /// <returns> The name of the partition key property. </returns>
-        public static string GetCosmosPartitionKeyStoreName([NotNull] this IEntityType entityType)
-        {
-            var name = entityType.GetCosmosPartitionKeyPropertyName();
-            if (name != null)
-            {
-                return entityType.FindProperty(name).GetCosmosPropertyName();
-            }
-
-            return CosmosClientWrapper.DefaultPartitionKey;
-        }
     }
 }

src/EFCore.Cosmos/Extensions/CosmosModelBuilderExtensions.cs

@@ -21,14 +21,14 @@ public static class CosmosModelBuilderExtensions
         /// <param name="modelBuilder"> The model builder. </param>
         /// <param name="name"> The default container name. </param>
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
-        public static ModelBuilder ForCosmosHasDefaultContainerName(
+        public static ModelBuilder ForCosmosHasDefaultContainer(
             [NotNull] this ModelBuilder modelBuilder,
             [CanBeNull] string name)
         {
             Check.NotNull(modelBuilder, nameof(modelBuilder));
             Check.NullButNotEmpty(name, nameof(name));
 
-            modelBuilder.Model.SetCosmosDefaultContainerName(name);
+            modelBuilder.Model.SetCosmosDefaultContainer(name);
 
             return modelBuilder;
         }
@@ -44,17 +44,17 @@ public static ModelBuilder ForCosmosHasDefaultContainerName(
         ///     The same builder instance if the configuration was applied,
         ///     <c>null</c> otherwise.
         /// </returns>
-        public static IConventionModelBuilder ForCosmosHasDefaultContainerName(
+        public static IConventionModelBuilder ForCosmosHasDefaultContainer(
             [NotNull] this IConventionModelBuilder modelBuilder,
             [CanBeNull] string name,
             bool fromDataAnnotation = false)
         {
-            if (!modelBuilder.ForCosmosCanSetDefaultContainerName(name, fromDataAnnotation))
+            if (!modelBuilder.ForCosmosCanSetDefaultContainer(name, fromDataAnnotation))
             {
                 return null;
             }
 
-            modelBuilder.Metadata.SetCosmosDefaultContainerName(name, fromDataAnnotation);
+            modelBuilder.Metadata.SetCosmosDefaultContainer(name, fromDataAnnotation);
 
             return modelBuilder;
         }
@@ -66,7 +66,7 @@ public static IConventionModelBuilder ForCosmosHasDefaultContainerName(
         /// <param name="name"> The default container name. </param>
         /// <param name="fromDataAnnotation"> Indicates whether the configuration was specified using a data annotation. </param>
         /// <returns> <c>true</c> if the given container name can be set as default. </returns>
-        public static bool ForCosmosCanSetDefaultContainerName(
+        public static bool ForCosmosCanSetDefaultContainer(
             [NotNull] this IConventionModelBuilder modelBuilder,
             [CanBeNull] string name,
             bool fromDataAnnotation = false)

src/EFCore.Cosmos/Extensions/CosmosModelExtensions.cs

@@ -19,15 +19,15 @@ public static class CosmosModelExtensions
         /// </summary>
         /// <param name="model"> The model. </param>
         /// <returns> The default container name. </returns>
-        public static string GetCosmosDefaultContainerName([NotNull] this IModel model)
+        public static string GetCosmosDefaultContainer([NotNull] this IModel model)
             => (string)model[CosmosAnnotationNames.ContainerName];
 
         /// <summary>
         ///     Sets the default container name.
         /// </summary>
         /// <param name="model"> The model. </param>
         /// <param name="name"> The name to set. </param>
-        public static void SetCosmosDefaultContainerName([NotNull] this IMutableModel model, [CanBeNull] string name)
+        public static void SetCosmosDefaultContainer([NotNull] this IMutableModel model, [CanBeNull] string name)
             => model.SetOrRemoveAnnotation(
                 CosmosAnnotationNames.ContainerName,
                 Check.NullButNotEmpty(name, nameof(name)));
@@ -38,7 +38,7 @@ public static void SetCosmosDefaultContainerName([NotNull] this IMutableModel mo
         /// <param name="model"> The model. </param>
         /// <param name="name"> The name to set. </param>
         /// <param name="fromDataAnnotation"> Indicates whether the configuration was specified using a data annotation. </param>
-        public static void SetCosmosDefaultContainerName([NotNull] this IConventionModel model, [CanBeNull] string name, bool fromDataAnnotation = false)
+        public static void SetCosmosDefaultContainer([NotNull] this IConventionModel model, [CanBeNull] string name, bool fromDataAnnotation = false)
             => model.SetOrRemoveAnnotation(
                 CosmosAnnotationNames.ContainerName,
                 Check.NullButNotEmpty(name, nameof(name)),
@@ -49,7 +49,7 @@ public static void SetCosmosDefaultContainerName([NotNull] this IConventionModel
         /// </summary>
         /// <param name="model"> The model. </param>
         /// <returns> The configuration source for the default container name.</returns>
-        public static ConfigurationSource? GetCosmosDefaultContainerNameConfigurationSource([NotNull] this IConventionModel model)
+        public static ConfigurationSource? GetCosmosDefaultContainerConfigurationSource([NotNull] this IConventionModel model)
             => model.FindAnnotation(CosmosAnnotationNames.ContainerName)?.GetConfigurationSource();
     }
 }

src/EFCore.Cosmos/Extensions/CosmosServiceCollectionExtensions.cs

@@ -2,12 +2,12 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using JetBrains.Annotations;
+using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Cosmos.Diagnostics.Internal;
-using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure;
 using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure.Internal;
+using Microsoft.EntityFrameworkCore.Cosmos.Internal;
 using Microsoft.EntityFrameworkCore.Cosmos.Metadata.Conventions.Internal;
 using Microsoft.EntityFrameworkCore.Cosmos.Query.Internal;
-using Microsoft.EntityFrameworkCore.Cosmos.Query.Pipeline;
 using Microsoft.EntityFrameworkCore.Cosmos.Storage.Internal;
 using Microsoft.EntityFrameworkCore.Diagnostics;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -20,8 +20,28 @@
 // ReSharper disable once CheckNamespace
 namespace Microsoft.Extensions.DependencyInjection
 {
+    /// <summary>
+    ///     Cosmos-specific extension methods for <see cref="IServiceCollection" />.
+    /// </summary>
     public static class CosmosServiceCollectionExtensions
     {
+        /// <summary>
+        ///     <para>
+        ///         Adds the services required by the Azure Cosmos database provider for Entity Framework
+        ///         to an <see cref="IServiceCollection" />.
+        ///     </para>
+        ///     <para>
+        ///         Calling this method is no longer necessary when building most applications, including those that
+        ///         use dependency injection in ASP.NET or elsewhere.
+        ///         It is only needed when building the internal service provider for use with
+        ///         the <see cref="DbContextOptionsBuilder.UseInternalServiceProvider"/> method.
+        ///         This is not recommend other than for some advanced scenarios.
+        ///     </para>
+        /// </summary>
+        /// <param name="serviceCollection"> The <see cref="IServiceCollection" /> to add services to. </param>
+        /// <returns>
+        ///     The same service collection so that multiple calls can be chained.
+        /// </returns>
         public static IServiceCollection AddEntityFrameworkCosmos([NotNull] this IServiceCollection serviceCollection)
         {
             Check.NotNull(serviceCollection, nameof(serviceCollection));

src/EFCore.Cosmos/Infrastructure/CosmosDbContextOptionsBuilder.cs

@@ -5,23 +5,36 @@
 using System.ComponentModel;
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Cosmos.Infrastructure.Internal;
-using Microsoft.EntityFrameworkCore.Infrastructure;
 using Microsoft.EntityFrameworkCore.Storage;
 using Microsoft.EntityFrameworkCore.Utilities;
 
-namespace Microsoft.EntityFrameworkCore.Cosmos.Infrastructure
+namespace Microsoft.EntityFrameworkCore.Infrastructure
 {
+    /// <summary>
+    ///     <para>
+    ///         Allows Cosmos specific configuration to be performed on <see cref="DbContextOptions" />.
+    ///     </para>
+    ///     <para>
+    ///         Instances of this class are returned from a call to
+    ///         <see cref="CosmosDbContextOptionsExtensions.UseCosmos{TContext}" />
+    ///         and it is not designed to be directly constructed in your application code.
+    ///     </para>
+    /// </summary>
     public class CosmosDbContextOptionsBuilder
     {
+        private readonly DbContextOptionsBuilder _optionsBuilder;
+
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="CosmosDbContextOptionsBuilder" /> class.
+        /// </summary>
+        /// <param name="optionsBuilder"> The options builder. </param>
         public CosmosDbContextOptionsBuilder([NotNull] DbContextOptionsBuilder optionsBuilder)
         {
             Check.NotNull(optionsBuilder, nameof(optionsBuilder));
 
-            OptionsBuilder = optionsBuilder;
+            _optionsBuilder = optionsBuilder;
         }
 
-        protected virtual DbContextOptionsBuilder OptionsBuilder { get; }
-
         /// <summary>
         ///     Configures the context to use the provided <see cref="IExecutionStrategy" />.
         /// </summary>
@@ -34,7 +47,7 @@ public virtual CosmosDbContextOptionsBuilder ExecutionStrategy(
         /// Configures the context to use the provided Region.
         /// </summary>
         /// <param name="region">CosmosDB region name</param>
-        public virtual CosmosDbContextOptionsBuilder Region(string region)
+        public virtual CosmosDbContextOptionsBuilder Region([NotNull] string region)
             => WithOption(e => e.WithRegion(Check.NotNull(region, nameof(region))));
 
         /// <summary>
@@ -45,8 +58,8 @@ public virtual CosmosDbContextOptionsBuilder Region(string region)
         /// <returns> The same builder instance so that multiple calls can be chained. </returns>
         protected virtual CosmosDbContextOptionsBuilder WithOption([NotNull] Func<CosmosOptionsExtension, CosmosOptionsExtension> setAction)
         {
-            ((IDbContextOptionsBuilderInfrastructure)OptionsBuilder).AddOrUpdateExtension(
-                setAction(OptionsBuilder.Options.FindExtension<CosmosOptionsExtension>() ?? new CosmosOptionsExtension()));
+            ((IDbContextOptionsBuilderInfrastructure)_optionsBuilder).AddOrUpdateExtension(
+                setAction(_optionsBuilder.Options.FindExtension<CosmosOptionsExtension>() ?? new CosmosOptionsExtension()));
 
             return this;
         }