Add IP address preference support for TCP connection (#1015)

doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml

@@ -0,0 +1,40 @@
+<docs>
+ <members name="SqlConnectionIPAddressPreference">
+ <SqlConnectionIPAddressPreferenceNetfx>
+ <summary>
+ Specifies a value for IP address preference during a TCP connection.
+ </summary>
+ <remarks>
+ <format type="text/markdown"><![CDATA[
+
+## Remarks
+If `Multi Subnet Failover` or "Transparent Network IP Resolution" is set to `true`, this setting has no effect.
+]]></format>
+ </remarks>
+ </SqlConnectionIPAddressPreferenceNetfx>
+ <SqlConnectionIPAddressPreference>
+ <summary>
+ Specifies a value for IP address preference during a TCP connection.
+ </summary>
+ <remarks>
+ <format type="text/markdown"><![CDATA[
+
+## Remarks
+If `Multi Subnet Failover` is set to `true`, this setting has no effect.
+]]></format>
+ </remarks>
+ </SqlConnectionIPAddressPreference>
+ <IPv4First>
+ <summary>Connects using IPv4 address(es) first. If the connection fails, try IPv6 address(es), if provided. This is the default value.</summary>
+ <value>0</value>
+ </IPv4First>
+ <IPv6First>
+ <summary>Connect using IPv6 address(es) first. If the connection fails, try IPv4 address(es), if available.</summary>
+ <value>1</value>
+ </IPv6First>
+ <UsePlatformDefault>
+ <summary>Connects with IP addresses in the order the underlying platform or operating system provides them.</summary>
+ <value>2</value>
+ </UsePlatformDefault>
+ </members>
+</docs>

doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml

@@ -346,6 +346,17 @@ False
  </remarks>
  <exception cref="T:System.ArgumentNullException">To set the value to null, use <see cref="F:System.DBNull.Value" />.</exception>
  </DataSource>
+ <IPAddressPreference>
+ <summary>Gets or sets the value of IP address preference.</summary>
+ <returns>Returns IP address preference.</returns>
+ <remarks>
+ <format type="text/markdown"><![CDATA[
+
+## Remarks
+If `Multi Subnet Failover` is set to `true`, this setting has no effect.
+]]></format>
+ </remarks>
+ </IPAddressPreference>
  <EnclaveAttestationUrl>
  <summary>Gets or sets the enclave attestation Url to be used with enclave based Always Encrypted.</summary>
  <value>The enclave attestation Url.</value>

src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs

@@ -398,6 +398,18 @@ public enum SqlConnectionAttestationProtocol
  HGS = 3
  }
 #endif
