Code changes to fix tests. Refactored API.

Microsoft.Azure.Cosmos/src/ConnectionPolicy.cs

@@ -92,7 +92,14 @@ public void SetPreferredLocations(IReadOnlyList<string> regions)
             }
         }
 
-        public void SetRegionalEndpoints(IReadOnlyList<string> regionalEndpoints)
+        /// <summary>
+        /// Sets the regional endpoints required to fetch account information from
+        /// private domain names.
+        /// </summary>
+        /// <param name="regionalEndpoints">An instance of <see cref="ISet{T}"/> containing the regional endpoints
+        /// provided by the customer.</param>
+        public void SetRegionalEndpoints(
+            ISet<string> regionalEndpoints)
         {
             if (regionalEndpoints == null)
             {

Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs

@@ -192,39 +192,35 @@ public string ApplicationName
         public IReadOnlyList<string> ApplicationPreferredRegions { get; set; }
 
         /// <summary>
-        /// Gets and sets the preferred regions for geo-replicated database accounts in the Azure Cosmos DB service. 
+        /// Gets and sets the regional private endpoints for geo-replicated database accounts in the Azure Cosmos DB service. 
         /// </summary>
         /// <remarks>
         /// <para>
         /// During the CosmosClient initialization the account information, including the available regions, is obtained from the <see cref="CosmosClient.Endpoint"/>.
-        /// The CosmosClient will use the value of <see cref="RegionalEndpoints"/> to populate the preferred list with the account available regions that intersect with its value.
-        /// If the value of <see cref="RegionalEndpoints"/> contains regions that are not an available region in the account, the values will be ignored. If the these invalid regions are added later to the account, the CosmosClient will use them if they are higher in the preference order.
+        /// Should the global endpoint become inaccessible, the CosmosClient will attempt to obtain the account information issuing requests to the regional endpoints provided in <see cref="RegionalEndpoints"/>.
         /// </para>
         /// <para>
-        /// If during CosmosClient initialization, the <see cref="CosmosClient.Endpoint"/> is not reachable, the CosmosClient will attempt to recover and obtain the account information issuing requests to the regions in <see cref="ApplicationPreferredRegions"/> in the order that they are listed.
+        /// Nevertheless, this parameter remains optional and is recommended for implementation when a customer has configured a private endpoint for their Cosmos DB account.
         /// </para>
         /// <para>
         /// See also <seealso href="https://docs.microsoft.com/azure/cosmos-db/sql/troubleshoot-sdk-availability">Diagnose
         /// and troubleshoot the availability of Cosmos SDKs</seealso> for more details.
         /// </para>
-        /// <para>
-        /// This configuration is an alternative to <see cref="ApplicationRegion"/>, either one can be set but not both.
-        /// </para>
         /// </remarks>
         /// <example>
         /// <code language="c#">
         /// <![CDATA[
         /// CosmosClientOptions clientOptions = new CosmosClientOptions()
         /// {
-        ///     RegionalEndpoints = new List<string>(){ "custom.p-1.documents.azure.com", "custom.p-2.documents.azure.com" }
+        ///     RegionalEndpoints = new HashSet<string>(){ "custom.p-1.documents.azure.com", "custom.p-2.documents.azure.com" }
         /// };
         /// 
         /// CosmosClient client = new CosmosClient("endpoint", "key", clientOptions);
         /// ]]>
         /// </code>
         /// </example>
         /// <seealso href="https://docs.microsoft.com/azure/cosmos-db/high-availability#high-availability-with-cosmos-db-in-the-event-of-regional-outages">High availability on regional outages</seealso>
-        public IReadOnlyList<string> RegionalEndpoints { get; set; }
+        public ISet<string> RegionalEndpoints { get; set; }
 
         /// <summary>
         /// Get or set the maximum number of concurrent connections allowed for the target

Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs

@@ -301,6 +301,36 @@ public CosmosClientBuilder WithApplicationPreferredRegions(IReadOnlyList<string>
             return this;
         }
 
+        /// <summary>
+        /// Sets the regional private endpoints for geo-replicated database accounts in the Azure Cosmos DB service. 
+        /// During the CosmosClient initialization the account information, including the available regions, is obtained from the <see cref="CosmosClient.Endpoint"/>.
+        /// Should the global endpoint become inaccessible, the CosmosClient will attempt to obtain the account information issuing requests to the regional endpoints
+        /// provided in the regionalEndpoints set.
+        /// </summary>
+        /// <param name="regionalEndpoints">A set of string containing the regional private endpoints for the cosmos db account.</param>
+        /// <remarks>
+        ///  This function is optional and is recommended for implementation when a customer has configured one or more private endpoints for their Cosmos DB account.
+        /// </remarks>
+        /// <example>
+        /// The example below creates a new instance of <see cref="CosmosClientBuilder"/> with the regional endpoints.
+        /// <code language="c#">
+        /// <![CDATA[
+        /// CosmosClientBuilder cosmosClientBuilder = new CosmosClientBuilder(
+        ///     accountEndpoint: "https://testcosmos.documents.azure.com:443/",
+        ///     authKeyOrResourceToken: "SuperSecretKey")
+        /// .WithRegionalEndpoints(new HashSet<string>() { "https://region-1.documents-test.windows-int.net:443/", "https://region-2.documents-test.windows-int.net:443/" });
+        /// CosmosClient client = cosmosClientBuilder.Build();
+        /// ]]>
+        /// </code>
+        /// </example>
+        /// <returns>The current <see cref="CosmosClientBuilder"/>.</returns>
+        /// <seealso cref="CosmosClientOptions.RegionalEndpoints"/>
+        public CosmosClientBuilder WithRegionalEndpoints(ISet<string> regionalEndpoints)
+        {
+            this.clientOptions.RegionalEndpoints = regionalEndpoints;
+            return this;
+        }
+
         /// <summary>
         /// Limits the operations to the provided endpoint on the CosmosClientBuilder constructor.
         /// </summary>

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/Contracts/DotNetSDKAPI.json

@@ -2782,6 +2782,18 @@
           ],
           "MethodInfo": "System.Collections.Generic.IReadOnlyList`1[System.String] get_ApplicationPreferredRegions();IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
         },
+        "System.Collections.Generic.ISet`1[System.String] get_RegionalEndpoints()[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
+          "Type": "Method",
+          "Attributes": [
+            "CompilerGeneratedAttribute"
+          ],
+          "MethodInfo": "System.Collections.Generic.ISet`1[System.String] get_RegionalEndpoints();IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
+        "System.Collections.Generic.ISet`1[System.String] RegionalEndpoints": {
+          "Type": "Property",
+          "Attributes": [],
+          "MethodInfo": "System.Collections.Generic.ISet`1[System.String] RegionalEndpoints;CanRead:True;CanWrite:True;System.Collections.Generic.ISet`1[System.String] get_RegionalEndpoints();IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;Void set_RegionalEndpoints(System.Collections.Generic.ISet`1[System.String]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
         "System.Collections.ObjectModel.Collection`1[Microsoft.Azure.Cosmos.RequestHandler] CustomHandlers[Newtonsoft.Json.JsonConverterAttribute(typeof(Microsoft.Azure.Cosmos.CosmosClientOptions+ClientOptionJsonConverter))]": {
           "Type": "Property",
           "Attributes": [
@@ -3096,6 +3108,13 @@
           "Attributes": [],
           "MethodInfo": "Void set_PortReuseMode(System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
         },
+        "Void set_RegionalEndpoints(System.Collections.Generic.ISet`1[System.String])[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
+          "Type": "Method",
+          "Attributes": [
+            "CompilerGeneratedAttribute"
+          ],
+          "MethodInfo": "Void set_RegionalEndpoints(System.Collections.Generic.ISet`1[System.String]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
         "Void set_RequestTimeout(System.TimeSpan)[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
           "Type": "Method",
           "Attributes": [
@@ -4599,6 +4618,11 @@
           "Attributes": [],
           "MethodInfo": "Microsoft.Azure.Cosmos.Fluent.CosmosClientBuilder WithLimitToEndpoint(Boolean);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
         },
+        "Microsoft.Azure.Cosmos.Fluent.CosmosClientBuilder WithRegionalEndpoints(System.Collections.Generic.ISet`1[System.String])": {
+          "Type": "Method",
+          "Attributes": [],
+          "MethodInfo": "Microsoft.Azure.Cosmos.Fluent.CosmosClientBuilder WithRegionalEndpoints(System.Collections.Generic.ISet`1[System.String]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
         "Microsoft.Azure.Cosmos.Fluent.CosmosClientBuilder WithRequestTimeout(System.TimeSpan)": {
           "Type": "Method",
           "Attributes": [],

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/CosmosClientOptionsUnitTests.cs

@@ -156,7 +156,9 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
             Assert.IsFalse(policy.EnablePartitionLevelFailover);
             Assert.IsTrue(clientOptions.EnableAdvancedReplicaSelectionForTcp.Value);
 
-            IReadOnlyList<string> preferredLocations = new List<string>() { Regions.AustraliaCentral, Regions.AustraliaCentral2 };
+            IReadOnlyList<string> preferredLocations = new List<string>() { Regions.AustraliaCentral, Regions.AustraliaCentral2 };
+            ISet<string> regionalEndpoints = new HashSet<string>() { "https://testfed2.documents-test.windows-int.net:443/", "https://testfed4.documents-test.windows-int.net:443/" };
+
             //Verify Direct Mode settings
             cosmosClientBuilder = new CosmosClientBuilder(
                 accountEndpoint: endpoint,
@@ -168,7 +170,8 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
                 maxTcpConnectionsPerEndpoint,
                 portReuseMode,
                 enableTcpConnectionEndpointRediscovery)
-                .WithApplicationPreferredRegions(preferredLocations)
+                .WithApplicationPreferredRegions(preferredLocations)
+                .WithRegionalEndpoints(regionalEndpoints)
                 .WithClientTelemetryOptions(new CosmosClientTelemetryOptions()
                 {
                     DisableDistributedTracing = false,
@@ -188,7 +191,8 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
             Assert.AreEqual(maxTcpConnectionsPerEndpoint, clientOptions.MaxTcpConnectionsPerEndpoint);
             Assert.AreEqual(portReuseMode, clientOptions.PortReuseMode);
             Assert.IsTrue(clientOptions.EnableTcpConnectionEndpointRediscovery);
-            CollectionAssert.AreEqual(preferredLocations.ToArray(), clientOptions.ApplicationPreferredRegions.ToArray());
+            CollectionAssert.AreEqual(preferredLocations.ToArray(), clientOptions.ApplicationPreferredRegions.ToArray());
+            CollectionAssert.AreEqual(regionalEndpoints.ToArray(), clientOptions.RegionalEndpoints.ToArray());
             Assert.AreEqual(TimeSpan.FromMilliseconds(100), clientOptions.CosmosClientTelemetryOptions.CosmosThresholdOptions.PointOperationLatencyThreshold);
             Assert.AreEqual(TimeSpan.FromMilliseconds(100), clientOptions.CosmosClientTelemetryOptions.CosmosThresholdOptions.NonPointOperationLatencyThreshold);
             Assert.IsFalse(clientOptions.CosmosClientTelemetryOptions.DisableDistributedTracing);
@@ -320,6 +324,13 @@ public void CosmosClientOptions_WhenPartitionLevelFailoverEnabledAndPreferredReg
                         Regions.NorthCentralUS,
                         Regions.WestUS,
                         Regions.EastAsia,
+                        })
+                    .WithRegionalEndpoints(
+                        new HashSet<string>()
+                        {
+                        "https://testfed2.documents-test.windows-int.net:443/",
+                        "https://testfed3.documents-test.windows-int.net:443/",
+                        "https://testfed4.documents-test.windows-int.net:443/",
                         });
 
                 CosmosClientOptions clientOptions = cosmosClientBuilder.Build().ClientOptions;
@@ -337,7 +348,8 @@ public void CosmosClientOptions_WhenPartitionLevelFailoverEnabledAndPreferredReg
                 Assert.IsFalse(clientOptions.AllowBulkExecution);
                 Assert.AreEqual(consistencyLevel, clientOptions.ConsistencyLevel);
                 Assert.IsTrue(clientOptions.EnablePartitionLevelFailover);
-                Assert.IsNotNull(clientOptions.ApplicationPreferredRegions);
+                Assert.IsNotNull(clientOptions.ApplicationPreferredRegions);
+                Assert.IsNotNull(clientOptions.RegionalEndpoints);
             }
             finally
             {

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/CosmosClientTests.cs

@@ -138,7 +138,7 @@ public async Task InvalidKey_ExceptionFullStacktrace(string endpoint, string key
             }
             catch (Exception ex)
             {
-                Assert.IsTrue(ex.StackTrace.Contains("GatewayAccountReader.GetDatabaseAccountAsync"), ex.StackTrace);
+                Assert.IsTrue(ex.StackTrace.Contains("GatewayAccountReader.InitializeReaderAsync"), ex.StackTrace);
             }
         }
 

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/GatewayAccountReaderTests.cs

@@ -142,7 +142,7 @@ public async Task InitializeReaderAsync_WhenRegionalEndpointsProvided_ShouldRetr
             if (regionalEndpointsProvided)
             {
                 connectionPolicy.SetRegionalEndpoints(
-                    new List<string>()
+                    new HashSet<string>()
                     {
                     "https://testfed2.documents-test.windows-int.net:443/",
                     "https://testfed3.documents-test.windows-int.net:443/",
@@ -193,7 +193,7 @@ public async Task InitializeReaderAsync_WhenRegionalEndpointsProvided_ShouldThro
             };
 
             connectionPolicy.SetRegionalEndpoints(
-                new List<string>()
+                new HashSet<string>()
                 {
                 "https://testfed2.documents-test.windows-int.net:443/",
                 "https://testfed3.documents-test.windows-int.net:443/",