Add troubleshooting guidance (#31619)

aspnetcore/blazor/security/includes/troubleshoot.md

@@ -36,7 +36,7 @@ To enable debug or trace logging for Blazor WebAssembly authentication, see <xre
   
   *The preceding forums are not owned or controlled by Microsoft.*
   
-  For non-security, non-sensitive, and non-confidential reproducible framework bug reports, [open an issue with the ASP.NET Core product unit](https://github.com/dotnet/aspnetcore/issues). Don't open an issue with the product unit until you've thoroughly investigated the cause of a problem and can't resolve it on your own and with the help of the community on a public support forum. The product unit isn't able to troubleshoot individual apps that are broken due to simple misconfiguration or use cases involving third-party services. If a report is sensitive or confidential in nature or describes a potential security flaw in the product that attackers may exploit, see [Reporting security issues and bugs (dotnet/aspnetcore GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/CONTRIBUTING.md#reporting-security-issues-and-bugs).
+  For non-security, non-sensitive, and non-confidential reproducible framework bug reports, [open an issue with the ASP.NET Core product unit](https://github.com/dotnet/aspnetcore/issues). Don't open an issue with the product unit until you've thoroughly investigated the cause of a problem and can't resolve it on your own and with the help of the community on a public support forum. The product unit isn't able to troubleshoot individual apps that are broken due to simple misconfiguration or use cases involving third-party services. If a report is sensitive or confidential in nature or describes a potential security flaw in the product that attackers may exploit, see [Reporting security issues and bugs (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/CONTRIBUTING.md#reporting-security-issues-and-bugs).
 
 * Unauthorized client for ME-ID
 

aspnetcore/blazor/security/webassembly/standalone-with-identity.md

@@ -214,6 +214,126 @@ For security reasons, role claims aren't sent back from the `manage/info` endpoi
 
 To create role claims on your own, make a separate request in the `GetAuthenticationStateAsync` method of the `CookieAuthenticationStateProvider` after the user is authenticated to a custom web API in the `Backend` project that provides user roles from the user data store. We plan to provide guidance on this subject. The work is tracked by [Role claims guidance in standalone WASM w/Identity article (dotnet/AspNetCore.Docs #31045)](https://github.com/dotnet/AspNetCore.Docs/issues/31045).
 
+## Troubleshoot
+
+### Logging
+
+To enable debug or trace logging for Blazor WebAssembly authentication, see <xref:blazor/fundamentals/logging>.
+
+### Common errors
+
+Check each project's configuration. Confirm that the URLs are correct:
+
+* `Backend` project
+  * `appsettings.json`
+    * `BackendUrl`
+    * `FrontendUrl`
+  * `Backend.http`: `Backend_HostAddress`
+* `BlazorWasmAuth` project: `wwwroot/appsettings.json`
+  * `BackendUrl`
+  * `FrontendUrl`
+
+If the configuration appears correct:
+
+* Analyze application logs.
+* Examine the network traffic between the `BlazorWasmAuth` app and `Backend` app with the browser's developer tools. Often, an exact error message or a message with a clue to what's causing the problem is returned to the client by the backend app after making a request. Developer tools guidance is found in the following articles:
+
+* [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/network) (Google documentation)
+* [Microsoft Edge](/microsoft-edge/devtools-guide-chromium/network/)
+* [Mozilla Firefox](https://developer.mozilla.org/docs/Tools/Network_Monitor) (Mozilla documentation)
+
+The documentation team responds to document feedback and bugs in articles. Open an issue using the **Open a documentation issue** link at the bottom of the article. The team isn't able to provide product support. Several public support forums are available to assist with troubleshooting an app. We recommend the following:
+
+* [Stack Overflow (tag: `blazor`)](https://stackoverflow.com/questions/tagged/blazor)
+* [ASP.NET Core Slack Team](https://join.slack.com/t/aspnetcore/shared_invite/zt-1mv5487zb-EOZxJ1iqb0A0ajowEbxByQ)
+* [Blazor Gitter](https://gitter.im/aspnet/Blazor)
+
+*The preceding forums are not owned or controlled by Microsoft.*
+
+For non-security, non-sensitive, and non-confidential reproducible framework bug reports, [open an issue with the ASP.NET Core product unit](https://github.com/dotnet/aspnetcore/issues). Don't open an issue with the product unit until you've thoroughly investigated the cause of a problem and can't resolve it on your own and with the help of the community on a public support forum. The product unit isn't able to troubleshoot individual apps that are broken due to simple misconfiguration or use cases involving third-party services. If a report is sensitive or confidential in nature or describes a potential security flaw in the product that attackers may exploit, see [Reporting security issues and bugs (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/CONTRIBUTING.md#reporting-security-issues-and-bugs).
+
+### Cookies and site data
+
+Cookies and site data can persist across app updates and interfere with testing and troubleshooting. Clear the following when making app code changes, user account changes, or app configuration changes:
+
+* User sign-in cookies
+* App cookies
+* Cached and stored site data
+
+One approach to prevent lingering cookies and site data from interfering with testing and troubleshooting is to:
+
+* Configure a browser
+  * Use a browser for testing that you can configure to delete all cookie and site data each time the browser is closed.
+  * Make sure that the browser is closed manually or by the IDE for any change to the app, test user, or provider configuration.
+* Use a custom command to open a browser in InPrivate or Incognito mode in Visual Studio:
+  * Open **Browse With** dialog box from Visual Studio's **Run** button.
+  * Select the **Add** button.
+  * Provide the path to your browser in the **Program** field. The following executable paths are typical installation locations for Windows 10. If your browser is installed in a different location or you aren't using Windows 10, provide the path to the browser's executable.
+    * Microsoft Edge: `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`
+    * Google Chrome: `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`
+    * Mozilla Firefox: `C:\Program Files\Mozilla Firefox\firefox.exe`
+  * In the **Arguments** field, provide the command-line option that the browser uses to open in InPrivate or Incognito mode. Some browsers require the URL of the app.
+    * Microsoft Edge: Use `-inprivate`.
+    * Google Chrome: Use `--incognito --new-window {URL}`, where the placeholder `{URL}` is the URL to open (for example, `https://localhost:5001`).
+    * Mozilla Firefox: Use `-private -url {URL}`, where the placeholder `{URL}` is the URL to open (for example, `https://localhost:5001`).
+  * Provide a name in the **Friendly name** field. For example, `Firefox Auth Testing`.
+  * Select the **OK** button.
+  * To avoid having to select the browser profile for each iteration of testing with an app, set the profile as the default with the **Set as Default** button.
+  * Make sure that the browser is closed by the IDE for any change to the app, test user, or provider configuration.
+
+### App upgrades
+
+A functioning app may fail immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. In some cases, incoherent packages may break an app when performing major upgrades. Most of these issues can be fixed by following these instructions:
+
+1. Clear the local system's NuGet package caches by executing [`dotnet nuget locals all --clear`](/dotnet/core/tools/dotnet-nuget-locals) from a command shell.
+1. Delete the project's `bin` and `obj` folders.
+1. Restore and rebuild the project.
+1. Delete all of the files in the deployment folder on the server prior to redeploying the app.
+
+> [!NOTE]
+> Use of package versions incompatible with the app's target framework isn't supported. For information on a package, use the [NuGet Gallery](https://www.nuget.org) or [FuGet Package Explorer](https://www.fuget.org).
+
+### Inspect the user's claims
+
+To troubleshoot problems with user claims, the following `UserClaims` component can be used directly in apps or serve as the basis for further customization.
+
+`UserClaims.razor`:
+
+```razor
+@page "/user-claims"
+@using System.Security.Claims
+@attribute [Authorize]
+
+<PageTitle>User Claims</PageTitle>
+
+<h1>User Claims</h1>
+
+**Name**: @AuthenticatedUser?.Identity?.Name
+
+<h2>Claims</h2>
+
+@foreach (var claim in AuthenticatedUser?.Claims ?? Array.Empty<Claim>())
+{
+    <p class="claim">@(claim.Type): @claim.Value</p>
+}
+
+@code {
+    [CascadingParameter]
+    private Task<AuthenticationState>? AuthenticationState { get; set; }
+
+    public ClaimsPrincipal? AuthenticatedUser { get; set; }
+
+    protected override async Task OnInitializedAsync()
+    {
+        if (AuthenticationState is not null)
+        {
+            var state = await AuthenticationState;
+            AuthenticatedUser = state.User;
+        }
+    }
+}
+```
+
 ## Additional resources
 
 <!-- UPDATE 9.0 Drop the What's New blog post -->