Rollup of feedback from Batch 1 PR

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

@@ -13,7 +13,7 @@
       <value>1</value>
     </AlwaysBlock>
     <NeverBlock>
-      <summary>Blocking period OFF for Azure SQL servers, but ON for all other SQL servers.</summary>
+      <summary>Blocking period OFF for all SQL servers, including Azure SQL servers.</summary>
       <value>2</value>
     </NeverBlock>
   </members>

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

@@ -2,17 +2,17 @@
   <members name="SqlAuthenticationInitializer">
     <SqlAuthenticationInitializer>
       <summary>
-        Called from constructors in derived classes to initialize the <see cref="T:Microsoft.Data.SqlClient.SqlAuthenticationInitializer" /> class.
+        Called during instantiation of the first <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> instance.
       </summary>
     </SqlAuthenticationInitializer>
     <ctor>
       <summary>
-        Default Constructor to initialize the <see cref="T:Microsoft.Data.SqlClient.SqlAuthenticationInitializer" /> class.
+        Default constructor to instantiate the <see cref="T:Microsoft.Data.SqlClient.SqlAuthenticationInitializer" /> class.
       </summary>
     </ctor>
     <Initialize>
       <summary>
-        When overridden in a derived class, initializes the authentication initializer. This method is called by the <see cref="M:Microsoft.Data.SqlClient.SqlAuthenticationInitializer.#ctor" /> constructor during startup.
+        When overridden in a derived class, initializes the authentication initializer. This method is called immediately after the <see cref="M:Microsoft.Data.SqlClient.SqlAuthenticationInitializer.#ctor" /> constructor during instantiation of the first <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> instance.
       </summary>
     </Initialize>
   </members>

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

@@ -1,18 +1,18 @@
 <docs>
   <members name="SqlAuthenticationMethod">
     <SqlAuthenticationMethod>
-      <summary>Describes the different SQL authentication methods that can be used by a client connecting to Azure SQL Database. For details, see <see href="https://docs.microsoft.com/azure/sql-database/sql-database-aad-authentication">Connecting to SQL Database By Using Azure Active Directory Authentication</see>.</summary>
+      <summary>Describes the different SQL authentication methods that can be used by a client connecting to Azure SQL Database. For details, see <see href="https://learn.microsoft.com/azure/azure-sql/database/authentication-aad-overview">Use Microsoft Entra Authentication</see>.</summary>
     </SqlAuthenticationMethod>
     <NotSpecified>
       <summary>The authentication method is not specified.</summary>
       <value>0</value>
     </NotSpecified>
     <SqlPassword>
-      <summary>The authentication method is Sql Password.</summary>
+      <summary>The authentication method uses Sql Password. Use Sql Password to connect to a SQL Database using SQL Server authentication.</summary>
       <value>1</value>
     </SqlPassword>
     <ActiveDirectoryPassword>
-      <summary>The authentication method uses Active Directory Password. Use Active Directory Password to connect to a SQL Database using an Azure AD principal name and password.</summary>
+      <summary>The authentication method uses Active Directory Password. Use Active Directory Password to connect to a SQL Database using a Microsoft Entra principal name and password.</summary>
       <value>2</value>
     </ActiveDirectoryPassword>
     <ActiveDirectoryIntegrated>

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

