Cosmos: Add a way to configure Application Preferred Regions

Fixes #29424

Author: AndriySvyryd

src/EFCore.Cosmos/Infrastructure/CosmosDbContextOptionsBuilder.cs

@@ -65,6 +65,17 @@ public virtual CosmosDbContextOptionsBuilder ExecutionStrategy(
     public virtual CosmosDbContextOptionsBuilder Region(string region)
         => WithOption(e => e.WithRegion(Check.NotNull(region, nameof(region))));
 
+    /// <summary>
+    ///     Configures the context to use the provided preferred regions for geo-replicated database accounts.
+    /// </summary>
+    /// <remarks>
+    ///     See <see href="https://aka.ms/efcore-docs-dbcontext-options">Using DbContextOptions</see>, and
+    ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information and examples.
+    /// </remarks>
+    /// <param name="regions">A list of Azure Cosmos DB region names.</param>
+    public virtual CosmosDbContextOptionsBuilder PreferredRegions(IReadOnlyList<string> regions)
+        => WithOption(e => e.WithPreferredRegions(Check.NotNull(regions, nameof(regions))));
+
     /// <summary>
     ///     Limits the operations to the provided endpoint.
     /// </summary>

src/EFCore.Cosmos/Infrastructure/Internal/CosmosDbOptionExtension.cs

@@ -23,6 +23,7 @@ public class CosmosOptionsExtension : IDbContextOptionsExtension
     private string? _connectionString;
     private string? _databaseName;
     private string? _region;
+    private IReadOnlyList<string>? _preferredRegions;
     private ConnectionMode? _connectionMode;
     private bool? _limitToEndpoint;
     private Func<ExecutionStrategyDependencies, IExecutionStrategy>? _executionStrategyFactory;
@@ -61,6 +62,7 @@ protected CosmosOptionsExtension(CosmosOptionsExtension copyFrom)
         _databaseName = copyFrom._databaseName;
         _connectionString = copyFrom._connectionString;
         _region = copyFrom._region;
+        _preferredRegions = copyFrom._preferredRegions;
         _connectionMode = copyFrom._connectionMode;
         _limitToEndpoint = copyFrom._limitToEndpoint;
         _executionStrategyFactory = copyFrom._executionStrategyFactory;
@@ -247,6 +249,30 @@ public virtual CosmosOptionsExtension WithRegion(string? region)
         return clone;
     }
 
+    /// <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 virtual IReadOnlyList<string>? PreferredRegions
+        => _preferredRegions;
+
+    /// <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 virtual CosmosOptionsExtension WithPreferredRegions(IReadOnlyList<string>? regions)
+    {
+        var clone = Clone();
+
+        clone._preferredRegions = regions;
+
+        return clone;
+    }
+
     /// <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

src/EFCore.Cosmos/Infrastructure/Internal/CosmosSingletonOptions.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Collections;
 using System.Net;
 using Azure.Core;
 
@@ -54,6 +55,14 @@ public class CosmosSingletonOptions : ICosmosSingletonOptions
     /// </summary>
     public virtual string? Region { get; private set; }
 
+    /// <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 virtual IReadOnlyList<string>? PreferredRegions { get; private set; }
+
     /// <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
@@ -158,6 +167,7 @@ public virtual void Initialize(IDbContextOptions options)
             TokenCredential = cosmosOptions.TokenCredential;
             ConnectionString = cosmosOptions.ConnectionString;
             Region = cosmosOptions.Region;
+            PreferredRegions = cosmosOptions.PreferredRegions;
             LimitToEndpoint = cosmosOptions.LimitToEndpoint;
             EnableContentResponseOnWrite = cosmosOptions.EnableContentResponseOnWrite;
             ConnectionMode = cosmosOptions.ConnectionMode;
@@ -188,6 +198,7 @@ public virtual void Validate(IDbContextOptions options)
                 || TokenCredential != cosmosOptions.TokenCredential
                 || ConnectionString != cosmosOptions.ConnectionString
                 || Region != cosmosOptions.Region
+                || !StructuralComparisons.StructuralEqualityComparer.Equals(PreferredRegions, cosmosOptions.PreferredRegions) 
                 || LimitToEndpoint != cosmosOptions.LimitToEndpoint
                 || ConnectionMode != cosmosOptions.ConnectionMode
                 || WebProxy != cosmosOptions.WebProxy

src/EFCore.Cosmos/Infrastructure/Internal/ICosmosSingletonOptions.cs

@@ -60,6 +60,14 @@ public interface ICosmosSingletonOptions : ISingletonOptions
     /// </summary>
     string? Region { get; }
 
+    /// <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>
+    IReadOnlyList<string>? PreferredRegions { get; }
+
     /// <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

src/EFCore.Cosmos/Storage/Internal/SingletonCosmosClientWrapper.cs

@@ -41,6 +41,11 @@ public SingletonCosmosClientWrapper(ICosmosSingletonOptions options)
             configuration.ApplicationRegion = options.Region;
         }
 
+        if (options.PreferredRegions != null)
+        {
+            configuration.ApplicationPreferredRegions = options.PreferredRegions;
+        }
+
         if (options.LimitToEndpoint != null)
         {
             configuration.LimitToEndpoint = options.LimitToEndpoint.Value;

test/EFCore.Cosmos.Tests/Extensions/CosmosDbContextOptionsExtensionsTests.cs

@@ -71,6 +71,8 @@ public void Can_create_options_with_valid_values()
         Test(o => o.Region(Regions.EastAsia), o => Assert.Equal(Regions.EastAsia, o.Region));
         // The region will be validated by the Cosmos SDK, because the region list is not constant
         Test(o => o.Region("FakeRegion"), o => Assert.Equal("FakeRegion", o.Region));
+        Test(o => o.PreferredRegions(new[] { Regions.AustraliaCentral, Regions.EastAsia }),
+            o => Assert.Equal(new[] { Regions.AustraliaCentral, Regions.EastAsia }, o.PreferredRegions));
         Test(o => o.ConnectionMode(ConnectionMode.Direct), o => Assert.Equal(ConnectionMode.Direct, o.ConnectionMode));
         Test(o => o.GatewayModeMaxConnectionLimit(3), o => Assert.Equal(3, o.GatewayModeMaxConnectionLimit));
         Test(o => o.MaxRequestsPerTcpConnection(3), o => Assert.Equal(3, o.MaxRequestsPerTcpConnection));