Merge pull request #24232 from dotnet/main

Merge to Live

Author: Rick-Anderson

aspnetcore/blazor/fundamentals/environments.md

@@ -91,25 +91,15 @@ Use the following guidance for hosted Blazor WebAssembly solutions hosted by Azu
 
 1. Confirm that the casing of environment segments in app settings filenames matches their environment name casing ***exactly***. For example, the matching app settings filename for the `Staging` environment is `appsettings.Staging.json`. If the filename is `appsettings.staging.json` (lowercase "`s`"), the file isn't located, and the settings in the file aren't used in the `Staging` environment.
 
-1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. In the following example for the `Staging` deployment slot, the app setting is set to `Staging`:
+1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. For an app named `BlazorAzureAppSample`, the staging App Service Slot is named `BlazorAzureAppSample/Staging`. For the `Staging` slot's configuration, create an app setting for `ASPNETCORE_ENVIRONMENT` with a value of `Staging`. **Deployment slot setting** is enabled for the setting.
 
-   ![Azure portal](environments/_static/image1.png)
+1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. For an app named `BlazorAzureAppSample`, the app is deployed to the `Staging` deployment slot.
 
-1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. In the following example, the app deploys from Visual Studio to the `Staging` deployment slot:
+When requested in a browser, the `BlazorAzureAppSample/Staging` app loads in the `Staging` environment at `https://blazorazureappsample-staging.azurewebsites.net`.
 
-   ![Visual Studio deployment configuration](environments/_static/image2.png)
+When the app is loaded in the browser, the response header collection for `blazor.boot.json` indicates that the `Blazor-Environment` header value is `Staging`.
 
