Moving prose into comments

dstrockis · dstrockis · commit 62c6a1817b09 · 2015-08-07T01:17:45.000-07:00
diff --git a/TodoListClient/MainWindow.xaml.cs b/TodoListClient/MainWindow.xaml.cs
@@ -46,12 +46,12 @@ namespace TodoListClient
     /// </summary>
     public partial class MainWindow : Window
     {
-        //
+        
         // The Client ID is used by the application to uniquely identify itself to the v2.0 endpoint
         // The AAD Instance is the instance of the v2.0 endpoint
         // The Redirect URI is the URI where the v2.0 endpoint will return OAuth responses.
         // The Authority is the sign-in URL.
-        //
+        
         private static string aadInstance = ConfigurationManager.AppSettings["ida:AADInstance"];
         private static string clientId = ConfigurationManager.AppSettings["ida:ClientId"];
         Uri redirectUri = new Uri(ConfigurationManager.AppSettings["ida:RedirectUri"]);
@@ -65,29 +65,36 @@ protected override async void OnInitialized(EventArgs e)
         {
             base.OnInitialized(e);
 
-            //
-            // As the application starts, try to get an access token without prompting the user.  If one exists, populate the To Do list.  If not, continue.
-            //
             authContext = new AuthenticationContext(authority, new FileCache());
             AuthenticationResult result = null;
 
+            // As the app starts, we want to check to see if the user is already signed in.
+            // You can do so by trying to get a token from ADAL, passing in the parameter
+            // PromptBehavior.Never.  This forces ADAL to throw an exception if it cannot
+            // get a token for the user without showing a UI.
+   
             try
             {
                 result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));
 
-                // A valid token is in the cache - get the To Do list.
+                // If we got here, a valid token is in the cache.  Proceed to 
+                // fetch the user's tasks from the TodoListService via the 
+                // GetTodoList() method.
+
                 SignInButton.Content = "Clear Cache";
                 GetTodoList();
             }
             catch (AdalException ex)
             {
                 if (ex.ErrorCode == "user_interaction_required")
                 {
-                    // There are no tokens in the cache.  Proceed without calling the To Do list service.
+                    // If user interaction is required, the app should take no action,
+                    // and simply show the user the sign in button.
                 }
                 else
                 {
-                    // An unexpected error occurred.
+                    // Here, we catch all other AdalExceptions
+
                     string message = ex.Message;
                     if (ex.InnerException != null)
                     {
@@ -106,25 +113,29 @@ public MainWindow()
 
         private async void GetTodoList()
         {
-            //
-            // Get an access token to call the To Do service.
-            //
             AuthenticationResult result = null;
             try
             {
+                // Here, we try to get an access token to call the TodoListService 
+                // without invoking any UI prompt.  PromptBehavior.Never forces
+                // ADAL to throw an exception if it cannot get a token silently.
+
                 result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));
             }
             catch (AdalException ex)
             {
-                // There is no access token in the cache, so prompt the user to sign-in.
+                // ADAL couldn't get a token silently, so show the user a message
+                // and let them click the Sign-In button.
+
                 if (ex.ErrorCode == "user_interaction_required")
                 {
                     MessageBox.Show("Please sign in first");
                     SignInButton.Content = "Sign In";
                 }
                 else
                 {
-                    // An unexpected error occurred.
+                    // In any other case, an unexpected error occurred.
+
                     string message = ex.Message;
                     if (ex.InnerException != null)
                     {
@@ -136,20 +147,21 @@ private async void GetTodoList()
                 return;
             }
 
-            // Once the token has been returned by ADAL, add it to the http authorization header, before making the call to access the To Do list service.
+            // Once the token has been returned by ADAL, 
+            // add it to the http authorization header, 
+            // before making the call to access the To Do list service.
+
             httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.Token);
 
+
             // Call the To Do list service.
             HttpResponseMessage response = await httpClient.GetAsync(todoListBaseAddress + "/api/todolist");
 
             if (response.IsSuccessStatusCode)
             {
-
-                // Read the response and databind to the GridView to display To Do items.
                 string s = await response.Content.ReadAsStringAsync();
                 JavaScriptSerializer serializer = new JavaScriptSerializer();
                 List<TodoItem> toDoArray = serializer.Deserialize<List<TodoItem>>(s);
-
                 TodoList.ItemsSource = toDoArray.Select(t => new { t.Title });
             }
             else
@@ -162,31 +174,28 @@ private async void GetTodoList()
 
         private async void AddTodoItem(object sender, RoutedEventArgs e)
         {
+            // This method follows the same pattern as GetTodoList()
+
             if (string.IsNullOrEmpty(TodoText.Text))
             {
                 MessageBox.Show("Please enter a value for the To Do item name");
                 return;
             }
 
-            //
-            // Get an access token to call the To Do service.
-            //
             AuthenticationResult result = null;
             try
             {
                 result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));
             }
             catch (AdalException ex)
             {
-                // There is no access token in the cache, so prompt the user to sign-in.
                 if (ex.ErrorCode == "user_interaction_required")
                 {
                     MessageBox.Show("Please sign in first");
                     SignInButton.Content = "Sign In";
                 }
                 else
                 {
-                    // An unexpected error occurred.
                     string message = ex.Message;
                     if (ex.InnerException != null)
                     {
@@ -199,17 +208,9 @@ private async void AddTodoItem(object sender, RoutedEventArgs e)
                 return;
             }
 
-            //
-            // Call the To Do service.
-            //
-
-            // Once the token has been returned by ADAL, add it to the http authorization header, before making the call to access the To Do service.
             httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.Token);
 
-            // Forms encode Todo item, to POST to the todo list web api.
             HttpContent content = new FormUrlEncodedContent(new[] { new KeyValuePair<string, string>("Title", TodoText.Text) });
-
-            // Call the To Do list service.
             HttpResponseMessage response = await httpClient.PostAsync(todoListBaseAddress + "/api/todolist", content);
 
             if (response.IsSuccessStatusCode)
@@ -225,20 +226,25 @@ private async void AddTodoItem(object sender, RoutedEventArgs e)
 
         private async void SignIn(object sender = null, RoutedEventArgs args = null)
         {
-            // If there is already a token in the cache, clear the cache and update the label on the button.
+            // If the user clicked the 'clear cache' button,
+            // clear the ADAL token cache and show the user as signed out.
+            // It's also necessary to clear the cookies from the browser
+            // control so the next user has a chance to sign in.
+
             if (SignInButton.Content.ToString() == "Clear Cache")
             {
                 TodoList.ItemsSource = string.Empty;
                 authContext.TokenCache.Clear();
-                // Also clear cookies from the browser control.
                 ClearCookies();
                 SignInButton.Content = "Sign In";
                 return;
             }
 
-            //
-            // Get an access token to call the To Do list service.
-            //
+            // If the user clicked the 'Sign-In' button, force
+            // ADAL to prompt the user for credentials by specifying
+            // PromptBehavior.Always.  ADAL will get a token for the 
+            // TodoListService and cache it for you.
+
             AuthenticationResult result = null;
             try
             {
@@ -248,6 +254,10 @@ private async void SignIn(object sender = null, RoutedEventArgs args = null)
             }
             catch (AdalException ex)
             {
+                // If ADAL cannot get a token, it will throw an exception.
+                // If the user canceled the login, it will result in the 
+                // error code 'authentication_canceled'.
+
                 if (ex.ErrorCode == "authentication_canceled")
                 {
                     MessageBox.Show("Sign in was canceled by the user");

Original file line number	Diff line number	Diff line change
`@@ -46,12 +46,12 @@ namespace TodoListClient`
`46`	`46`	`/// </summary>`
`47`	`47`	`public partial class MainWindow : Window`
`48`	`48`	`{`
`49`		`- //`
	`49`	`+`
`50`	`50`	`// The Client ID is used by the application to uniquely identify itself to the v2.0 endpoint`
`51`	`51`	`// The AAD Instance is the instance of the v2.0 endpoint`
`52`	`52`	`// The Redirect URI is the URI where the v2.0 endpoint will return OAuth responses.`
`53`	`53`	`// The Authority is the sign-in URL.`
`54`		`- //`
	`54`	`+`
`55`	`55`	`private static string aadInstance = ConfigurationManager.AppSettings["ida:AADInstance"];`
`56`	`56`	`private static string clientId = ConfigurationManager.AppSettings["ida:ClientId"];`
`57`	`57`	`Uri redirectUri = new Uri(ConfigurationManager.AppSettings["ida:RedirectUri"]);`
`@@ -65,29 +65,36 @@ protected override async void OnInitialized(EventArgs e)`
`65`	`65`	`{`
`66`	`66`	`base.OnInitialized(e);`
`67`	`67`
`68`		`- //`
`69`		`- // As the application starts, try to get an access token without prompting the user. If one exists, populate the To Do list. If not, continue.`
`70`		`- //`
`71`	`68`	`authContext = new AuthenticationContext(authority, new FileCache());`
`72`	`69`	`AuthenticationResult result = null;`
`73`	`70`
	`71`	`+ // As the app starts, we want to check to see if the user is already signed in.`
	`72`	`+ // You can do so by trying to get a token from ADAL, passing in the parameter`
	`73`	`+ // PromptBehavior.Never. This forces ADAL to throw an exception if it cannot`
	`74`	`+ // get a token for the user without showing a UI.`
	`75`	`+`
`74`	`76`	`try`
`75`	`77`	`{`
`76`	`78`	`result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));`
`77`	`79`
`78`		`- // A valid token is in the cache - get the To Do list.`
	`80`	`+ // If we got here, a valid token is in the cache. Proceed to`
	`81`	`+ // fetch the user's tasks from the TodoListService via the`
	`82`	`+ // GetTodoList() method.`
	`83`	`+`
`79`	`84`	`SignInButton.Content = "Clear Cache";`
`80`	`85`	`GetTodoList();`
`81`	`86`	`}`
`82`	`87`	`catch (AdalException ex)`
`83`	`88`	`{`
`84`	`89`	`if (ex.ErrorCode == "user_interaction_required")`
`85`	`90`	`{`
`86`		`- // There are no tokens in the cache. Proceed without calling the To Do list service.`
	`91`	`+ // If user interaction is required, the app should take no action,`
	`92`	`+ // and simply show the user the sign in button.`
`87`	`93`	`}`
`88`	`94`	`else`
`89`	`95`	`{`
`90`		`- // An unexpected error occurred.`
	`96`	`+ // Here, we catch all other AdalExceptions`
	`97`	`+`
`91`	`98`	`string message = ex.Message;`
`92`	`99`	`if (ex.InnerException != null)`
`93`	`100`	`{`
`@@ -106,25 +113,29 @@ public MainWindow()`
`106`	`113`
`107`	`114`	`private async void GetTodoList()`
`108`	`115`	`{`
`109`		`- //`
`110`		`- // Get an access token to call the To Do service.`
`111`		`- //`
`112`	`116`	`AuthenticationResult result = null;`
`113`	`117`	`try`
`114`	`118`	`{`
	`119`	`+ // Here, we try to get an access token to call the TodoListService`
	`120`	`+ // without invoking any UI prompt. PromptBehavior.Never forces`
	`121`	`+ // ADAL to throw an exception if it cannot get a token silently.`
	`122`	`+`
`115`	`123`	`result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));`
`116`	`124`	`}`
`117`	`125`	`catch (AdalException ex)`
`118`	`126`	`{`
`119`		`- // There is no access token in the cache, so prompt the user to sign-in.`
	`127`	`+ // ADAL couldn't get a token silently, so show the user a message`
	`128`	`+ // and let them click the Sign-In button.`
	`129`	`+`
`120`	`130`	`if (ex.ErrorCode == "user_interaction_required")`
`121`	`131`	`{`
`122`	`132`	`MessageBox.Show("Please sign in first");`
`123`	`133`	`SignInButton.Content = "Sign In";`
`124`	`134`	`}`
`125`	`135`	`else`
`126`	`136`	`{`
`127`		`- // An unexpected error occurred.`
	`137`	`+ // In any other case, an unexpected error occurred.`
	`138`	`+`
`128`	`139`	`string message = ex.Message;`
`129`	`140`	`if (ex.InnerException != null)`
`130`	`141`	`{`
`@@ -136,20 +147,21 @@ private async void GetTodoList()`
`136`	`147`	`return;`
`137`	`148`	`}`
`138`	`149`
`139`		`- // Once the token has been returned by ADAL, add it to the http authorization header, before making the call to access the To Do list service.`
	`150`	`+ // Once the token has been returned by ADAL,`
	`151`	`+ // add it to the http authorization header,`
	`152`	`+ // before making the call to access the To Do list service.`
	`153`	`+`
`140`	`154`	`httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.Token);`
`141`	`155`
	`156`	`+`
`142`	`157`	`// Call the To Do list service.`
`143`	`158`	`HttpResponseMessage response = await httpClient.GetAsync(todoListBaseAddress + "/api/todolist");`
`144`	`159`
`145`	`160`	`if (response.IsSuccessStatusCode)`
`146`	`161`	`{`
`147`		`-`
`148`		`- // Read the response and databind to the GridView to display To Do items.`
`149`	`162`	`string s = await response.Content.ReadAsStringAsync();`
`150`	`163`	`JavaScriptSerializer serializer = new JavaScriptSerializer();`
`151`	`164`	`List<TodoItem> toDoArray = serializer.Deserialize<List<TodoItem>>(s);`
`152`		`-`
`153`	`165`	`TodoList.ItemsSource = toDoArray.Select(t => new { t.Title });`
`154`	`166`	`}`
`155`	`167`	`else`
`@@ -162,31 +174,28 @@ private async void GetTodoList()`
`162`	`174`
`163`	`175`	`private async void AddTodoItem(object sender, RoutedEventArgs e)`
`164`	`176`	`{`
	`177`	`+ // This method follows the same pattern as GetTodoList()`
	`178`	`+`
`165`	`179`	`if (string.IsNullOrEmpty(TodoText.Text))`
`166`	`180`	`{`
`167`	`181`	`MessageBox.Show("Please enter a value for the To Do item name");`
`168`	`182`	`return;`
`169`	`183`	`}`
`170`	`184`
`171`		`- //`
`172`		`- // Get an access token to call the To Do service.`
`173`		`- //`
`174`	`185`	`AuthenticationResult result = null;`
`175`	`186`	`try`
`176`	`187`	`{`
`177`	`188`	`result = await authContext.AcquireTokenAsync(new string[] { clientId }, null, clientId, redirectUri, new PlatformParameters(PromptBehavior.Never, null));`
`178`	`189`	`}`
`179`	`190`	`catch (AdalException ex)`
`180`	`191`	`{`
`181`		`- // There is no access token in the cache, so prompt the user to sign-in.`
`182`	`192`	`if (ex.ErrorCode == "user_interaction_required")`
`183`	`193`	`{`
`184`	`194`	`MessageBox.Show("Please sign in first");`
`185`	`195`	`SignInButton.Content = "Sign In";`
`186`	`196`	`}`
`187`	`197`	`else`
`188`	`198`	`{`
`189`		`- // An unexpected error occurred.`
`190`	`199`	`string message = ex.Message;`
`191`	`200`	`if (ex.InnerException != null)`
`192`	`201`	`{`
`@@ -199,17 +208,9 @@ private async void AddTodoItem(object sender, RoutedEventArgs e)`
`199`	`208`	`return;`
`200`	`209`	`}`
`201`	`210`
`202`		`- //`
`203`		`- // Call the To Do service.`
`204`		`- //`
`205`		`-`
`206`		`- // Once the token has been returned by ADAL, add it to the http authorization header, before making the call to access the To Do service.`
`207`	`211`	`httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.Token);`
`208`	`212`
`209`		`- // Forms encode Todo item, to POST to the todo list web api.`
`210`	`213`	`HttpContent content = new FormUrlEncodedContent(new[] { new KeyValuePair<string, string>("Title", TodoText.Text) });`
`211`		`-`
`212`		`- // Call the To Do list service.`
`213`	`214`	`HttpResponseMessage response = await httpClient.PostAsync(todoListBaseAddress + "/api/todolist", content);`
`214`	`215`
`215`	`216`	`if (response.IsSuccessStatusCode)`
`@@ -225,20 +226,25 @@ private async void AddTodoItem(object sender, RoutedEventArgs e)`
`225`	`226`
`226`	`227`	`private async void SignIn(object sender = null, RoutedEventArgs args = null)`
`227`	`228`	`{`
`228`		`- // If there is already a token in the cache, clear the cache and update the label on the button.`
	`229`	`+ // If the user clicked the 'clear cache' button,`
	`230`	`+ // clear the ADAL token cache and show the user as signed out.`
	`231`	`+ // It's also necessary to clear the cookies from the browser`
	`232`	`+ // control so the next user has a chance to sign in.`
	`233`	`+`
`229`	`234`	`if (SignInButton.Content.ToString() == "Clear Cache")`
`230`	`235`	`{`
`231`	`236`	`TodoList.ItemsSource = string.Empty;`
`232`	`237`	`authContext.TokenCache.Clear();`
`233`		`- // Also clear cookies from the browser control.`
`234`	`238`	`ClearCookies();`
`235`	`239`	`SignInButton.Content = "Sign In";`
`236`	`240`	`return;`
`237`	`241`	`}`
`238`	`242`
`239`		`- //`
`240`		`- // Get an access token to call the To Do list service.`
`241`		`- //`
	`243`	`+ // If the user clicked the 'Sign-In' button, force`
	`244`	`+ // ADAL to prompt the user for credentials by specifying`
	`245`	`+ // PromptBehavior.Always. ADAL will get a token for the`
	`246`	`+ // TodoListService and cache it for you.`
	`247`	`+`
`242`	`248`	`AuthenticationResult result = null;`
`243`	`249`	`try`
`244`	`250`	`{`
`@@ -248,6 +254,10 @@ private async void SignIn(object sender = null, RoutedEventArgs args = null)`
`248`	`254`	`}`
`249`	`255`	`catch (AdalException ex)`
`250`	`256`	`{`
	`257`	`+ // If ADAL cannot get a token, it will throw an exception.`
	`258`	`+ // If the user canceled the login, it will result in the`
	`259`	`+ // error code 'authentication_canceled'.`
	`260`	`+`
`251`	`261`	`if (ex.ErrorCode == "authentication_canceled")`
`252`	`262`	`{`
`253`	`263`	`MessageBox.Show("Sign in was canceled by the user");`