Updated instructions

Author: JimDaly

powerapps-docs/developer/common-data-service/media/blazor-webassembly-walkthrough-advanced-settings.png

@@ -58,24 +58,11 @@ Let’s make sure that your environment is configured properly, and you understa
 
 ### Get the CDS Web API URI
 
-> [!NOTE]
-> These instructions were valid when this content was written. The steps may change in the future.
-
-1. When you have an environment with the database you want to connect to, select the **Settings** (Gear) icon and choose **Advanced settings**.
-
-    :::image type="content" source="media/blazor-webassembly-walkthrough-advanced-settings.png" alt-text="Navigating to the Advanced settings are from the maker portal":::
-
-1. The Dynamics 365 settings app will open. Select **Settings** > **Customizations**.
+You will need the Instance Web API Service Root URL. This is found on the Developer Resources page of your CDS environment.
 
-    :::image type="content" source="media/blazor-webassembly-walkthrough-settings-customizations.png" alt-text="Navigating to the customizations area in the Dynamics 365 settings area.":::
+Follow the instructions found in [View or download developer resources](view-download-developer-resources.md) to copy the Url. 
 
-1. Then select **Developer Resources**.
-
-    :::image type="content" source="media/blazor-webassembly-walkthrough-developer-resources.png" alt-text="Navigating to the developer resources page.":::
-
-1. Then copy the **Instance Web API Service Root URL**. You will need this in the [Step 3: Apply code changes](#step-3-apply-code-changes).
-
-    :::image type="content" source="media/blazor-webassembly-walkthrough-instance-web-api.png" alt-text="The developer resources page showing the Instance Web API URL":::
+It will look something like this: `https://yourorgname.api.crm.dynamics.com/api/data/v9.1/`
 
 ### Navigate to the Azure Active Directory portal
 
@@ -101,9 +88,14 @@ The [Secure an ASP.NET Core Blazor WebAssembly standalone app with Azure Active
 These steps will describe how to create an app registration in AAD and run a .NET Core CLI command to generate the scaffold for the basic app with support for AAD authentication.
 
 > [!NOTE]
-> At this time, you must use the .NET Core CLI command to generate the app. There is no template for this app when creating a project using Visual Studio.
+> At this time, you must use the .NET Core CLI command to generate the app. There is no template for this specific type of app when creating a project using Visual Studio.
+
+Go to [Secure an ASP.NET Core Blazor WebAssembly standalone app with Azure Active Directory](/aspnet/core/security/blazor/webassembly/standalone-with-azure-active-directory) and follow the instructions there to generate the basic app template. 
 
-The rest of the content in this section provides supplemental information to assist in completing the steps described in the [Secure an ASP.NET Core Blazor WebAssembly standalone app with Azure Active Directory](/aspnet/core/security/blazor/webassembly/standalone-with-azure-active-directory) topic.
+> [!NOTE]
+> The rest of the content in this section provides supplemental information to assist in completing the steps described in the [Secure an ASP.NET Core Blazor WebAssembly standalone app with Azure Active Directory](/aspnet/core/security/blazor/webassembly/standalone-with-azure-active-directory) topic. 
+> 
+> You may want to review this as you complete those steps, but it is not required. When you are done, come back here and start with [Step 3 Grant API permissions](#step-3-grant-api-permissions).
 
 Registering the application involves completing a form. The default value for the Redirect URI includes a placeholder for the port value. You must replace the placeholder with a number value to complete the registration, for example, just add `1111` for now. You can provide the randomly generated port value later after you open the project in Visual Studio. See [Update callback URL](#update-callback-url).
 
@@ -158,7 +150,7 @@ Now that the Redirect URI has been updated; you should be able to press F5 in Vi
 
 At this point, all the capabilities of the app work whether you log-in or not. Only members of the AAD tenant can log in.
 
-### Grant API permissions
+## Step 3: Grant API permissions
 
 To connect to CDS, you must configure permissions for the app to connect.
 
@@ -183,12 +175,24 @@ To connect to CDS, you must configure permissions for the app to connect.
 
     :::image type="content" source="media/blazor-webassembly-walkthrough-grant-admin-consent.png" alt-text="The button showing the optional button to grant admin consent for the registered application.":::
 
-## Step 3: Apply code changes
+## Step 4: Apply code changes
 
 Apply changes to the following files to enable displaying CDS data in the application.
 
 ### \wwwroot\appsettings.json
 
+You will find that this file already has configuration information generated by the template with information about the application registered in Azure AD. It will look like this:
+
+```json
+{
+  "AzureAd": {
+    "Authority": "https://login.microsoftonline.com/22222222-2222-2222-2222-222222222222",
+    "ClientId": "11111111-1111-1111-1111-111111111111",
+    "ValidateAuthority": true
+  }
+}
+```
+
 Update the file to include a new `CDSWebAPI` section that includes the root of the **Instance Web API Service Root URL** you copied in the [Get the CDS Web API URI](#get-the-cds-web-api-uri) step.
 
 > [!NOTE]
@@ -211,41 +215,39 @@ Update the file to include a new `CDSWebAPI` section that includes the root of t
 
 ### Program.cs
 
-1. Comment out or remove the following line:
+1. Install the `Microsoft.Extensions.Http` NuGet package.
+    1. In the solution explorer, right-click the project and select **Manage NuGet Packages...**.
+    1. Select **Browse** and search for `Microsoft.Extensions.Http`.
+    1. Install the latest version of the package.
 
-    ```csharp
-    builder.Services.AddTransient(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
-    ```
-    > [!NOTE]
-    > This line enables an HttpClient to access JSON data within the web site for the Weather Forecast functionality. Changes in this walkthrough will break this functionality
+    :::image type="content" source="media/blazor-webassembly-walkthrough-install-microsoft.extensions.http-nuget-package.png" alt-text="Install the required NuGet package":::
 
-1. Add the following code to replace the line commented out in step 1. This code will read configuration information from appsettings.json and enable an HttpClient to use for CDS Data.
+1. Add the following code below the line that starts with `builder.Services.AddTransient(sp => new HttpClient...`
 
     ```csharp
+    // Get configuration data about the Web API set in wwwroot/appsettings.json
     var CDSWebApiConfig = builder.Configuration.GetSection("CDSWebAPI");
     var resourceUrl = CDSWebApiConfig.GetSection("ResourceUrl").Value;
     var version = CDSWebApiConfig.GetSection("Version").Value;
     var timeoutSeconds = int.Parse(CDSWebApiConfig.GetSection("TimeoutSeconds").Value);
 
-    builder.Services.AddTransient(sp => new HttpClient
+    // Create an named definition of an HttpClient that can be created in a component page
+    // using IHttpClientFactory.CreateClient("CDSClient")
+    builder.Services.AddHttpClient("CDSClient", client =>
     {
-        BaseAddress = new Uri($"{resourceUrl}/api/data/{version}/"),
-        Timeout = TimeSpan.FromSeconds(timeoutSeconds)
-
-    }
-    );
+        // See https://docs.microsoft.com/powerapps/developer/common-data-service/webapi/compose-http-requests-handle-errors
+        client.BaseAddress = new Uri($"{resourceUrl}/api/data/{version}/");
+        client.Timeout = TimeSpan.FromSeconds(timeoutSeconds);
+        client.DefaultRequestHeaders.Add("OData-Version", "4.0");
+        client.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
+    });
     ```
 
-1. Add the the second line within the section where MSAL authentication options are configured. This will include access to CDS data to the scope of accesstoken.
+1. Add the following code below the line that starts with `builder.Configuration.Bind("AzureAd" ...`
 
     ```csharp
-    builder.Services.AddMsalAuthentication(options =>
-    {
-        builder.Configuration.Bind("AzureAd", options.ProviderOptions.Authentication);
-
-        options.ProviderOptions.DefaultAccessTokenScopes.Add($"{resourceUrl}/user_impersonation");
-
-    });
+    // Add access to CDS to the scope of the access token when the user signs in
+    options.ProviderOptions.DefaultAccessTokenScopes.Add($"{resourceUrl}/user_impersonation");
     ```
 
 ### Add \Pages\FetchAccounts.razor
@@ -260,42 +262,18 @@ This is a new page that will display the account information.
     @using Microsoft.AspNetCore.Components.WebAssembly.Authentication
     @using System.Net.Http.Headers
     @using System.Net.Http.Json
+    @using Microsoft.Extensions.Logging;
+    @using System.Text.Json.Serialization;
     @inject IAccessTokenProvider TokenProvider
-    @inject HttpClient Http
+    @inject IHttpClientFactory ClientFactory
+    @inject ILogger<FetchAccounts> logger;
 
     <AuthorizeView>
+        @*Only show the list if the user is signed in and authorized*@
         <Authorized>
             <h3>Fetch Accounts</h3>
 
-            @if (accounts == null)
-            {
-                <p><em>Loading...</em></p>
-                <p>@message</p>
-                @if (error != null)
-                {
-                    <h3>Error:</h3>
-                    <table>
-                        <tr>
-                            <td>Status Code: </td>
-                            <td>@error.statuscode</td>
-                        </tr>
-                        <tr>
-                            <td>Reason: </td>
-                            <td>@error.reason</td>
-                        </tr>
-                        <tr>
-                            <td>Code: </td>
-                            <td>@error.error.code</td>
-                        </tr>
-                        <tr>
-                            <td>Message: </td>
-                            <td>@error.error.message</td>
-                        </tr>
-                    </table>
-
-                }
-            }
-            else
+            @if (accounts != null)
             {
                 <table class="table">
                     <thead>
@@ -344,7 +322,10 @@ This is a new page that will display the account information.
                         }
                     </tbody>
                 </table>
-
+            }
+            else
+            {
+                <p><em>@message</em></p>
             }
         </Authorized>
         <NotAuthorized>
@@ -356,60 +337,82 @@ This is a new page that will display the account information.
 
     @code {
 
+        //The collection of Account records to display
         private AccountCollection accounts;
 
-        private string message;
+        //An informational message
+        private string message = "Loading...";
 
+        //Contains data about an error returned from the Web API
         private Error error;
 
+        // Method invoked when the component is ready to start, having received its initial parameters from its parent in the render tree.
+        // Override this method if you will perform an asynchronous operation and want the component to refresh when that operation is completed.
         protected override async Task OnInitializedAsync()
         {
-
+            // Tries to get an access token for the current user with the default set of permissions.
             var tokenResult = await TokenProvider.RequestAccessToken();
 
+            // If the token request was successful
             if (tokenResult.TryGetToken(out var token))
             {
+                //Creates an HttpClient based on the named definition found in Program.Main
+                var client = ClientFactory.CreateClient("CDSClient");
+
+                //Prepare the request to get the data
                 var request = new HttpRequestMessage()
                 {
                     Method = HttpMethod.Get,
-                    RequestUri = new Uri($"{Http.BaseAddress}accounts?" +
-                    $"$select=name,telephone1,address1_city&" +
-                    $"$expand=primarycontactid($select=fullname,emailaddress1)")
+                    RequestUri = new Uri($"{client.BaseAddress}accounts?" +
+                    "$select=name,telephone1,address1_city&" +
+                    "$expand=primarycontactid($select=fullname,emailaddress1)")
                 };
+                //Add the access token
                 request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Value);
-                request.Headers.Add("OData-MaxVersion", "4.0");
-                request.Headers.Add("OData-Version", "4.0");
+                //Specify a JSON result is expected
                 request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+                //Limit the number of results to 10
                 request.Headers.Add("Prefer", "odata.maxpagesize=10");
 
-                var response = await Http.SendAsync(request);
+                //Send the request
+                var response = await client.SendAsync(request);
 
                 if (response.IsSuccessStatusCode)
                 {
-
+                    //Parse the JSON returned into a strongly typed AccountCollection
                     accounts = await response.Content.ReadFromJsonAsync<AccountCollection>();
                 }
                 else
                 {
-
+                    //Parse the JSON returned into a strongly typed Error
                     error = await response.Content.ReadFromJsonAsync<Error>();
                     error.statuscode = (int)response.StatusCode;
                     error.reason = response.ReasonPhrase;
+                    //Display a message to the user
+                    message = "An error occurred.";
+                    //Log the details so they can be seen in the browser console
+                    logger.LogError($"{error.detail.message}");
+
                 }
 
             }
             else
             {
+                // Notify user that the token request was not successful
                 message = "There was a problem authenticating.";
             }
 
         }
 
+
+        // The result will be a JSON object with an array of entities set to the value property
         public class AccountCollection
         {
             public Account[] value { get; set; }
         }
 
+        //Just the properties of the Account EntityType used for this sample
+        // See https://docs.microsoft.com/dynamics365/customer-engagement/web-api/account
         public class Account
         {
 
@@ -425,6 +428,8 @@ This is a new page that will display the account information.
 
         }
 
+        //Just the properties of the Contact EntityType that are expanded from the Account entity
+        // See https://docs.microsoft.com/dynamics365/customer-engagement/web-api/contact
         public class Contact
         {
 
@@ -433,14 +438,18 @@ This is a new page that will display the account information.
             public string emailaddress1 { get; set; }
         }
 
+        // Contains the error data returned by the Web API and the HttpMessageResponse
         public class Error
         {
-            public ErrorDetail error { get; set; }
+            [JsonPropertyName("error")]
+            public ErrorDetail detail { get; set; }
             public int statuscode { get; set; }
             public string reason { get; set; }
 
         }
 
+        //Contains data from the Web API
+        //See https://docs.microsoft.com/powerapps/developer/common-data-service/webapi/compose-http-requests-handle-errors#parse-errors-from-the-response
         public class ErrorDetail
         {
             public string code { get; set; }
@@ -454,25 +463,14 @@ This code does the following:
 
 1. Ensures that only authenticated users can view the page with data.
 1. Defines a table to display Account data after it is retrieved.
-1. Displays error information if there is an error retrieving the Account data.
 1. Requests an accesstoken and then uses that token with an HttpRequestMessage to retrieve data from CDS.
 1. Defines classes to enable strongly typed data when the JSON returned from the service is deserialized.
 
 ### \Shared\NavMenu.razor
 
-Edit this file to remove the navigation option for **Fetch Data** and replace it with one to **Fetch Accounts** data.
-
-Replace this:
-
-```html
-<li class="nav-item px-3">
-    <NavLink class="nav-link" href="fetchdata">
-        <span class="oi oi-list-rich" aria-hidden="true"></span> Fetch data
-    </NavLink>
-</li>
-```
+Edit this file to add the fetchaccounts razor component page.
 
-With this:
+Add this node where ever you like within the `<ul class="nav flex-column">` element.
 
 ```html
 <li class="nav-item px-3">
@@ -482,7 +480,7 @@ With this:
 </li>
 ```
 
-## Step 4: Verify Behavior
+## Step 5: Verify it works
 
 In Visual Studio, press F5 to launch the app with the code changes.