XML documentation corrections - batch 1

doc/samples/CustomDeviceCodeFlowAzureAuthenticationProvider.cs

@@ -2,6 +2,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Data.SqlClient;
 using Microsoft.Identity.Client;
@@ -14,49 +15,52 @@ namespace CustomAuthenticationProviderExamples
     /// </summary>
     public class CustomDeviceCodeFlowAzureAuthenticationProvider : SqlAuthenticationProvider
     {
-        private const string clientId = "my-client-id";
-        private const string clientName = "My Application Name";
-        private const string s_defaultScopeSuffix = "/.default";
+        private const string ClientId = "my-client-id";
+        private const string ClientName = "My Application Name";
+        private const string DefaultScopeSuffix = "/.default";
 
         // Maintain a copy of the PublicClientApplication object to cache the underlying access tokens it provides
         private static IPublicClientApplication pcApplication;
 
         public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
         {
-            string[] scopes = new string[] { parameters.Resource.EndsWith(s_defaultScopeSuffix) ? parameters.Resource : parameters.Resource + s_defaultScopeSuffix };
+            string[] scopes = [ parameters.Resource.EndsWith(DefaultScopeSuffix) ? parameters.Resource : parameters.Resource + DefaultScopeSuffix ];
 
             IPublicClientApplication app = pcApplication;
             if (app == null)
             {
-                pcApplication = app = PublicClientApplicationBuilder.Create(clientId)
+                pcApplication = app = PublicClientApplicationBuilder.Create(ClientId)
                     .WithAuthority(parameters.Authority)
-                    .WithClientName(clientName)
+                    .WithClientName(ClientName)
                     .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
-                .Build();
+                    .Build();
             }
 
             AuthenticationResult result;
+            using CancellationTokenSource connectionTimeoutCancellation = new CancellationTokenSource(TimeSpan.FromSeconds(parameters.ConnectionTimeout));
 
             try
             {
                 IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
-                result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault()).ExecuteAsync();
+                result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
+                    .ExecuteAsync(connectionTimeoutCancellation.Token);
             }
             catch (MsalUiRequiredException)
             {
-                result = await app.AcquireTokenWithDeviceCode(scopes,
-                        deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult)).ExecuteAsync();
+                result = await app.AcquireTokenWithDeviceCode(scopes, deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult))
+                    .ExecuteAsync(connectionTimeoutCancellation.Token);
             }
 
             return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
         }
 
-        public override bool IsSupported(SqlAuthenticationMethod authenticationMethod) => authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
+        public override bool IsSupported(SqlAuthenticationMethod authenticationMethod)
+            => authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
 
-        private static Task<int> CustomDeviceFlowCallback(DeviceCodeResult result)
+        private static Task CustomDeviceFlowCallback(DeviceCodeResult result)
         {
             Console.WriteLine(result.Message);
-            return Task.FromResult(0);
+            return Task.CompletedTask;
         }
     }
 

doc/samples/SqlBatch_ExecuteReader.cs

@@ -15,7 +15,7 @@ static void RunBatch(string connString)
         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";
@@ -26,9 +26,6 @@ static void RunBatch(string connString)
             batch.BatchCommands.Add(batchCommand);
         }
 
-        // Optionally Prepare
-        batch.Prepare();
-
         var results = new List<int>(count);
         using (SqlDataReader reader = batch.ExecuteReader())
         {

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 the opening of the first <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> instance to specify an Authentication connection string attribute.
       </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 the opening of the first <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> instance to specify an Authentication connection string attribute.
       </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,49 +23,52 @@
               /// </summary>
               public class CustomDeviceCodeFlowAzureAuthenticationProvider : SqlAuthenticationProvider
               {
-                  private const string clientId = "my-client-id";
-                  private const string clientName = "My Application Name";
-                  private const string s_defaultScopeSuffix = "/.default";
+                  private const string ClientId = "my-client-id";
+                  private const string ClientName = "My Application Name";
+                  private const string DefaultScopeSuffix = "/.default";
 
                   // Maintain a copy of the PublicClientApplication object to cache the underlying access tokens it provides
                   private static IPublicClientApplication pcApplication;
 
                   public override async Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters)
                   {
-                      string[] scopes = new string[] { parameters.Resource.EndsWith(s_defaultScopeSuffix) ? parameters.Resource : parameters.Resource + s_defaultScopeSuffix };
+                      string[] scopes = [ parameters.Resource.EndsWith(DefaultScopeSuffix) ? parameters.Resource : parameters.Resource + DefaultScopeSuffix ];
 
                       IPublicClientApplication app = pcApplication;
                       if (app == null)
                       {
-                          pcApplication = app = PublicClientApplicationBuilder.Create(clientId)
+                          pcApplication = app = PublicClientApplicationBuilder.Create(ClientId)
                               .WithAuthority(parameters.Authority)
-                              .WithClientName(clientName)
+                              .WithClientName(ClientName)
                               .WithRedirectUri("https://login.microsoftonline.com/common/oauth2/nativeclient")
-                          .Build();
+                              .Build();
                       }
 
                       AuthenticationResult result;
+                      using CancellationTokenSource connectionTimeoutCancellation = new CancellationTokenSource(TimeSpan.FromSeconds(parameters.ConnectionTimeout));
 
                       try
                       {
                           IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
-                          result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault()).ExecuteAsync();
+                          result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
+                              .ExecuteAsync(connectionTimeoutCancellation.Token);
                       }
                       catch (MsalUiRequiredException)
                       {
-                          result = await app.AcquireTokenWithDeviceCode(scopes,
-                                  deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult)).ExecuteAsync();
+                          result = await app.AcquireTokenWithDeviceCode(scopes, deviceCodeResult => CustomDeviceFlowCallback(deviceCodeResult))
+                              .ExecuteAsync(connectionTimeoutCancellation.Token);
                       }
 
                       return new SqlAuthenticationToken(result.AccessToken, result.ExpiresOn);
                   }
 
-                  public override bool IsSupported(SqlAuthenticationMethod authenticationMethod) => authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
+                  public override bool IsSupported(SqlAuthenticationMethod authenticationMethod) =>
+                      authenticationMethod.Equals(SqlAuthenticationMethod.ActiveDirectoryDeviceCodeFlow);
 
-                  private static Task<int> CustomDeviceFlowCallback(DeviceCodeResult result)
+                  private Task CustomDeviceFlowCallback(DeviceCodeResult result)
                   {
                       Console.WriteLine(result.Message);
-                      return Task.FromResult(0);
+                      return Task.CompletedTask;
                   }
               }
 
@@ -106,16 +109,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 the 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

@@ -22,7 +22,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";
@@ -33,9 +33,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List<int>(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {
@@ -77,7 +74,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";
@@ -88,9 +85,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List<lint>(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {
@@ -152,7 +146,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 +157,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List<int>(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {
@@ -185,7 +176,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 +204,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 +215,6 @@
                       batch.BatchCommands.Add(batchCommand);
                   }
 
-                  // Optionally Prepare
-                  batch.Prepare();
-
                   var results = new List&lt;int&gt;(count);
                   using (SqlDataReader reader = batch.ExecuteReader())
                   {