+ /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml' path='docs/members[@name="SqlConnectionIPAddressPreference"]/SqlConnectionIPAddressPreference/*' />
+ public enum SqlConnectionIPAddressPreference
+ {
+ /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml' path='docs/members[@name="SqlConnectionIPAddressPreference"]/IPv4First/*' />
+ IPv4First = 0, // default
+
+ /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml' path='docs/members[@name="SqlConnectionIPAddressPreference"]/IPv6First/*' />
+ IPv6First = 1,
+
+ /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionIPAddressPreference.xml' path='docs/members[@name="SqlConnectionIPAddressPreference"]/UsePlatformDefault/*' />
+ UsePlatformDefault = 2
+ }
  /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionCertificateStoreProvider.xml' path='docs/members[@name="SqlColumnEncryptionCertificateStoreProvider"]/SqlColumnEncryptionCertificateStoreProvider/*'/>
  public partial class SqlColumnEncryptionCertificateStoreProvider : Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider
  {
@@ -883,6 +895,10 @@ public SqlConnectionStringBuilder(string connectionString) { }
  [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)]
  public string EnclaveAttestationUrl { get { throw null; } set { } }
 #endif
+ /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml' path='docs/members[@name="SqlConnectionStringBuilder"]/IPAddressPreference/*'/>
+ [System.ComponentModel.DisplayNameAttribute("IP Address Preference")]
+ [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)]
+ public Microsoft.Data.SqlClient.SqlConnectionIPAddressPreference IPAddressPreference { get { throw null; } set { } }
  /// <include file='../../../../doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml' path='docs/members[@name="SqlConnectionStringBuilder"]/Encrypt/*'/>
  [System.ComponentModel.DisplayNameAttribute("Encrypt")]
  [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)]

src/Microsoft.Data.SqlClient/netcore/src/Interop/SNINativeMethodWrapper.Windows.cs

@@ -165,6 +165,7 @@ private unsafe struct SNI_CLIENT_CONSUMER_INFO
  public TransparentNetworkResolutionMode transparentNetworkResolution;
  public int totalTimeout;
  public bool isAzureSqlServerEndpoint;
+ public SqlConnectionIPAddressPreference ipAddressPreference;
  public SNI_DNSCache_Info DNSCacheInfo;
  }
 
@@ -275,6 +276,7 @@ private static extern uint SNIOpenWrapper(
  [In] SNIHandle pConn,
  out IntPtr ppConn,
  [MarshalAs(UnmanagedType.Bool)] bool fSync,
+ SqlConnectionIPAddressPreference ipPreference,
  [In] ref SNI_DNSCache_Info pDNSCachedInfo);
 
  [DllImport(SNI, CallingConvention = CallingConvention.Cdecl)]
@@ -341,7 +343,7 @@ internal static uint SNIInitialize()
  return SNIInitialize(IntPtr.Zero);
  }
 
- internal static unsafe uint SNIOpenMarsSession(ConsumerInfo consumerInfo, SNIHandle parent, ref IntPtr pConn, bool fSync, SQLDNSInfo cachedDNSInfo)
+ internal static unsafe uint SNIOpenMarsSession(ConsumerInfo consumerInfo, SNIHandle parent, ref IntPtr pConn, bool fSync, SqlConnectionIPAddressPreference ipPreference, SQLDNSInfo cachedDNSInfo)
  {
  // initialize consumer info for MARS
  Sni_Consumer_Info native_consumerInfo = new Sni_Consumer_Info();
@@ -353,10 +355,11 @@ internal static unsafe uint SNIOpenMarsSession(ConsumerInfo consumerInfo, SNIHan
  native_cachedDNSInfo.wszCachedTcpIPv6 = cachedDNSInfo?.AddrIPv6;
  native_cachedDNSInfo.wszCachedTcpPort = cachedDNSInfo?.Port;
 
- return SNIOpenWrapper(ref native_consumerInfo, "session:", parent, out pConn, fSync, ref native_cachedDNSInfo);
+ return SNIOpenWrapper(ref native_consumerInfo, "session:", parent, out pConn, fSync, ipPreference, ref native_cachedDNSInfo);
  }
 
- internal static unsafe uint SNIOpenSyncEx(ConsumerInfo consumerInfo, string constring, ref IntPtr pConn, byte[] spnBuffer, byte[] instanceName, bool fOverrideCache, bool fSync, int timeout, bool fParallel, SQLDNSInfo cachedDNSInfo)
+ internal static unsafe uint SNIOpenSyncEx(ConsumerInfo consumerInfo, string constring, ref IntPtr pConn, byte[] spnBuffer, byte[] instanceName, bool fOverrideCache, 
+ bool fSync, int timeout, bool fParallel, SqlConnectionIPAddressPreference ipPreference, SQLDNSInfo cachedDNSInfo)
  {
  fixed (byte* pin_instanceName = &instanceName[0])
  {
@@ -379,6 +382,7 @@ internal static unsafe uint SNIOpenSyncEx(ConsumerInfo consumerInfo, string cons
  clientConsumerInfo.totalTimeout = SniOpenTimeOut;
  clientConsumerInfo.isAzureSqlServerEndpoint = ADP.IsAzureSqlServerEndpoint(constring);
 
+ clientConsumerInfo.ipAddressPreference = ipPreference;
  clientConsumerInfo.DNSCacheInfo.wszCachedFQDN = cachedDNSInfo?.FQDN;
  clientConsumerInfo.DNSCacheInfo.wszCachedTcpIPv4 = cachedDNSInfo?.AddrIPv4;
  clientConsumerInfo.DNSCacheInfo.wszCachedTcpIPv6 = cachedDNSInfo?.AddrIPv6;

src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/Common/DbConnectionStringCommon.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.Globalization;
 using System.Reflection;
@@ -400,6 +401,110 @@ internal static SqlConnectionAttestationProtocol ConvertToAttestationProtocol(st
 
  #endregion
 
+ #region <<IPAddressPreference Utility>>
+ /// <summary>
+ /// IP Address Preference.
+ /// </summary>
+ private readonly static Dictionary<string, SqlConnectionIPAddressPreference> s_preferenceNames = new(StringComparer.InvariantCultureIgnoreCase);
+
+ static DbConnectionStringBuilderUtil()
+ {
+ foreach (SqlConnectionIPAddressPreference item in Enum.GetValues(typeof(SqlConnectionIPAddressPreference)))
+ {
+ s_preferenceNames.Add(item.ToString(), item);
+ }
+ }
+
+ /// <summary>
+ /// Convert a string value to the corresponding IPAddressPreference.
+ /// </summary>
+ /// <param name="value">The string representation of the enumeration name to convert.</param>
+ /// <param name="result">When this method returns, `result` contains an object of type `SqlConnectionIPAddressPreference` whose value is represented by `value` if the operation succeeds. 
+ /// If the parse operation fails, `result` contains the default value of the `SqlConnectionIPAddressPreference` type.</param>
+ /// <returns>`true` if the value parameter was converted successfully; otherwise, `false`.</returns>
+ internal static bool TryConvertToIPAddressPreference(string value, out SqlConnectionIPAddressPreference result)
+ {
+ if (!s_preferenceNames.TryGetValue(value, out result))
+ {
+ result = DbConnectionStringDefaults.IPAddressPreference;
+ return false;
+ }
+ return true;
+ }
+
+ /// <summary>
+ /// Verifies if the `value` is defined in the expected Enum.
+ /// </summary>
+ internal static bool IsValidIPAddressPreference(SqlConnectionIPAddressPreference value)
+ => value == SqlConnectionIPAddressPreference.IPv4First
+ || value == SqlConnectionIPAddressPreference.IPv6First
+ || value == SqlConnectionIPAddressPreference.UsePlatformDefault;
+
+ internal static string IPAddressPreferenceToString(SqlConnectionIPAddressPreference value)
+ => Enum.GetName(typeof(SqlConnectionIPAddressPreference), value);
+
+ internal static SqlConnectionIPAddressPreference ConvertToIPAddressPreference(string keyword, object value)
+ {
+ if (value is null)
+ {
+ return DbConnectionStringDefaults.IPAddressPreference; // IPv4First
+ }
+
+ if (value is string sValue)
+ {
+ // try again after remove leading & trailing whitespaces.
+ sValue = sValue.Trim();
+ if (TryConvertToIPAddressPreference(sValue, out SqlConnectionIPAddressPreference result))
+ {
+ return result;
+ }
+
+ // string values must be valid
+ throw ADP.InvalidConnectionOptionValue(keyword);
+ }
+ else
+ {
+ // the value is not string, try other options
+ SqlConnectionIPAddressPreference eValue;
+
+ if (value is SqlConnectionIPAddressPreference preference)
+ {
+ eValue = preference;
+ }
+ else if (value.GetType().IsEnum)
+ {
+ // explicitly block scenarios in which user tries to use wrong enum types, like:
+ // builder["SqlConnectionIPAddressPreference"] = EnvironmentVariableTarget.Process;
+ // workaround: explicitly cast non-SqlConnectionIPAddressPreference enums to int
+ throw ADP.ConvertFailed(value.GetType(), typeof(SqlConnectionIPAddressPreference), null);
+ }
+ else
+ {
+ try
+ {
+ // Enum.ToObject allows only integral and enum values (enums are blocked above), raising ArgumentException for the rest
+ eValue = (SqlConnectionIPAddressPreference)Enum.ToObject(typeof(SqlConnectionIPAddressPreference), value);
+ }
+ catch (ArgumentException e)
+ {
+ // to be consistent with the messages we send in case of wrong type usage, replace
+ // the error with our exception, and keep the original one as inner one for troubleshooting
+ throw ADP.ConvertFailed(value.GetType(), typeof(SqlConnectionIPAddressPreference), e);
+ }
+ }
+
+ if (IsValidIPAddressPreference(eValue))
+ {
+ return eValue;
+ }
+ else
+ {
+ throw ADP.InvalidEnumerationValue(typeof(SqlConnectionIPAddressPreference), (int)eValue);
+ }
+ }
+ }
+ #endregion
+
  internal static bool IsValidApplicationIntentValue(ApplicationIntent value)
  {
  Debug.Assert(Enum.GetNames(typeof(ApplicationIntent)).Length == 2, "ApplicationIntent enum has changed, update needed");
@@ -728,6 +833,7 @@ internal static partial class DbConnectionStringDefaults
  internal const SqlConnectionColumnEncryptionSetting ColumnEncryptionSetting = SqlConnectionColumnEncryptionSetting.Disabled;
  internal const string EnclaveAttestationUrl = _emptyString;
  internal const SqlConnectionAttestationProtocol AttestationProtocol = SqlConnectionAttestationProtocol.NotSpecified;
+ internal const SqlConnectionIPAddressPreference IPAddressPreference = SqlConnectionIPAddressPreference.IPv4First;
  }
 
 
@@ -765,6 +871,7 @@ internal static partial class DbConnectionStringKeywords
  internal const string ColumnEncryptionSetting = "Column Encryption Setting";
  internal const string EnclaveAttestationUrl = "Enclave Attestation Url";
  internal const string AttestationProtocol = "Attestation Protocol";
+ internal const string IPAddressPreference = "IP Address Preference";
 
  // common keywords (OleDb, OracleClient, SqlClient)
  internal const string DataSource = "Data Source";
@@ -793,6 +900,9 @@ internal static class DbConnectionStringSynonyms
  //internal const string ApplicationName = APP;
  internal const string APP = "app";
 
+ // internal const string IPAddressPreference = IPADDRESSPREFERENCE;
+ internal const string IPADDRESSPREFERENCE = "IPAddressPreference";
+
  //internal const string ApplicationIntent = APPLICATIONINTENT;
  internal const string APPLICATIONINTENT = "ApplicationIntent";
 

src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SNI/SNIProxy.cs

@@ -254,10 +254,12 @@ internal uint WritePacket(SNIHandle handle, SNIPacket packet, bool sync)
  /// <param name="async">Asynchronous connection</param>
  /// <param name="parallel">Attempt parallel connects</param>
  /// <param name="isIntegratedSecurity"></param>
+ /// <param name="ipPreference">IP address preference</param>
  /// <param name="cachedFQDN">Used for DNS Cache</param>
- /// <param name="pendingDNSInfo">Used for DNS Cache</param>
+ /// <param name="pendingDNSInfo">Used for DNS Cache</param> 
  /// <returns>SNI handle</returns>
- internal SNIHandle CreateConnectionHandle(string fullServerName, bool ignoreSniOpenTimeout, long timerExpire, out byte[] instanceName, ref byte[][] spnBuffer, bool flushCache, bool async, bool parallel, bool isIntegratedSecurity, string cachedFQDN, ref SQLDNSInfo pendingDNSInfo)
+ internal SNIHandle CreateConnectionHandle(string fullServerName, bool ignoreSniOpenTimeout, long timerExpire, out byte[] instanceName, ref byte[][] spnBuffer, 
+ bool flushCache, bool async, bool parallel, bool isIntegratedSecurity, SqlConnectionIPAddressPreference ipPreference, string cachedFQDN, ref SQLDNSInfo pendingDNSInfo)
  {
  instanceName = new byte[1];
 
@@ -284,7 +286,7 @@ internal SNIHandle CreateConnectionHandle(string fullServerName, bool ignoreSniO
  case DataSource.Protocol.Admin:
  case DataSource.Protocol.None: // default to using tcp if no protocol is provided
  case DataSource.Protocol.TCP:
- sniHandle = CreateTcpHandle(details, timerExpire, parallel, cachedFQDN, ref pendingDNSInfo);
+ sniHandle = CreateTcpHandle(details, timerExpire, parallel, ipPreference, cachedFQDN, ref pendingDNSInfo);
  break;
  case DataSource.Protocol.NP:
  sniHandle = CreateNpHandle(details, timerExpire, parallel);
@@ -374,10 +376,11 @@ private static byte[][] GetSqlServerSPNs(string hostNameOrAddress, string portOr
  /// <param name="details">Data source</param>
  /// <param name="timerExpire">Timer expiration</param>
  /// <param name="parallel">Should MultiSubnetFailover be used</param>
+ /// <param name="ipPreference">IP address preference</param>
  /// <param name="cachedFQDN">Key for DNS Cache</param>
- /// <param name="pendingDNSInfo">Used for DNS Cache</param>
+ /// <param name="pendingDNSInfo">Used for DNS Cache</param> 
  /// <returns>SNITCPHandle</returns>
- private SNITCPHandle CreateTcpHandle(DataSource details, long timerExpire, bool parallel, string cachedFQDN, ref SQLDNSInfo pendingDNSInfo)
+ private SNITCPHandle CreateTcpHandle(DataSource details, long timerExpire, bool parallel, SqlConnectionIPAddressPreference ipPreference, string cachedFQDN, ref SQLDNSInfo pendingDNSInfo)
  {
  // TCP Format:
  // tcp:<host name>\<instance name>
@@ -415,7 +418,7 @@ private SNITCPHandle CreateTcpHandle(DataSource details, long timerExpire, bool
  port = isAdminConnection ? DefaultSqlServerDacPort : DefaultSqlServerPort;
  }
 
- return new SNITCPHandle(hostName, port, timerExpire, parallel, cachedFQDN, ref pendingDNSInfo);
+ return new SNITCPHandle(hostName, port, timerExpire, parallel, ipPreference, cachedFQDN, ref pendingDNSInfo);
  }