Chriss/token cache peristence options doc improvements

sdk/identity/Azure.Identity/src/AuthenticationRecord.cs

@@ -14,6 +14,7 @@ namespace Azure.Identity
     /// <summary>
     /// Account information relating to an authentication request.
     /// </summary>
+    /// <seealso cref="TokenCachePersistenceOptions"/>.
     public class AuthenticationRecord
     {
         internal const string CurrentVersion = "1.0";

sdk/identity/Azure.Identity/src/ClientCertificateCredentialOptions.cs

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class ClientCertificateCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

sdk/identity/Azure.Identity/src/ClientSecretCredentialOptions.cs

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class ClientSecretCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

sdk/identity/Azure.Identity/src/DeviceCodeCredentialOptions.cs

@@ -35,7 +35,7 @@ public string TenantId
         public string ClientId { get; set; } = Constants.DeveloperSignOnClientId;
 
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

sdk/identity/Azure.Identity/src/InteractiveBrowserCredentialOptions.cs

@@ -34,7 +34,7 @@ public string TenantId
         public string ClientId { get; set; } = Constants.DeveloperSignOnClientId;
 
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

sdk/identity/Azure.Identity/src/TokenCachePersistenceOptions.cs

@@ -1,11 +1,59 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 namespace Azure.Identity
 {
     /// <summary>
     /// Options controlling the storage of the token cache.
     /// </summary>
+    /// <example>
+    /// <para>
+    /// This is an example showing how TokenCachePersistenceOptions and an AuthenticationRecord can be used together to enable silent authentication
+    /// across executions of a client application.
+    /// </para>
+    /// <code snippet="Snippet:AuthenticationRecord_TokenCachePersistenceOptions" language="csharp">
+    /// const string TOKEN_CACHE_NAME = &quot;MyTokenCache&quot;;
+    /// InteractiveBrowserCredential credential;
+    /// AuthenticationRecord authRecord;
+    ///
+    /// // Check if an AuthenticationRecord exists on disk.
+    /// // If it does not exist, get one and serialize it to disk.
+    /// // If it does exist, load it from disk and deserialize it.
+    /// if (!File.Exists(AUTH_RECORD_PATH))
+    /// {
+    ///     // Construct a credential with TokenCachePersistenceOptions specified to ensure that the token cache is persisted to disk.
+    ///     // We can also optionally specify a name for the cache to avoid having it cleared by other applications.
+    ///     credential = new InteractiveBrowserCredential(
+    ///         new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME } });
+    ///
+    ///     // Call AuthenticateAsync to fetch a new AuthenticationRecord.
+    ///     authRecord = await credential.AuthenticateAsync();
+    ///
+    ///     // Serialize the AuthenticationRecord to disk so that it can be re-used across executions of this initialization code.
+    ///     using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write);
+    ///     await authRecord.SerializeAsync(authRecordStream);
+    /// }
+    /// else
+    /// {
+    ///     // Load the previously serialized AuthenticationRecord from disk and deserialize it.
+    ///     using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read);
+    ///     authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
+    /// }
+    ///
+    /// // Construct a new client with our TokenCachePersistenceOptions with the addition of the AuthenticationRecord property.
+    /// // This tells the credential to use the same token cache in addition to which account to try and fetch from cache when GetToken is called.
+    /// credential = new InteractiveBrowserCredential(
+    ///     new InteractiveBrowserCredentialOptions
+    ///     {
+    ///         TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME },
+    ///         AuthenticationRecord = authRecord
+    ///     });
+    ///
+    /// // Construct our client with the credential which is connected to the token cache
+    /// // with the capability of silent authentication for the account specified in the AuthenticationRecord.
+    /// var client = new SecretClient(new Uri(&quot;https://myvault.vault.azure.net/&quot;), credential);
+    /// </code>
+    /// </example>
     public class TokenCachePersistenceOptions
     {
         /// <summary>

sdk/identity/Azure.Identity/src/UsernamePasswordCredentialOptions.cs

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class UsernamePasswordCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
     }

sdk/identity/Azure.Identity/tests/samples/UserAuthenticationSnippets.cs

@@ -26,7 +26,7 @@ public void Identity_ClientSideUserAuthentication_SimpleInteractiveBrowser()
                 new InteractiveBrowserCredential()
             );
             #endregion
-        }
+    }
 
         public void Identity_ClientSideUserAuthentication_SimpleDeviceCode()
         {
@@ -120,41 +120,50 @@ public static async Task<TokenCredential> GetUserCredentialAsync()
 
         public static async Task Main()
         {
+            #region Snippet:AuthenticationRecord_TokenCachePersistenceOptions
+
+            const string TOKEN_CACHE_NAME = "MyTokenCache";
             InteractiveBrowserCredential credential;
+            AuthenticationRecord authRecord;
 
+            // Check if an AuthenticationRecord exists on disk.
+            // If it does not exist, get one and serialize it to disk.
+            // If it does exist, load it from disk and deserialize it.
             if (!File.Exists(AUTH_RECORD_PATH))
             {
+                // Construct a credential with TokenCachePersistenceOptions specified to ensure that the token cache is persisted to disk.
+                // We can also optionally specify a name for the cache to avoid having it cleared by other applications.
                 credential = new InteractiveBrowserCredential(
-                    new InteractiveBrowserCredentialOptions
-                    {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions()
-                    });
+                    new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME } });
 
-                AuthenticationRecord authRecord = await credential.AuthenticateAsync();
+                // Call AuthenticateAsync to fetch a new AuthenticationRecord.
+                authRecord = await credential.AuthenticateAsync();
 
-                using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write))
-                {
-                    await authRecord.SerializeAsync(authRecordStream);
-                }
+                // Serialize the AuthenticationRecord to disk so that it can be re-used across executions of this initialization code.
+                using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write);
+                await authRecord.SerializeAsync(authRecordStream);
             }
             else
             {
-                AuthenticationRecord authRecord;
+                // Load the previously serialized AuthenticationRecord from disk and deserialize it.
+                using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read);
+                authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
+            }
 
-                using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read))
+            // Construct a new client with our TokenCachePersistenceOptions with the addition of the AuthenticationRecord property.
+            // This tells the credential to use the same token cache in addition to which account to try and fetch from cache when GetToken is called.
+            credential = new InteractiveBrowserCredential(
+                new InteractiveBrowserCredentialOptions
                 {
-                    authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
-                }
-
-                credential = new InteractiveBrowserCredential(
-                    new InteractiveBrowserCredentialOptions
-                    {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(),
-                        AuthenticationRecord = authRecord
-                    });
-            }
+                    TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME },
+                    AuthenticationRecord = authRecord
+                });
 
+            // Construct our client with the credential which is connected to the token cache
+            // with the capability of silent authentication for the account specified in the AuthenticationRecord.
             var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
+
+            #endregion
         }
     }
 }