-The app loads in the specified environment with the correct settings. In the following example, the app loads from the `Staging` deployment slot at the URL `https://bwhappsettingsasdf-staging.azurewebsites.net`:
-
-![Browser screenshot of the loaded app from the Staging deployment slot](environments/_static/image3.png)
-
-In the response header collection for `blazor.boot.json`, the `Blazor-Environment` header indicates the environment. In the following example, the `Blazor-Environment` header is inspected in the browser's developer tools and has a value of `Staging`:
-
-![Developer tools Network tab for the response of the blazor.boot.json request](environments/_static/image4.png)
-
-App settings from the files `appsettings.json` and `appsettings.{ENVIRONMENT}.json` (the `{ENVIRONMENT}` placeholder is the app's environment) are loaded by the app. In the following example, the app's settings files are loaded according to the browser's developer tools, which includes the settings file for the `Staging` environment (`appsettings.Staging.json`):
-
-![Developer tools Network tab indicating that both app settings files loaded (200 - OK status code)](environments/_static/image5.png)
+App settings from the `appsettings.{ENVIRONMENT}.json` file are loaded by the app, where the `{ENVIRONMENT}` placeholder is the app's environment. In the preceding example, settings from the `appsettings.Staging.json` file are loaded.
 
 ## Read the environment
 
@@ -240,25 +230,15 @@ Use the following guidance for hosted Blazor WebAssembly solutions hosted by Azu
 
 1. Confirm that the casing of environment segments in app settings filenames matches their environment name casing ***exactly***. For example, the matching app settings filename for the `Staging` environment is `appsettings.Staging.json`. If the filename is `appsettings.staging.json` (lowercase "`s`"), the file isn't located, and the settings in the file aren't used in the `Staging` environment.
 
-1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. In the following example for the `Staging` deployment slot, the app setting is set to `Staging`:
-
-   ![Azure portal](environments/_static/image1.png)
-
-1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. In the following example, the app deploys from Visual Studio to the `Staging` deployment slot:
-
-   ![Visual Studio deployment configuration](environments/_static/image2.png)
+1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. For an app named `BlazorAzureAppSample`, the staging App Service Slot is named `BlazorAzureAppSample/Staging`. For the `Staging` slot's configuration, create an app setting for `ASPNETCORE_ENVIRONMENT` with a value of `Staging`. **Deployment slot setting** is enabled for the setting.
 
-The app loads in the specified environment with the correct settings. In the following example, the app loads from the `Staging` deployment slot at the URL `https://bwhappsettingsasdf-staging.azurewebsites.net`:
+1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. For an app named `BlazorAzureAppSample`, the app is deployed to the `Staging` deployment slot.
 
-![Browser screenshot of the loaded app from the Staging deployment slot](environments/_static/image3.png)
+When requested in a browser, the `BlazorAzureAppSample/Staging` app loads in the `Staging` environment at `https://blazorazureappsample-staging.azurewebsites.net`.
 
-In the response header collection for `blazor.boot.json`, the `Blazor-Environment` header indicates the environment. In the following example, the `Blazor-Environment` header is inspected in the browser's developer tools and has a value of `Staging`:
+When the app is loaded in the browser, the response header collection for `blazor.boot.json` indicates that the `Blazor-Environment` header value is `Staging`.
 
-![Developer tools Network tab for the response of the blazor.boot.json request](environments/_static/image4.png)
-
-App settings from the files `appsettings.json` and `appsettings.{ENVIRONMENT}.json` (the `{ENVIRONMENT}` placeholder is the app's environment) are loaded by the app. In the following example, the app's settings files are loaded according to the browser's developer tools, which includes the settings file for the `Staging` environment (`appsettings.Staging.json`):
-
-![Developer tools Network tab indicating that both app settings files loaded (200 - OK status code)](environments/_static/image5.png)
+App settings from the `appsettings.{ENVIRONMENT}.json` file are loaded by the app, where the `{ENVIRONMENT}` placeholder is the app's environment. In the preceding example, settings from the `appsettings.Staging.json` file are loaded.
 
 ## Read the environment
 
@@ -364,25 +344,15 @@ Use the following guidance for hosted Blazor WebAssembly solutions hosted by Azu
 
 1. Confirm that the casing of environment segments in app settings filenames matches their environment name casing ***exactly***. For example, the matching app settings filename for the `Staging` environment is `appsettings.Staging.json`. If the filename is `appsettings.staging.json` (lowercase "`s`"), the file isn't located, and the settings in the file aren't used in the `Staging` environment.
 
-1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. In the following example for the `Staging` deployment slot, the app setting is set to `Staging`:
-
-   ![Azure portal](environments/_static/image1.png)
-
-1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. In the following example, the app deploys from Visual Studio to the `Staging` deployment slot:
-
-   ![Visual Studio deployment configuration](environments/_static/image2.png)
-
-The app loads in the specified environment with the correct settings. In the following example, the app loads from the `Staging` deployment slot at the URL `https://bwhappsettingsasdf-staging.azurewebsites.net`:
-
-![Browser screenshot of the loaded app from the Staging deployment slot](environments/_static/image3.png)
+1. In the Azure portal for the environment's deployment slot, set the environment with the `ASPNETCORE_ENVIRONMENT` app setting. For an app named `BlazorAzureAppSample`, the staging App Service Slot is named `BlazorAzureAppSample/Staging`. For the `Staging` slot's configuration, create an app setting for `ASPNETCORE_ENVIRONMENT` with a value of `Staging`. **Deployment slot setting** is enabled for the setting.
 
-In the response header collection for `blazor.boot.json`, the `Blazor-Environment` header indicates the environment. In the following example, the `Blazor-Environment` header is inspected in the browser's developer tools and has a value of `Staging`:
+1. For Visual Studio deployment, confirm that the app is deployed to the correct deployment slot. For an app named `BlazorAzureAppSample`, the app is deployed to the `Staging` deployment slot.
 
-![Developer tools Network tab for the response of the blazor.boot.json request](environments/_static/image4.png)
+When requested in a browser, the `BlazorAzureAppSample/Staging` app loads in the `Staging` environment at `https://blazorazureappsample-staging.azurewebsites.net`.
 
-App settings from the files `appsettings.json` and `appsettings.{ENVIRONMENT}.json` (the `{ENVIRONMENT}` placeholder is the app's environment) are loaded by the app. In the following example, the app's settings files are loaded according to the browser's developer tools, which includes the settings file for the `Staging` environment (`appsettings.Staging.json`):
+When the app is loaded in the browser, the response header collection for `blazor.boot.json` indicates that the `Blazor-Environment` header value is `Staging`.
 
-![Developer tools Network tab indicating that both app settings files loaded (200 - OK status code)](environments/_static/image5.png)
+App settings from the `appsettings.{ENVIRONMENT}.json` file are loaded by the app, where the `{ENVIRONMENT}` placeholder is the app's environment. In the preceding example, settings from the `appsettings.Staging.json` file are loaded.
 
 ## Read the environment
 

aspnetcore/blazor/fundamentals/environments/_static/image1.png

@@ -27,7 +27,7 @@ The following deployment strategies are supported:
 
 Blazor WebAssembly supports [ahead-of-time (AOT) compilation](/dotnet/standard/glossary#aot), where you can compile your .NET code directly into WebAssembly. AOT compilation results in runtime performance improvements at the expense of a larger app size.
 
-Without enabling AOT compilation, Blazor WebAssembly apps run on the browser using a .NET Intermediate Language (IL) interpreter implemented in WebAssembly. Because the .NET code is interpreted, apps typically run slower than they would on a server-side [.NET just-in-time (JIT) runtime](/dotnet/standard/glossary#jit). AOT compilation addresses this performance issue by compiling an app's .NET code directly into WebAssembly for native WebAssembly execution by the browser. The AOT performance improvement can yield dramatic improvements for apps that execute CPU intensive tasks. The drawback to using AOT compilation is that AOT-compiled apps are generally larger than their IL-interpreted counterparts, so they usually take longer to download to the client when first requested.
+Without enabling AOT compilation, Blazor WebAssembly apps run on the browser using a .NET Intermediate Language (IL) interpreter implemented in WebAssembly. Because the .NET code is interpreted, apps typically run slower than they would on a server-side [.NET just-in-time (JIT) runtime](/dotnet/standard/glossary#jit). AOT compilation addresses this performance issue by compiling an app's .NET code directly into WebAssembly for native WebAssembly execution by the browser. The AOT performance improvement can yield dramatic improvements for apps that execute CPU-intensive tasks. The drawback to using AOT compilation is that AOT-compiled apps are generally larger than their IL-interpreted counterparts, so they usually take longer to download to the client when first requested.
 
 For guidance on installing the .NET WebAssembly build tools, see <xref:blazor/tooling#net-webassembly-build-tools>.
 
@@ -53,7 +53,9 @@ The size of an AOT-compiled Blazor WebAssembly app is generally larger than the
 
 One of the largest parts of a Blazor WebAssembly app is the WebAssembly-based .NET runtime (`dotnet.wasm`) that the browser must download when the app is first accessed by a user's browser. Relinking the .NET WebAssembly runtime trims unused runtime code and thus improves download speed.
 
-Runtime relinking is performed automatically when you publish an app. The size reduction is particularly dramatic when disabling globalization. For more information, see <xref:blazor/globalization-localization>. For guidance on installing the .NET WebAssembly build tools, see <xref:blazor/tooling#net-webassembly-build-tools>.
+Runtime relinking requires installation of the .NET WebAssembly build tools. For more information, see <xref:blazor/tooling#net-webassembly-build-tools>.
+
+With the .NET WebAssembly build tools installed, runtime relinking is performed automatically when an app is published. The size reduction is particularly dramatic when disabling globalization. For more information, see <xref:blazor/globalization-localization#invariant-globalization>.
 
 ## Customize how boot resources are loaded
 

aspnetcore/blazor/fundamentals/environments/_static/image2.png

@@ -713,8 +713,16 @@ function jsInteropCall() {
 }
 ```
 
+## Ahead-of-time (AOT) compilation
+
+[Ahead-of-time (AOT) compilation](/dotnet/standard/glossary#aot) compiles a Blazor app's .NET code directly into native WebAssembly for direct execution by the browser. AOT-compiled apps result in larger apps that take longer to download, but AOT-compiled apps usually provide better runtime performance, especially for apps that execute CPU-intensive tasks. For more information, see <xref:blazor/host-and-deploy/webassembly#ahead-of-time-aot-compilation>.
+
 ## Minimize app download size
 
+### Runtime relinking
+
+For information on how runtime relinking minimizes an app's download size, see <xref:blazor/host-and-deploy/webassembly#runtime-relinking>.
+
 ### Use `System.Text.Json`
 
 Blazor's JS interop implementation relies on <xref:System.Text.Json>, which is a high-performance JSON serialization library with low memory allocation. Using <xref:System.Text.Json> shouldn't result in additional app payload size over adding one or more alternate JSON libraries.

aspnetcore/blazor/fundamentals/environments/_static/image3.png

@@ -10,9 +10,8 @@ uid: migration/31-to-50
 ---
 # Migrate from ASP.NET Core 3.1 to 5.0
 
-By [Scott Addie](https://github.com/scottaddie)
 
-This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core 5.0.
+This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core 5.0. For instructions on how to migrate from ASP.NET Core 3.1 to ASP.NET Core 6.0, see <xref:migration/31-to-60>.
 
 ## Prerequisites
 

aspnetcore/blazor/fundamentals/environments/_static/image4.png

@@ -10,7 +10,7 @@ uid: migration/50-to-60
 ---
 # Migrate from ASP.NET Core 5.0 to 6.0
 
-This article explains how to update an existing ASP.NET Core 5.0 project to ASP.NET Core 6.0.
+This article explains how to update an existing ASP.NET Core 5.0 project to ASP.NET Core 6.0. For instructions on how to migrate from ASP.NET Core 3.1 to ASP.NET Core 6.0, see <xref:migration/31-to-60>.
 
 ## Prerequisites