@@ -23,33 +23,34 @@
               {
                   public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
                   {
-                      string clientId = "my-client-id";
-                      string clientName = "My Application Name";
-                      string s_defaultScopeSuffix = "/.default";
-          
-                      string[] scopes = new string[] { parameters.Resource.EndsWith(s_defaultScopeSuffix) ? parameters.Resource : parameters.Resource + s_defaultScopeSuffix };
-          
-                      IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
+                      const string ClientId = "my-client-id";
+                      const string ClientName = "My Application Name";
+                      const string DefaultScopeSuffix = "/.default";
+
+                      string[] scopes = [ parameters.Resource.EndsWith(DefaultScopeSuffix) ? parameters.Resource : parameters.Resource + DefaultScopeSuffix ];
+
+                      IPublicClientApplication app = PublicClientApplicationBuilder.Create(ClientId)
                           .WithAuthority(parameters.Authority)
-                          .WithClientName(clientName)
+                          .WithClientName(ClientName)
                           .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
                           .Build();
-
-                      AuthenticationResult result = await app.AcquireTokenWithDeviceCode(scopes,
-                      deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult)).ExecuteAsync();
+                      using CancellationTokenSource connectionTimeoutCancellation = new CancellationTokenSource(TimeSpan.FromSeconds(parameters.ConnectionTimeout));
+
+                      AuthenticationResult result = await app.AcquireTokenWithDeviceCode(scopes, CustomDeviceFlowCallback)
+                          .ExecuteAsync(connectionTimeoutCancellation.Token);
                       return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
                   }
-          
+
                   public override bool IsSupported(SqlAuthenticationMethod authenticationMethod) =>
                       authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
-          
+
                   private Task CustomDeviceFlowCallback(DeviceCodeResult result)
                   {
                       Console.WriteLine(result.Message);
-                      return Task.FromResult(0);
+                      return Task.CompletedTask;
                   }
               }
-          
+
               public class Program
               {
                   public static void Main()
@@ -87,16 +88,16 @@
     </SetProvider>
     <BeforeLoad>
       <param name="authenticationMethod">The authentication method.</param>
-      <summary>This method is called immediately before the provider is added to SQL drivers registry.</summary>
+      <summary>This method is called immediately before the provider is added to SQL authentication provider registry.</summary>
       <remarks>
         Avoid performing long-waiting tasks in this method, since it can block other threads from accessing the provider registry.
       </remarks>
     </BeforeLoad>
     <BeforeUnload>
       <param name="authenticationMethod">The authentication method.</param>
-      <summary>This method is called immediately before the provider is removed from the SQL drivers registry.</summary>
+      <summary>This method is called immediately before the provider is removed from the SQL authentication provider registry.</summary>
       <remarks>
-        For example, this method is called when a different provider with the same authentication method overrides this provider in the SQL drivers registry. Avoid performing long-waiting task in this method, since it can block other threads from accessing the provider registry.
+        For example, this method is called when a different provider with the same authentication method overrides this provider in the SQL authentication provider registry. Avoid performing long-waiting task in this method, since it can block other threads from accessing the provider registry.
       </remarks>
     </BeforeUnload>
     <IsSupported>

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

@@ -1,7 +1,7 @@
 <docs>
   <members name="SqlAuthenticationToken">
     <SqlAuthenticationToken>
-      <summary>Represents an AD authentication token.</summary>
+      <summary>Represents an authentication token.</summary>
     </SqlAuthenticationToken>
     <ctor>
       <param name="accessToken">The access token.</param>

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

@@ -152,7 +152,7 @@
                   using var connection = new SqlConnection(connString);
                   connection.Open();
 
-                  var batch = new SqlBatch(connection);
+                  using var batch = new SqlBatch(connection);
 
                   const int count = 10;
                   const string parameterName = "parameter";
@@ -163,9 +163,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List<int>(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {
@@ -185,7 +182,7 @@
     </BatchCommands>
     <Commands>
       <summary>
-        The list of commands contained in the batch in a <see cref="T:System.Collections.IList" /> of <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> objects.
+        The list of commands contained in the batch in a <see cref="T:System.Collections.Generic.List{Microsoft.Data.SqlClient.SqlBatchCommand}" />.
       </summary>
     </Commands>
     <ExecuteReader>
@@ -213,7 +210,7 @@
                   using var connection = new SqlConnection(connString);
                   connection.Open();
 
-                  var batch = new SqlBatch(connection);
+                  using var batch = new SqlBatch(connection);
 
                   const int count = 10;
                   const string parameterName = "parameter";
@@ -224,9 +221,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List&lt;int&gt;(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {