dotnet · guardrex · Nov 20, 2023 · Nov 20, 2023
@@ -0,0 +1,73 @@
+---
+title: Avoid HTTP caching issues when upgrading ASP.NET Core Blazor apps
+author: guardrex
+description: Learn how to avoid HTTP caching issues when upgrading Blazor apps.
+monikerRange: '>= aspnetcore-3.1'
+ms.author: riande
+ms.custom: mvc
+ms.date: 11/20/2023
+uid: blazor/http-caching-issues
+---
+# Avoid HTTP caching issues when upgrading ASP.NET Core Blazor apps
+
+[!INCLUDE[](~/includes/not-latest-version.md)]
+
+When Blazor apps are incorrectly upgraded or configured, it can result in non-seamless upgrades for existing users. This article discusses some of the common HTTP caching issues that can occur when upgrading Blazor apps across major versions. It also provides some recommended actions to ensure a smooth transition for your users.
+
+While future Blazor releases might provide better solutions for dealing with HTTP caching issues, it's ultimately up to the app to correctly configure caching. Proper caching configuration ensures that the app's users always have the most up-to-date version of the app, improving their experience and reducing the likelihood of encountering errors.
+
+Common problems that negatively impact the user upgrade experience include:
+
+* **Incorrect handling of project and package updates**: This happens if you don't update all of the app's deployed projects to use the same major framework version or if you use packages from a previous version when a newer version is available as part of the major upgrade.
+* **Incorrect configuration of caching headers**: HTTP caching headers control how, where, and for how long the app's responses are cached. If headers aren't configured correctly, users might receive stale content.
+* **Incorrect configuration of other layers**: Content Delivery Networks (CDNs) and other layers of the deployed app can cause issues if incorrectly configured. For example, CDNs are designed to cache and deliver content to improve performance and reduce latency. If a CDN is incorrectly serving cached versions of assets, it can lead to stale content delivery to the user.
+
+## Detect and diagnose upgrade issues
+
+Upgrade issues typically appear as a failure to start the app in the browser. Normally, a warning indicates the presence of a stale asset or an asset that's missing or inconsistent with the app.
+
+* First, check if the app loads successfully within a clean browser instance. Use a private browser mode to load the app, such as Microsoft Edge InPrivate mode or Google Chrome Incognito mode. If the app fails to load, it likely means that one or more packages or the framework wasn't correctly updated.
+* If the app loads correctly in a clean browser instance, then it's likely that the app is being served from a stale cache. In most cases, a hard browser refresh with <kbd>Ctrl</kbd>+<kbd>F5</kbd> flushes the cache, which permits the app to load and run with the latest assets.
+* If the app continues to fail, then it's likely that a stale CDN cache is serving the app. Try to flushing the DNS cache via whatever mechanism your CDN provider offers.
+
+## Recommended actions before an upgrade
+
+The prior process for serving the app might make the update process more challenging. For example, avoiding or incorrectly using caching headers in the past can lead to current caching problems for users. You can take the actions in the following sections to mitigate the issue and improve the upgrade process for users.
+
+### Align framework packages with the framework version
+
+Ensure that framework packages line up with the framework version. Using packages from a previous version when a newer version is available can lead to compatibility issues. It's also important to ensure that all of the app's deployed projects use the same major framework version. This consistency helps to avoid unexpected behavior and errors.
+
+### Verify the presence of correct caching headers
+
+The correct caching headers should be present on responses to resource requests. This includes `ETag`, `Cache-Control`, and other caching headers. The configuration of these headers is dependent on the hosting service or hosting server platform. They are particularly important for assets such as the Blazor script (`blazor.webassembly.js`) and anything the script downloads.
+
+Incorrect HTTP caching headers may also impact service workers. Service workers rely on caching headers to manage cached resources effectively. Therefore, incorrect or missing headers can disrupt the service worker's functionality.
+
+### Use `Clear-Site-Data` to delete state in the browser
+
+Consider using the [`Clear-Site-Data` header](https://developer.mozilla.org/docs/Web/HTTP/Headers/Clear-Site-Data) to delete state in the browser.
+
+Usually the source of cache state problems is limited to the HTTP browser cache, so use of the `cache` directive should be sufficient. This action can help to ensure that the browser fetches the latest resources from the server, rather than serving stale content from the cache.
+
+You can optionally include the `storage` directive to clear local storage caches at the same time that you're clearing the HTTP browser cache. However, apps that use client storage might experience a loss of important information if the `storage` directive is used.
+
+### Append a query string to the Blazor script tag
+
+If none of the previous recommended actions are effective, possible to use for your deployment, or apply to your app, consider temporarily appending a query string to the Blazor script's `<script>` tag source. This action should be enough in most situations to force the browser to bypass the local HTTP cache and download a new version of the app. There's no need to read or use the query string in the app.
+
+In the following example, the query string `temporaryQueryString=1` is temporarily applied to the `<script>` tag's relative external source URI:
+
+```html
+<script src="_framework/blazor.webassembly.js?temporaryQueryString=1"></script>
+```
+
+After all of the app's users have reloaded the app, the query string can be removed.
+
+Alternatively, you can apply a persistent query string with relevant versioning. The following example assumes that the version of the app matches the .NET release version (`8` for .NET 8):
+
+```html
+<script src="_framework/blazor.webassembly.js?version=8"></script>
+```
+
+For the location of the Blazor script `<script>` tag, see <xref:blazor/project-structure#location-of-the-blazor-script>.
@@ -154,7 +154,7 @@ In the ASP.NET Core project's `Program` file:
   app.UseAntiforgery();
   ```
 
-* Add `MapRazorComponents` to the app's request processing pipeline with the `App` component (`App.razor`) specified as the default root component (the first component loaded). Place the following code before the the line that calls `app.Run`:
+* Add `MapRazorComponents` to the app's request processing pipeline with the `App` component (`App.razor`) specified as the default root component (the first component loaded). Place the following code before the line that calls `app.Run`:
 
   ```csharp
   app.MapRazorComponents<App>();

@@ -392,7 +392,7 @@ Register a root component as a custom element:
   ```
 
   > [!NOTE]
-  > The preceding code example requires a namespace for the app's components (for example, `using BlazorSample.Components.Pages;`) in the the `Program` file.
+  > The preceding code example requires a namespace for the app's components (for example, `using BlazorSample.Components.Pages;`) in the `Program` file.
 
 * In a Blazor WebAssembly app, call `RegisterAsCustomElement` on <xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.RootComponents> in the `Program` file:
 
@@ -401,7 +401,7 @@ Register a root component as a custom element:
   ```
 
   > [!NOTE]
-  > The preceding code example requires a namespace for the app's components (for example, `using BlazorSample.Components.Pages;`) in the the `Program` file.
+  > The preceding code example requires a namespace for the app's components (for example, `using BlazorSample.Components.Pages;`) in the `Program` file.
 
 Include the following `<script>` tag in the app's HTML ***before*** the Blazor script tag:
 

@@ -96,7 +96,7 @@ To use Entity Framework (EF) Core as the data source:
   builder.Services.AddQuickGridEntityFrameworkAdapter();
   ```
 
-QuickGrid supports passing custom attributes to the the rendered table element:
+QuickGrid supports passing custom attributes to the rendered table element:
 
 ```razor
 <QuickGrid Items="..." custom-attribute="somevalue" class="custom-class">

@@ -1,7 +1,7 @@
 ---
 title: ASP.NET Core Blazor sections
 author: guardrex
-description: Learn how to to control the content in a Razor component from a child Razor component.
+description: Learn how to control the content in a Razor component from a child Razor component.
 monikerRange: '>= aspnetcore-8.0'
 ms.author: riande
 ms.custom: mvc
@@ -18,7 +18,7 @@ uid: blazor/components/sections
 
 To control the content in a Razor component from a child Razor component, Blazor supports *sections* using the following built-in components:
 
-* `SectionOutlet`: Renders content provided by `SectionContent` components with matching `SectionName` or `SectionId` arguments. Two or more `SectionOutlet` components can't have the the same `SectionName` or `SectionId`.
+* `SectionOutlet`: Renders content provided by `SectionContent` components with matching `SectionName` or `SectionId` arguments. Two or more `SectionOutlet` components can't have the same `SectionName` or `SectionId`.
 
 * `SectionContent`: Provides content as a <xref:Microsoft.AspNetCore.Components.RenderFragment> to `SectionOutlet` components with a matching `SectionName` or `SectionId`. If several `SectionContent` components have the same `SectionName` or `SectionId`, the matching `SectionOutlet` component renders the content of the last rendered `SectionContent`.
 

@@ -167,7 +167,7 @@ The repo contains two types of samples:
 
 * Snippet sample apps provide the code examples that appear in articles. These apps compile but aren't necessarily runnable apps. These apps are useful for merely obtaining example code that appears in articles.
 * Samples apps to accompany Blazor articles compile and run for the following scenarios:
-  * Blazor Web App with with EF Core
+  * Blazor Web App with EF Core
   * Blazor Web App with SignalR
   * Blazor WebAssembly scopes-enabled logging
 

@@ -733,13 +733,13 @@ The following `CultureSelector` component shows how to call the `Set` method of
 
 :::moniker range=">= aspnetcore-8.0"
 
-Add the `CultureSelector` component to the the `MainLayout` component. Place the following markup inside the closing `</main>` tag in the `Components/Layout/MainLayout.razor` file:
+Add the `CultureSelector` component to the `MainLayout` component. Place the following markup inside the closing `</main>` tag in the `Components/Layout/MainLayout.razor` file:
 
 :::moniker-end
 
 :::moniker range=">= aspnetcore-8.0"
 
-Add the `CultureSelector` component to the the `MainLayout` component. Place the following markup inside the closing `</main>` tag in the `Shared/MainLayout.razor` file:
+Add the `CultureSelector` component to the `MainLayout` component. Place the following markup inside the closing `</main>` tag in the `Shared/MainLayout.razor` file:
 
 :::moniker-end
 

@@ -540,13 +540,13 @@ The Blazor script is served from an embedded resource in the ASP.NET Core shared
 
 In a Blazor Web App, the Blazor script is located in the `Components/App.razor` file:
 
-```
+```html
 <script src="_framework/blazor.web.js"></script>
 ```
 
 In a Blazor Server app, the Blazor script is located in the `Pages/_Host.cshtml` file:
 
-```
+```html
 <script src="_framework/blazor.server.js"></script>
 ```
 
@@ -556,7 +556,7 @@ In a Blazor Server app, the Blazor script is located in the `Pages/_Host.cshtml`
 
 In a Blazor Server app, the Blazor script is located in the `Pages/_Host.cshtml` file:
 
-```
+```html
 <script src="_framework/blazor.server.js"></script>
 ```
 
@@ -566,7 +566,7 @@ In a Blazor Server app, the Blazor script is located in the `Pages/_Host.cshtml`
 
 In a Blazor Server app, the Blazor script is located in the `Pages/_Layout.cshtml` file:
 
-```
+```html
 <script src="_framework/blazor.server.js"></script>
 ```
 
@@ -576,15 +576,15 @@ In a Blazor Server app, the Blazor script is located in the `Pages/_Layout.cshtm
 
 In a Blazor Server app, the Blazor script is located in the `Pages/_Host.cshtml` file:
 
-```
+```html
 <script src="_framework/blazor.server.js"></script>
 ```
 
 :::moniker-end
 
 In a Blazor WebAssembly app, the Blazor script content is located in the `wwwroot/index.html` file:
 
-```
+```html
 <script src="_framework/blazor.webassembly.js"></script>
 ```
 

@@ -67,14 +67,14 @@ One approach to prevent lingering cookies and site data from interfering with te
 * 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 incognito or private mode in Visual Studio:
+* 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 incognito or private mode. Some browsers require the URL of the app.
+  * 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`).

@@ -95,7 +95,7 @@ At the server level, the framework provides limits on request/response parameter
 
 In addition, there are limits defined for the form, such as the maximum form key size and value size and the maximum number of entries.
 
-In general, the app must evaluate when there's a chance that a request triggers an asymmetric amount of work by the server. Examples of this include when the user sends a a request parameterized by N and the server performs an operation in response that is N times as expensive, where N is a parameter that a user controls and can grow indefinitely. Normally, the app must either impose a limit on the maximum N that it's willing to process or ensure that any operation is either less, equal, or more expensive than the request by a constant factor.
+In general, the app must evaluate when there's a chance that a request triggers an asymmetric amount of work by the server. Examples of this include when the user sends a request parameterized by N and the server performs an operation in response that is N times as expensive, where N is a parameter that a user controls and can grow indefinitely. Normally, the app must either impose a limit on the maximum N that it's willing to process or ensure that any operation is either less, equal, or more expensive than the request by a constant factor.
 
 This aspect has more to do with the difference in growth between the work the client performs and the work the server performs than with a specific 1→N comparison. For example, a client might submit a work item (inserting elements into a list) that takes N units of time to perform, but the server needs N^2^ to process (because it might be doing something very naive). It's the difference between N and N^2^ that matters.