From 5a8837c848508015c2a61328c283a789505f0350 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 12 Oct 2023 13:26:54 -0400 Subject: [PATCH 01/20] Blazor migration guidance 8.0 --- aspnetcore/migration/70-80.md | 200 +++++++++++++++++++++++++++------- 1 file changed, 160 insertions(+), 40 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index f2573c5c3698..df851ee5609b 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -73,64 +73,184 @@ In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/ ## Blazor -We hope to have the Blazor section of this article updated soon. +The following migration scenarios are covered: -### Adopt .NET 8 features +* [Update a Blazor Server app](#update-a-blazor-server-app) +* [Add Auto component rendering to a Blazor Server app](#add-auto-component-rendering-to-a-blazor-server-app) +* [Upgrade a hosted Blazor WebAssembly app](#upgrade-a-hosted-blazor-webassembly-app) -After following the guidance earlier in this article to update an app to 8.0, adopt specific features by following the links in . +For scenarios not covered or to upgrade to a Blazor Web App, we recommend: - +Blazor Server apps are supported in .NET 8. Make the following changes to update the app's code, which permits adopting new .NET 8 features: - + > [!NOTE] + > In the following example, the app's namespace is `Net8BlazorServer`. + + * Add a `using` statement for the app's namespace: + + ```diff + + using Net8BlazorServer; + ``` + + * Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddServerComponents`: + + ```diff + - builder.Services.AddServerSideBlazor(); + + builder.Services.AddRazorComponents() + + .AddServerComponents(); + ``` + + * Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddServerRenderMode`. + + ```diff + - app.MapBlazorHub(); + + app.MapRazorComponents() + + .AddServerRenderMode(); + ``` + + * Remove the endpoint mapping that falls back to the `_Host` page: + + ```diff + - app.MapFallbackToPage("/_Host"); + ``` + +1. If the Blazor Server app wasn't prerendering content, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: + + ```diff + - @rendermode="RenderMode.InteractiveServer" + + @rendermode="new InteractiveServerRenderMode(prerender: false)" + ``` + + For more information, see . + +### Add Auto component rendering to a Blazor Server app + + + +### Upgrade a hosted Blazor WebAssembly app + + + +### Adopt .NET 8 features + +After following the guidance earlier in this article to update an app to 8.0, adopt specific features by following the links in . + +To adopt all of the [new 8.0 features for Blazor apps](xref:aspnetcore-8#blazor) at one time, we recommend the following process: + +* Create a new 8.0 Blazor project from one of the Blazor project templates. For more information, see . +* Move the app's components and code to the new 8.0 app, making modifications to adopt 8.0 features as desired. ## Update Docker images From 24f06f6e04520cb027c92a5854dbef093340360e Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 12 Oct 2023 13:42:12 -0400 Subject: [PATCH 02/20] Updates --- aspnetcore/migration/70-80.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index df851ee5609b..9c3774c71b19 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -204,20 +204,20 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update + using Net8BlazorServer; ``` - * Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddServerComponents`: + * Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddInteractiveServerComponents`: ```diff - builder.Services.AddServerSideBlazor(); + builder.Services.AddRazorComponents() - + .AddServerComponents(); + + .AddInteractiveServerComponents(); ``` - * Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddServerRenderMode`. + * Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddInteractiveServerRenderMode`. ```diff - app.MapBlazorHub(); + app.MapRazorComponents() - + .AddServerRenderMode(); + + .AddInteractiveServerRenderMode(); ``` * Remove the endpoint mapping that falls back to the `_Host` page: From 0eaa0d9dbf5a0d36fde71563c2510025228b60ab Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 12 Oct 2023 13:47:38 -0400 Subject: [PATCH 03/20] Updates --- aspnetcore/migration/70-80.md | 71 +++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 28 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 9c3774c71b19..25657c9a7dfe 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -94,6 +94,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - net7.0 + net8.0 ``` + 1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the app. 1. Add an entry to the `_Imports.razor` file to make shorthand render modes available to the app: @@ -116,7 +117,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update The following represents the changes to make to the `App` component. - Replace the following lines at the top of the file: + Remove the following lines at the top of the file: ```diff - @page "/" @@ -125,7 +126,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers ``` - Use: + Replace them with the following: ```razor @inject IHostEnvironment Env @@ -138,31 +139,31 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update + ``` - Replace the Component Tag Helper for the `HeadOutlet` component: + Remove the Component Tag Helper for the `HeadOutlet` component: ```diff - ``` - Use: + Replace it with the following: ```razor ``` - Replace the Component Tag Helper for the `App` component: + Remove the Component Tag Helper for the `App` component: ```diff - ``` - Use: + Replace it with the following: ```razor ``` - Replace the Environment Tag Helpers for error UI: + Remove the Environment Tag Helpers for error UI: ```diff - @@ -173,7 +174,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - ``` - Use: + Replace them with the following: ```razor @if (Env.IsDevelopment()) @@ -198,33 +199,47 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update > [!NOTE] > In the following example, the app's namespace is `Net8BlazorServer`. - * Add a `using` statement for the app's namespace: + Add a `using` statement for the app's namespace: - ```diff - + using Net8BlazorServer; - ``` + ```csharp + using Net8BlazorServer; + ``` - * Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddInteractiveServerComponents`: + Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddInteractiveServerComponents`. + + Remove the following line: + + ```diff + - builder.Services.AddServerSideBlazor(); + ``` - ```diff - - builder.Services.AddServerSideBlazor(); - + builder.Services.AddRazorComponents() - + .AddInteractiveServerComponents(); - ``` + Replace it with the following: + + ```csharp + builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); + ``` - * Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddInteractiveServerRenderMode`. + Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddInteractiveServerRenderMode`. + + Remove the following line: - ```diff - - app.MapBlazorHub(); - + app.MapRazorComponents() - + .AddInteractiveServerRenderMode(); - ``` + ```diff + - app.MapBlazorHub(); + ``` + + Replace it with the following: - * Remove the endpoint mapping that falls back to the `_Host` page: + ```csharp + app.MapRazorComponents() + .AddInteractiveServerRenderMode(); + ``` + + Remove the endpoint mapping that falls back to the `_Host` page: - ```diff - - app.MapFallbackToPage("/_Host"); - ``` + ```diff + - app.MapFallbackToPage("/_Host"); + ``` 1. If the Blazor Server app wasn't prerendering content, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: From 90e544892682a92365f9ffc30b7c28f10006ea89 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 12 Oct 2023 13:55:43 -0400 Subject: [PATCH 04/20] Updates --- aspnetcore/migration/70-80.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 25657c9a7dfe..fccb804d2ab9 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -95,7 +95,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update + net8.0 ``` -1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the app. +1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the app. Leave the empty `App.razor` file in the app. 1. Add an entry to the `_Imports.razor` file to make shorthand render modes available to the app: @@ -103,20 +103,11 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update @using static Microsoft.AspNetCore.Components.Web.RenderMode ``` -1. In the `App` component (`App.razor`): - - * Move content from `Pages/_Host.cshtml` to `App.razor`. - * Update the Razor directives at the top of the file, including obtaining an instance of `IHostEnvironment`. - * Update the `` tag. - * Replace tag helpers with Blazor equivalents. - * Update script to `blazor.web.js`. - * Delete the `Pages/_Host.cshtml` file. +1. Move the content in the `_Host` page (`Pages/_Host.cshtml`) to the empty `App.razor` file and delete the `Pages/_Host.cshtml` file. Proceed to make the following changes to the `App` component. > [!NOTE] > In the following example, the app's namespace is `Net8BlazorServer`. - The following represents the changes to make to the `App` component. - Remove the following lines at the top of the file: ```diff From 98a8df33a9b7c5ade4d2c4717d3066dd711e2809 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 13 Oct 2023 09:04:28 -0400 Subject: [PATCH 05/20] Updates --- aspnetcore/migration/70-80.md | 145 ++++++++++++++++++++++++++++------ 1 file changed, 120 insertions(+), 25 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index fccb804d2ab9..b3e3172dbcd9 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -77,23 +77,26 @@ The following migration scenarios are covered: * [Update a Blazor Server app](#update-a-blazor-server-app) * [Add Auto component rendering to a Blazor Server app](#add-auto-component-rendering-to-a-blazor-server-app) -* [Upgrade a hosted Blazor WebAssembly app](#upgrade-a-hosted-blazor-webassembly-app) +* [Update a Blazor WebAssembly app](#update-a-blazor-webassembly-app) +* [Update a hosted Blazor WebAssembly app](#update-a-hosted-blazor-webassembly-app) -For scenarios not covered or to upgrade to a Blazor Web App, we recommend: +For scenarios not covered or to convert the app into a Blazor Web App, we recommend the following process: -* Creating a new app from the Blazor Web App project template. For more information, see . -* Move the your app's components and code to the new Blazor Web App app, making modifications to adopt 8.0 features as desired. For more information, see . +* Create a new app from the Blazor Web App project template. For more information, see . +* Move the your app's components and code to the new Blazor Web App app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). ### Update a Blazor Server app -Blazor Server apps are supported in .NET 8. Make the following changes to update the app's code, which permits adopting new .NET 8 features: +Blazor Server apps are supported in .NET 8. Use the following guidance to update a Blazor Server app to .NET 8, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. -1. Update the project file to target `net8.0` and package references to the latest .NET 8 versions: +> [!NOTE] +> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes and recommended best practices, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Adopt all .NET 8 project template changes](#adopt-all-net-8-project-template-changes) section. - ```diff - - net7.0 - + net8.0 - ``` +1. Follow the guidance in the first three sections of this article: + + * [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) + * [Update the target framework](#update-the-target-framework) + * [Update package references](#update-package-references) 1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the app. Leave the empty `App.razor` file in the app. @@ -108,7 +111,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update > [!NOTE] > In the following example, the app's namespace is `Net8BlazorServer`. - Remove the following lines at the top of the file: + Remove the following lines from the top of the file: ```diff - @page "/" @@ -117,13 +120,13 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers ``` - Replace them with the following: + Replace the preceding lines with the following: ```razor @inject IHostEnvironment Env ``` - Remove the tilde (~) from the value of `href` for the `` tag: + Remove the tilde (`~`) from the value of `href` for the `` tag: ```diff - @@ -136,7 +139,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - ``` - Replace it with the following: + Replace the tag helper with the following line: ```razor @@ -148,7 +151,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - ``` - Replace it with the following: + Replace the tag helper with the following line: ```razor @@ -165,7 +168,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - ``` - Replace them with the following: + Replace the tag helpers with the following lines: ```razor @if (Env.IsDevelopment()) @@ -204,7 +207,7 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - builder.Services.AddServerSideBlazor(); ``` - Replace it with the following: + Replace the line with the following lines: ```csharp builder.Services.AddRazorComponents() @@ -219,20 +222,20 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update - app.MapBlazorHub(); ``` - Replace it with the following: + Replace the line with the following lines: ```csharp app.MapRazorComponents() .AddInteractiveServerRenderMode(); ``` - Remove the endpoint mapping that falls back to the `_Host` page: + Remove the following line: ```diff - app.MapFallbackToPage("/_Host"); ``` -1. If the Blazor Server app wasn't prerendering content, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: +1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: ```diff - @rendermode="RenderMode.InteractiveServer" @@ -241,22 +244,114 @@ Blazor Server apps are supported in .NET 8. Make the following changes to update For more information, see . +1. Razor components in the app should adopt either static or interactive server rendering. Render modes can be applied to the app's components either at the level of a component definition (`.razor` file) or where a component instance is used in Razor markup. For guidance on applying render modes, see . + ### Add Auto component rendering to a Blazor Server app +This section covers adding WebAssembly-based components to a Blazor Server app after upgrading to .NET 8. + +Use the following process: + +1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app). + + + +1. Create a donor Blazor Web App, which will provide assets to the Blazor Server app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. + + For the app's name, use the same name as the Blazor Server app, which results in matching name and namespaces. + + * Interactivity type: Select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. + * Interactivity location: Use either **Global** or **Per page/component** for Visual Studio or don't pass the `-ai|--all-interactive` option if using the .NET CLI. + +1. From the donor Blazor Web App, drag the entire `.Client` project into the solution folder of the Blazor Server app. + +1. Add the `.Client` project to the solution: + + In Visual Studio, right-click the solution in **Solution Explorer** and select **Add** > **Existing Project**. Navigate to the `.Client` folder and select the project file (`.csproj`). + + If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the Blazor Server's solution. + +1. If you want to make all of the solution's developer-created Razor components adopt the Auto render mode, configure global interactive Auto render mode on the `HeadOutlet` and `Routes` components in the Blazor Server project's `App` component (`Components/App.razor`): + + ```razor + + + ... + + + ``` + + If you prefer to set the render modes of component definitions and instances on each component, don't set a global render mode on the `HeadOutlet` and `Routes` components: + + ```razor + + + ... + + + ``` + +1. Add the `.Client` project's namespace to the Blazor Server project by adding a `using` statement to the Blazor Server project's `_Imports.razor` file. In the following example, the project's namespace is `Net8BlazorServer`: + + ```razor + @using Net8BlazorServer.Client + ``` + +1. If you made all of the solution's developer-created Razor components adopt the Auto render mode in the `App` component earlier, move all of the Blazor Server's developer-created components in the `Components/Pages` pages folder to the `.Client` project's `Pages` folder. Create a `Shared` folder in the `.Client` project for shared components. It isn't necessary to set a render mode in each component definition or instance. + + If you left it up to each component to set its render mode, apply the render modes according to the guidance in the article. + +### Update a Blazor WebAssembly app + +Follow the guidance in the first three sections of this article: + +* [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) +* [Update the target framework](#update-the-target-framework) +* [Update package references](#update-package-references) + +Adopt [8.0 features](xref:aspnetcore-8#blazor). + +### Update a hosted Blazor WebAssembly app + +************************************************************* +**** This section is a WIP: Will pick back up on Monday! **** +************************************************************* + +To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: + +1. Follow the guidance in the first three sections of this article: + + * [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) + * [Update the target framework](#update-the-target-framework) + * [Update package references](#update-package-references) + +1. Move content from `Client/wwwroot/index.html` to `Host.razor` (commit): + + * Update script to `blazor.web.js`. + * Replace `` tag with `HeadOutlet` component. + +1. Update `Client/Program.cs` (commit): Remove `builder.RootComponents.Add<HeadOutlet>("head::after")`. + +1. Update `Server/Program.cs` (commit): + * Add `builder.Services.AddRazorComponents().AddInteractiveWebAssemblyComponents()`. + * Remove `app.UseBlazorFrameworkFiles()`. + * Replace `MapFallbackToFile("index.html")` with `app.MapRazorComponents<Host>().AddInteractiveWebAssemblyRenderMode()`. -### Upgrade a hosted Blazor WebAssembly app +To enable prerendering: +* Update all components to support prerendering from the server (commit). +* In `Host.razor` replace the `id=app` tag with `<App @rendermode="RenderMode.WebAssembly" />` (commit). -### Adopt .NET 8 features -After following the guidance earlier in this article to update an app to 8.0, adopt specific features by following the links in <xref:aspnetcore-8#blazor>. +### Adopt all .NET 8 project template changes -To adopt all of the [new 8.0 features for Blazor apps](xref:aspnetcore-8#blazor) at one time, we recommend the following process: +To adopt all of the changes that were made to the project templates for this release, we recommend the following process: * Create a new 8.0 Blazor project from one of the Blazor project templates. For more information, see <xref:blazor/tooling>. -* Move the app's components and code to the new 8.0 app, making modifications to adopt 8.0 features as desired. +* Move the app's components and code to the new app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). ## Update Docker images From c43846647987694314319630eb4172c9638cf4f6 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Mon, 16 Oct 2023 09:07:09 -0400 Subject: [PATCH 06/20] Updates --- aspnetcore/migration/70-80.md | 168 ++++++++++++++++++++++++++-------- 1 file changed, 132 insertions(+), 36 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index b3e3172dbcd9..e2264aaa9419 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -76,7 +76,8 @@ In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/ The following migration scenarios are covered: * [Update a Blazor Server app](#update-a-blazor-server-app) -* [Add Auto component rendering to a Blazor Server app](#add-auto-component-rendering-to-a-blazor-server-app) +* [Add interactive WebAssembly rendering to a Blazor Server app](#add-interactive-webassembly-rendering-to-a-blazor-server-app) +* [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) * [Update a Blazor WebAssembly app](#update-a-blazor-webassembly-app) * [Update a hosted Blazor WebAssembly app](#update-a-hosted-blazor-webassembly-app) @@ -89,8 +90,8 @@ For scenarios not covered or to convert the app into a Blazor Web App, we recomm Blazor Server apps are supported in .NET 8. Use the following guidance to update a Blazor Server app to .NET 8, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. -> [!NOTE] -> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes and recommended best practices, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Adopt all .NET 8 project template changes](#adopt-all-net-8-project-template-changes) section. +> [!IMPORTANT] +> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes and recommended best practices for Blazor, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. 1. Follow the guidance in the first three sections of this article: @@ -98,7 +99,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) -1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the app. Leave the empty `App.razor` file in the app. +1. Move the contents of the `App` component (`App.razor`) to a new `Routes` component file (`Routes.razor`) added to the project's root folder. Leave the empty `App.razor` file in the app in the project's root folder. 1. Add an entry to the `_Imports.razor` file to make shorthand render modes available to the app: @@ -106,7 +107,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update @using static Microsoft.AspNetCore.Components.Web.RenderMode ``` -1. Move the content in the `_Host` page (`Pages/_Host.cshtml`) to the empty `App.razor` file and delete the `Pages/_Host.cshtml` file. Proceed to make the following changes to the `App` component. +1. Move the content in the `_Host` page (`Pages/_Host.cshtml`) to the empty `App.razor` file. Proceed to make the following changes to the `App` component. > [!NOTE] > In the following example, the app's namespace is `Net8BlazorServer`. @@ -157,6 +158,9 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update <Routes @rendermode="RenderMode.InteractiveServer" /> ``` + > [!NOTE] + > The preceding configuration assumes that the app's components adopt interactive server rendering. For more information, including how to adopt static server rendering, see <xref:blazor/components/render-modes>. + Remove the Environment Tag Helpers for error UI: ```diff @@ -188,6 +192,8 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update + <script src="_framework/blazor.web.js"></script> ``` +1. Delete the `Pages/_Host.cshtml` file. + 1. Update `Program.cs`: > [!NOTE] @@ -235,6 +241,12 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update - app.MapFallbackToPage("/_Host"); ``` + Add [Antiforgery Middleware](xref:blazor/security/index#antiforgery-support) to the request processing pipeline immediately after the call to `app.UseRouting`. If there are calls to `app.UseRouting` and `app.UseEndpoints`, the call to `app.UseAntiforgery` must go between them. Calls to `app.UseAntiforgery` must be placed after calls to `app.UseAuthentication` and `app.UseAuthorization`. + + ```csharp + app.UseAntiforgery(); + ``` + 1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: ```diff @@ -244,27 +256,41 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update For more information, see <xref:blazor/components/render-modes?view=aspnetcore-8.0&preserve-view=true#prerendering>. -1. Razor components in the app should adopt either static or interactive server rendering. Render modes can be applied to the app's components either at the level of a component definition (`.razor` file) or where a component instance is used in Razor markup. For guidance on applying render modes, see <xref:blazor/components/render-modes>. +### Add interactive WebAssembly rendering to a Blazor Server app -### Add Auto component rendering to a Blazor Server app - -This section covers adding WebAssembly-based components to a Blazor Server app after upgrading to .NET 8. +This section covers adding interactive WebAssembly rendering to a Blazor Server app after updating the Blazor Server app to .NET 8. Use the following process: -1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app). +1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app) section. -<!-- UPDATE 8.0 RTM - The name of 'Interactivity type' will change to + > [!NOTE] + > For the examples in this section, the Blazor Server app's name and namespace uses is carried over from the *Update a Blazor Server app* section (`Net8BlazorServer`). + +1. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the Blazor Server app. + + [!INCLUDE[](~/includes/package-reference.md)] + +<!-- UPDATE 8.0 'Interactivity type' will change to 'Interactive render mode' --> 1. Create a donor Blazor Web App, which will provide assets to the Blazor Server app. Follow the guidance in the <xref:blazor/tooling> article, selecting support for the following template features when generating the Blazor Web App. - For the app's name, use the same name as the Blazor Server app, which results in matching name and namespaces. + For the app's name, use the same name as the Blazor Server app, which results in matching app name markup in components and matching namespaces in code. + + * For **Interactivity type**, select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. + * Ignore the **Interactivity location** setting. The `App` component of the donor project isn't used, and configuring the render mode globally or on a per-component basis is covered by a manual change made to the app in a later step. - * Interactivity type: Select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. - * Interactivity location: Use either **Global** or **Per page/component** for Visual Studio or don't pass the `-ai|--all-interactive` option if using the .NET CLI. +1. From the donor Blazor Web App, copy the entire `.Client` project into the solution folder of the Blazor Server app. -1. From the donor Blazor Web App, drag the entire `.Client` project into the solution folder of the Blazor Server app. + > [!IMPORTANT] + > Don't copy the `.Client` folder into the Blazor Server project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the Blazor Server project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder for the Blazor Server app. The final project folder structure should have the following layout: + > + > * `Net8BlazorServerSolution` (top-level solution folder) + > * `Net8BlazorServer` (original Blazor Server project) + > * `Net8BlazorServer.Client` (`.Client` project folder from the donor Blazor Web App) + > + > For the Blazor Server solution file, you can leave it in the Blazor Server project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. 1. Add the `.Client` project to the solution: @@ -272,17 +298,50 @@ Use the following process: If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the Blazor Server's solution. -1. If you want to make all of the solution's developer-created Razor components adopt the Auto render mode, configure global interactive Auto render mode on the `HeadOutlet` and `Routes` components in the Blazor Server project's `App` component (`Components/App.razor`): +1. Add a project reference to the Blazor Server project for the client project: - ```razor - <HeadOutlet @rendermode="RenderMode.InteractiveAuto" /> + In Visual Studio, right-click the Blazor Server project and select **Add** > **Project Reference**. Select the `.Client` project and select **OK**. - ... + If using the .NET CLI, from the Blazor Server project's folder, use the following command: + + ```dotnetcli + dotnet add reference ../Net8BlazorServer.Client/Net8BlazorServer.Client.csproj + ``` - <Routes @rendermode="RenderMode.InteractiveAuto" /> + > [!NOTE] + > The preceding command assumes the following: + > + > * The project file name is `Net8BlazorServer.Client.csproj`. + > * The `.Client` project is in a `Net8BlazorServer.Client` folder inside of a solution folder. The `.Client` folder is side-by-side with the Blazor Server project's folder. + > + > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). + +1. Add the interactive WebAssembly component services (`AddInteractiveWebAssemblyComponents`) to the project's `Program` file where Razor component services are added with `AddRazorComponents`: + + ```csharp + builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); ``` - If you prefer to set the render modes of component definitions and instances on each component, don't set a global render mode on the `HeadOutlet` and `Routes` components: + Add the interactive WebAssembly render mode (`AddInteractiveWebAssemblyRenderMode`) and additional assemblies for the `.Client` project where Razor components are mapped with `MapRazorComponents`: + + ```csharp + app.MapRazorComponents<App>() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode() + .AddAdditionalAssemblies(typeof(Net8BlazorServer.Client._Imports).Assembly); + ``` + +1. Add the `.Client` project's namespace to the Blazor Server project by adding a `using` statement to the Blazor Server project's `_Imports.razor` file. In the following example, the project's namespace is `Net8BlazorServer.Client`: + + ```razor + @using Net8BlazorServer.Client + ``` + +1. Configure the root `HeadOutlet` and `Routes` components to set the render mode on a per-component definition or instance. + + In the `App` component (`App.razor`): ```razor <HeadOutlet /> @@ -292,15 +351,60 @@ Use the following process: <Routes /> ``` -1. Add the `.Client` project's namespace to the Blazor Server project by adding a `using` statement to the Blazor Server project's `_Imports.razor` file. In the following example, the project's namespace is `Net8BlazorServer`: +1. Because the donor Blazor Web App supplied a `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project) to the solution, delete the Blazor Server app's `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer` project). + + Notice that the component supplied by the Blazor Web App adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directives: + + ```razor + @attribute [RenderModeInteractiveAuto] + ``` + + <!-- UPDATE 8.0 To adopt simplified naming at RTM --> ```razor - @using Net8BlazorServer.Client + @rendermode RenderMode.InteractiveAuto + ``` + + In the Blazor Server project (`Pages` folder of the `Net8BlazorServer` project), you can adopt the interactive server render mode for any components that should remain server-rendered: + + ```razor + @attribute [RenderModeInteractiveServer] + ``` + + <!-- UPDATE 8.0 To adopt simplified naming at RTM --> + + ```razor + @rendermode RenderMode.InteractiveServer + ``` + + If any of your server-side components should also disable prerendering, see <xref:blazor/components/render-modes#prerendering>. + + For any components that should strictly adopt the interactive WebAssembly render mode in the `.Client` project (`Pages` folder of the `Net8BlazorServer.Client` project), explicitly configure the render mode: + + ```razor + @attribute [RenderModeInteractiveWebAssembly] ``` -1. If you made all of the solution's developer-created Razor components adopt the Auto render mode in the `App` component earlier, move all of the Blazor Server's developer-created components in the `Components/Pages` pages folder to the `.Client` project's `Pages` folder. Create a `Shared` folder in the `.Client` project for shared components. It isn't necessary to set a render mode in each component definition or instance. + <!-- UPDATE 8.0 To adopt simplified naming at RTM --> - If you left it up to each component to set its render mode, apply the render modes according to the guidance in the <xref:blazor/components/render-modes> article. + ```razor + @rendermode RenderMode.InteractiveWebAssembly + ``` + + For additional information on applying render modes to components, see <xref:blazor/components/render-modes>. + +1. Run the solution from the ***Blazor Server*** project: + + For Visual Studio, confirm that the Blazor Server project is selected in **Solution Explorer** when running the app. + + If using the .NET CLI, run the project from the Blazor Server project's folder. + +### Convert a Blazor Server app into a Blazor Web App + +To adopt all of the changes that were made to the project templates for this release, we recommend the following process: + +* Create a new project from the Blazor Web App project template. For more information, see <xref:blazor/tooling>. +* Move the app's components and code to the new app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). ### Update a Blazor WebAssembly app @@ -314,9 +418,9 @@ Adopt [8.0 features](xref:aspnetcore-8#blazor). ### Update a hosted Blazor WebAssembly app -************************************************************* -**** This section is a WIP: Will pick back up on Monday! **** -************************************************************* +************************************************************** +**** This section is a WIP: Will pick back up on Tuesday! **** +************************************************************** To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: @@ -345,14 +449,6 @@ To enable prerendering: * In `Host.razor` replace the `id=app` tag with `<App @rendermode="RenderMode.WebAssembly" />` (commit). - -### Adopt all .NET 8 project template changes - -To adopt all of the changes that were made to the project templates for this release, we recommend the following process: - -* Create a new 8.0 Blazor project from one of the Blazor project templates. For more information, see <xref:blazor/tooling>. -* Move the app's components and code to the new app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). - ## Update Docker images For apps using Docker, update your *Dockerfile* `FROM` statements and scripts. Use a base image that includes the ASP.NET Core 8.0 runtime. Consider the following `docker pull` command difference between ASP.NET Core 7.0 and 8.0: From 206a2e3ba50518ca5ea4c28a93f648683c61c670 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Tue, 17 Oct 2023 09:56:59 -0400 Subject: [PATCH 07/20] Updates --- aspnetcore/migration/70-80.md | 205 ++++++++++++++++++++++++++++------ 1 file changed, 172 insertions(+), 33 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index e2264aaa9419..4653ff396643 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -73,10 +73,12 @@ In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/ ## Blazor +<!-- UPDATE 8.0 Add API cross-links after RTM --> + The following migration scenarios are covered: * [Update a Blazor Server app](#update-a-blazor-server-app) -* [Add interactive WebAssembly rendering to a Blazor Server app](#add-interactive-webassembly-rendering-to-a-blazor-server-app) +* [Add interactive WebAssembly components to a Blazor Server app](#add-interactive-webassembly-components-to-a-blazor-server-app) * [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) * [Update a Blazor WebAssembly app](#update-a-blazor-webassembly-app) * [Update a hosted Blazor WebAssembly app](#update-a-hosted-blazor-webassembly-app) @@ -85,13 +87,14 @@ For scenarios not covered or to convert the app into a Blazor Web App, we recomm * Create a new app from the Blazor Web App project template. For more information, see <xref:blazor/tooling>. * Move the your app's components and code to the new Blazor Web App app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). +* Update the layout and styles of the Blazor Web App. ### Update a Blazor Server app Blazor Server apps are supported in .NET 8. Use the following guidance to update a Blazor Server app to .NET 8, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. > [!IMPORTANT] -> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes and recommended best practices for Blazor, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. +> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. 1. Follow the guidance in the first three sections of this article: @@ -110,7 +113,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update 1. Move the content in the `_Host` page (`Pages/_Host.cshtml`) to the empty `App.razor` file. Proceed to make the following changes to the `App` component. > [!NOTE] - > In the following example, the app's namespace is `Net8BlazorServer`. + > In the following example, the project's namespace is `Net8BlazorServer`. Adjust the namespace to match your project. Remove the following lines from the top of the file: @@ -197,9 +200,9 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update 1. Update `Program.cs`: > [!NOTE] - > In the following example, the app's namespace is `Net8BlazorServer`. + > In the following example, the project's namespace is `Net8BlazorServer`. Adjust the namespace to match your project. - Add a `using` statement for the app's namespace: + Add a `using` statement for the project's namespace: ```csharp using Net8BlazorServer; @@ -256,16 +259,16 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update For more information, see <xref:blazor/components/render-modes?view=aspnetcore-8.0&preserve-view=true#prerendering>. -### Add interactive WebAssembly rendering to a Blazor Server app +### Add interactive WebAssembly components to a Blazor Server app -This section covers adding interactive WebAssembly rendering to a Blazor Server app after updating the Blazor Server app to .NET 8. +This section covers adding interactive WebAssembly components to a Blazor Server app after updating the Blazor Server app to .NET 8. Use the following process: 1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app) section. > [!NOTE] - > For the examples in this section, the Blazor Server app's name and namespace uses is carried over from the *Update a Blazor Server app* section (`Net8BlazorServer`). + > For the examples in this section, the Blazor Server app's name and namespace is carried over from the preceding *Update a Blazor Server app* section. The example name/namespace is `Net8BlazorServer`. 1. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the Blazor Server app. @@ -316,6 +319,37 @@ Use the following process: > > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). +1. In the Blazor Server app's `Routes` component (`Routes.razor`): + + Add the client project's assembly to the router in the first line of the file: + + ```diff + - <Router AppAssembly="@typeof(App).Assembly"> + + <Router AppAssembly="@typeof(App).Assembly" + + AdditionalAssemblies="new[] { typeof(Client._Imports).Assembly }"> + ``` + + Remove the `<NotFound>` tags and content, as this markup is no longer used: + + ```diff + - <NotFound> + - <PageTitle>Not found</PageTitle> + - <LayoutView Layout="@typeof(MainLayout)"> + - <p role="alert">Sorry, there's nothing at this address.</p> + - </LayoutView> + - </NotFound> + ``` + + If you want to replace the loss of `<NotFound>` functionality, implement [Status Code Pages](xref:fundamentals/error-handling#usestatuscodepages) in the Blazor Server app (`Net8BlazorServer` project), which includes options for a default response string, a custom response string, or a redirect to an error handling endpoint. + + For a default response string, place Status Code Pages Middleware immediately after the line that adds HTTPS Redirection Middleware (`app.UseHttpsRedirection`) in the `Program` file of the Blazor Server app: + + ```csharp + app.UseStatusCodePages(); + ``` + + For more information, see <xref:fundamentals/error-handling#usestatuscodepages>. + 1. Add the interactive WebAssembly component services (`AddInteractiveWebAssemblyComponents`) to the project's `Program` file where Razor component services are added with `AddRazorComponents`: ```csharp @@ -333,12 +367,6 @@ Use the following process: .AddAdditionalAssemblies(typeof(Net8BlazorServer.Client._Imports).Assembly); ``` -1. Add the `.Client` project's namespace to the Blazor Server project by adding a `using` statement to the Blazor Server project's `_Imports.razor` file. In the following example, the project's namespace is `Net8BlazorServer.Client`: - - ```razor - @using Net8BlazorServer.Client - ``` - 1. Configure the root `HeadOutlet` and `Routes` components to set the render mode on a per-component definition or instance. In the `App` component (`App.razor`): @@ -351,9 +379,11 @@ Use the following process: <Routes /> ``` -1. Because the donor Blazor Web App supplied a `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project) to the solution, delete the Blazor Server app's `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer` project). +1. Configure the render mode and location of each Razor component in the Blazor Server app. + + The donor Blazor Web App supplies a `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project) to the solution, which can be used for development testing. - Notice that the component supplied by the Blazor Web App adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directives: + Notice that the `Counter` component in the `.Client` project adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directive: ```razor @attribute [RenderModeInteractiveAuto] @@ -364,10 +394,23 @@ Use the following process: ```razor @rendermode RenderMode.InteractiveAuto ``` + + For any of your Blazor Server app components that should also adopt the Auto render mode, move them to the `.Client` project's `Pages` folder (or `Shared` folder if a non-routable, shared component) and provide them with ***either*** of the preceding directives, noting that a shared component typically inherits its render mode and doesn't require a directive. + + Such components render on the server first, then render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the Auto render mode. + + To further test in development with an interactive server `Counter` component, make a copy of the `Client` project's `Counter` component and change its file name to `Counter2.razor`. Place the file in the Blazor Server app (`Pages/Counter2.razor` in the `Net8BlazorServer` project). - In the Blazor Server project (`Pages` folder of the `Net8BlazorServer` project), you can adopt the interactive server render mode for any components that should remain server-rendered: + Open the `Counter2.razor` file and change the route to avoid a conflict with the existing `Counter` component: - ```razor + ```diff + - @page "/counter" + + @page "/counter-2" + ``` + + Also, change the interactive render mode using ***either*** of the following lines: + + ```razor @attribute [RenderModeInteractiveServer] ``` @@ -376,6 +419,10 @@ Use the following process: ```razor @rendermode RenderMode.InteractiveServer ``` + + For Blazor Server components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. + + When the app is run in the next step, navigate to each of the counter components (`/counter` and `/counter-2`) to inspect how they render. If any of your server-side components should also disable prerendering, see <xref:blazor/components/render-modes#prerendering>. @@ -391,6 +438,8 @@ Use the following process: @rendermode RenderMode.InteractiveWebAssembly ``` + Such components only render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the interactive WebAssembly render mode. + For additional information on applying render modes to components, see <xref:blazor/components/render-modes>. 1. Run the solution from the ***Blazor Server*** project: @@ -399,12 +448,17 @@ Use the following process: If using the .NET CLI, run the project from the Blazor Server project's folder. + For the `Counter` component of the `.Client` project, navigate to `/counter`. + + If the `Counter2` component configured for strict interactive server rendering was implemented, navigate to `/counter-2`. + ### Convert a Blazor Server app into a Blazor Web App To adopt all of the changes that were made to the project templates for this release, we recommend the following process: * Create a new project from the Blazor Web App project template. For more information, see <xref:blazor/tooling>. * Move the app's components and code to the new app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). +* Update the layout and styles of the Blazor Web App to match the Blazor Server app. ### Update a Blazor WebAssembly app @@ -418,10 +472,6 @@ Adopt [8.0 features](xref:aspnetcore-8#blazor). ### Update a hosted Blazor WebAssembly app -************************************************************** -**** This section is a WIP: Will pick back up on Tuesday! **** -************************************************************** - To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: 1. Follow the guidance in the first three sections of this article: @@ -430,24 +480,113 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) -1. Move content from `Client/wwwroot/index.html` to `Host.razor` (commit): + > [!IMPORTANT] + > Using the preceding guidance, update the `Client`, `Server`, and `Shared` projects of the solution. + +1. Move the file content from the `Client/wwwroot/index.html` file to a new `Host.razor` file created at the root of the `Client` project. + +1. Make the following changes to the `Host.razor` file: - * Update script to `blazor.web.js`. - * Replace `<title>` tag with `HeadOutlet` component. + Replace the `<title>` tag with the `HeadOutlet` component. Start by removing the `<title>` tag: -1. Update `Client/Program.cs` (commit): Remove `builder.RootComponents.Add<HeadOutlet>("head::after")`. + ```diff + - <title>... + ``` + + Add the `HeadOutlet` component to the `` content with the interactive WebAssembly render mode: + + + + ```razor + + ``` + + Update Blazor script to `blazor.web.js`: + + ```diff + - + + + ``` + +1. Remove the following line from `Client/Program.cs`: + + ```diff + - builder.RootComponents.Add("head::after"); + ``` + +1. Update `Server/Program.cs`: + + Add a `using` statement for `` at the top of the file. + + > [!NOTE] + > In the following example, the project's namespace is `Net8BlazorWebAssembly.Client`. Adjust the namespace to match your project. + + ```csharp + using Host = Net8BlazorWebAssembly.Client.Host; + ``` + + Add Razor component and interactive WebAssembly component services to the project. Call `AddRazorComponents` with a chained call to `AddInteractiveWebAssemblyComponents`: + + ```csharp + builder.Services.AddRazorComponents() + .AddInteractiveWebAssemblyComponents(); + ``` + + Add [Antiforgery Middleware](xref:blazor/security/index#antiforgery-support) to the request processing pipeline immediately after the call to `app.UseRouting`. If there are calls to `app.UseRouting` and `app.UseEndpoints`, the call to `app.UseAntiforgery` must go between them. Calls to `app.UseAntiforgery` must be placed after calls to `app.UseAuthentication` and `app.UseAuthorization`. + + ```csharp + app.UseAntiforgery(); + ``` + + Remove the following line: + + ```diff + - app.UseBlazorFrameworkFiles(); + ``` + + Remove the following line: + + ```diff + - app.MapFallbackToFile("index.html"); + ``` + + Replace the preceding line with with a call to `MapRazorComponents`, supplying the `Host` component as the root component type, and a chained call to `AddInteractiveWebAssemblyRenderMode`: -1. Update `Server/Program.cs` (commit): + ```csharp + app.MapRazorComponents() + .AddInteractiveWebAssemblyRenderMode(); + ``` - * Add `builder.Services.AddRazorComponents().AddInteractiveWebAssemblyComponents()`. - * Remove `app.UseBlazorFrameworkFiles()`. - * Replace `MapFallbackToFile("index.html")` with `app.MapRazorComponents().AddInteractiveWebAssemblyRenderMode()`. +1. To enable prerendering: -To enable prerendering: + Update all components to support prerendering from the server. -* Update all components to support prerendering from the server (commit). + -* In `Host.razor` replace the `id=app` tag with `` (commit). + In the `Client/Host.razor` file, remove the following markup: + + ```diff + -
+ - + - + - + - + -
+ -
+ ``` + + Replace the preceding markup with the following line: + + ```razor + + ``` + +1. Run the solution from the `Server` project: + + For Visual Studio, confirm that the `Server` project is selected in **Solution Explorer** when running the app. + + If using the .NET CLI, run the project from the `Server` project's folder. ## Update Docker images From 8dd5d777011cb8b2ba941edf9205994e054eb37e Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Tue, 17 Oct 2023 10:12:22 -0400 Subject: [PATCH 08/20] Updates --- aspnetcore/migration/70-80.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 4653ff396643..3fdb8fa723db 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -483,7 +483,7 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: > [!IMPORTANT] > Using the preceding guidance, update the `Client`, `Server`, and `Shared` projects of the solution. -1. Move the file content from the `Client/wwwroot/index.html` file to a new `Host.razor` file created at the root of the `Client` project. +1. Move the file content from the `Client/wwwroot/index.html` file to a new `Host` component file (`Host.razor`) created at the root of the `Client` project. 1. Make the following changes to the `Host.razor` file: @@ -516,7 +516,7 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: 1. Update `Server/Program.cs`: - Add a `using` statement for `` at the top of the file. + Add a `using` statement for the `Host` component at the top of the file. > [!NOTE] > In the following example, the project's namespace is `Net8BlazorWebAssembly.Client`. Adjust the namespace to match your project. @@ -559,10 +559,11 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: 1. To enable prerendering: - Update all components to support prerendering from the server. + Update the app's Razor components to support prerendering from the server. - + In the `Client/Host.razor` file, remove the following markup: From 6315203ddffdf219bbd26a84d25ca69e4ec68e56 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Wed, 18 Oct 2023 10:27:34 -0400 Subject: [PATCH 09/20] Updates --- aspnetcore/migration/70-80.md | 92 +++++++++++++--------- aspnetcore/release-notes/aspnetcore-8.0.md | 2 +- 2 files changed, 57 insertions(+), 37 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 3fdb8fa723db..99538b3b87cc 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -26,9 +26,9 @@ This article explains how to update an existing ASP.NET Core 7.0 project to ASP. --- -## Update .NET Core SDK version in global.json +## Update .NET Core SDK version in `global.json` -If you rely on a [global.json](/dotnet/core/tools/global-json) file to target a specific .NET Core SDK version, update the `version` property to the .NET 8.0 SDK version that's installed. For example: +If you rely on a [`global.json`](/dotnet/core/tools/global-json) file to target a specific .NET Core SDK version, update the `version` property to the .NET 8.0 SDK version that's installed. For example: ```diff { @@ -56,7 +56,7 @@ Update the project file's [Target Framework Moniker (TFM)](/dotnet/standard/fram ## Update package references -In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/packages?q=Microsoft.AspNetCore.*), [Microsoft.EntityFrameworkCore.*](https://www.nuget.org/packages?q=Microsoft.EntityFrameworkCore.*), [Microsoft.Extensions.*](https://www.nuget.org/packages?q=Microsoft.Extensions.*), and [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) package reference's `Version` attribute to 8.00 or later. For example: +In the project file, update each [`Microsoft.AspNetCore.*`](https://www.nuget.org/packages?q=Microsoft.AspNetCore.*), [`Microsoft.EntityFrameworkCore.*`](https://www.nuget.org/packages?q=Microsoft.EntityFrameworkCore.*), [`Microsoft.Extensions.*`](https://www.nuget.org/packages?q=Microsoft.Extensions.*), and [`System.Net.Http.Json`](https://www.nuget.org/packages/System.Net.Http.Json) package reference's `Version` attribute to 8.00 or later. For example: ```diff @@ -83,22 +83,24 @@ The following migration scenarios are covered: * [Update a Blazor WebAssembly app](#update-a-blazor-webassembly-app) * [Update a hosted Blazor WebAssembly app](#update-a-hosted-blazor-webassembly-app) -For scenarios not covered or to convert the app into a Blazor Web App, we recommend the following process: +For scenarios not covered or to convert a .NET 6 or earlier app into a Blazor Web App, we recommend the following process: * Create a new app from the Blazor Web App project template. For more information, see . -* Move the your app's components and code to the new Blazor Web App app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). +* Move the your app's components and code to the new Blazor Web App app, making modifications to adopt new features. * Update the layout and styles of the Blazor Web App. +New .NET 8 features are covered in . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. + ### Update a Blazor Server app Blazor Server apps are supported in .NET 8. Use the following guidance to update a Blazor Server app to .NET 8, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. > [!IMPORTANT] -> This section focuses on the minimal changes required to update a Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. +> This section focuses on the minimal changes required to update a .NET 7 Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes for .NET 8, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. 1. Follow the guidance in the first three sections of this article: - * [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) + * [Update .NET Core SDK version in `global.json`](#update-net-core-sdk-version-in-globaljson) * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) @@ -130,7 +132,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update @inject IHostEnvironment Env ``` - Remove the tilde (`~`) from the value of `href` for the `` tag: + Remove the tilde (`~`) from the `href` of the `` tag: ```diff - @@ -143,7 +145,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update - ``` - Replace the tag helper with the following line: + Replace the preceding line's tag helper with the `HeadOutlet` component: ```razor @@ -155,7 +157,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update - ``` - Replace the tag helper with the following line: + Replace the preceding line's tag helper with the `Routes` component: ```razor @@ -175,16 +177,20 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update - ``` - Replace the tag helpers with the following lines: + Replace the preceding tag helpers with the following lines: ```razor @if (Env.IsDevelopment()) { - An unhandled exception has occurred. See browser dev tools for details. + + An unhandled exception has occurred. See browser dev tools for details. + } else { - An error has occurred. This application may no longer respond until reloaded. + + An error has occurred. This app may no longer respond until reloaded. + } ``` @@ -202,7 +208,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update > [!NOTE] > In the following example, the project's namespace is `Net8BlazorServer`. Adjust the namespace to match your project. - Add a `using` statement for the project's namespace: + Add a `using` statement to the top of the file for the project's namespace: ```csharp using Net8BlazorServer; @@ -223,7 +229,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update .AddInteractiveServerComponents(); ``` - Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and a chained call to `AddInteractiveServerRenderMode`. + Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and add a chained call to `AddInteractiveServerRenderMode`. Remove the following line: @@ -250,11 +256,18 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update app.UseAntiforgery(); ``` -1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components: +1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components. + + Remove the following from the `HeadOutlet` and `Routes` components: ```diff - @rendermode="RenderMode.InteractiveServer" - + @rendermode="new InteractiveServerRenderMode(prerender: false)" + ``` + + Replace with the following: + + ```razor + @rendermode="new InteractiveServerRenderMode(prerender: false)" ``` For more information, see . @@ -268,14 +281,13 @@ Use the following process: 1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app) section. > [!NOTE] - > For the examples in this section, the Blazor Server app's name and namespace is carried over from the preceding *Update a Blazor Server app* section. The example name/namespace is `Net8BlazorServer`. + > For the examples in this section, the Blazor Server app's name and namespace is carried over from the preceding *Update a Blazor Server app* section. The example app name and namespace is `Net8BlazorServer`. 1. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the Blazor Server app. [!INCLUDE[](~/includes/package-reference.md)] - + 1. Create a donor Blazor Web App, which will provide assets to the Blazor Server app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. @@ -287,19 +299,21 @@ Use the following process: 1. From the donor Blazor Web App, copy the entire `.Client` project into the solution folder of the Blazor Server app. > [!IMPORTANT] - > Don't copy the `.Client` folder into the Blazor Server project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the Blazor Server project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder for the Blazor Server app. The final project folder structure should have the following layout: + > Don't copy the `.Client` folder into the Blazor Server project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the Blazor Server project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder. The final project folder structure should have the following layout: > > * `Net8BlazorServerSolution` (top-level solution folder) > * `Net8BlazorServer` (original Blazor Server project) > * `Net8BlazorServer.Client` (`.Client` project folder from the donor Blazor Web App) > - > For the Blazor Server solution file, you can leave it in the Blazor Server project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. + > For the Blazor Server solution file, you can leave it in the Blazor Server project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. + +1. Delete the donor Blazor Web App, as it has no further use in this process. 1. Add the `.Client` project to the solution: In Visual Studio, right-click the solution in **Solution Explorer** and select **Add** > **Existing Project**. Navigate to the `.Client` folder and select the project file (`.csproj`). - If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the Blazor Server's solution. + If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the solution. 1. Add a project reference to the Blazor Server project for the client project: @@ -315,7 +329,7 @@ Use the following process: > The preceding command assumes the following: > > * The project file name is `Net8BlazorServer.Client.csproj`. - > * The `.Client` project is in a `Net8BlazorServer.Client` folder inside of a solution folder. The `.Client` folder is side-by-side with the Blazor Server project's folder. + > * The `.Client` project is in a `Net8BlazorServer.Client` folder inside the solution folder. The `.Client` folder is side-by-side with the Blazor Server project's folder. > > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). @@ -367,21 +381,23 @@ Use the following process: .AddAdditionalAssemblies(typeof(Net8BlazorServer.Client._Imports).Assembly); ``` -1. Configure the root `HeadOutlet` and `Routes` components to set the render mode on a per-component definition or instance. +1. Configure the root `HeadOutlet` and `Routes` components to set the render mode on a per-component definition or instance by removing the `@rendermode` directive attribute from each component instance. In the `App` component (`App.razor`): - ```razor - + ```diff + - + + ... - + - + + ``` 1. Configure the render mode and location of each Razor component in the Blazor Server app. - The donor Blazor Web App supplies a `Counter` component (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project) to the solution, which can be used for development testing. + The donor Blazor Web App supplies a `Counter` component to the solution (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project), which can be used for development testing. Notice that the `Counter` component in the `.Client` project adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directive: @@ -395,7 +411,7 @@ Use the following process: @rendermode RenderMode.InteractiveAuto ``` - For any of your Blazor Server app components that should also adopt the Auto render mode, move them to the `.Client` project's `Pages` folder (or `Shared` folder if a non-routable, shared component) and provide them with ***either*** of the preceding directives, noting that a shared component typically inherits its render mode and doesn't require a directive. + For any of your Blazor Server app components that should also adopt the Auto render mode, move them to the `.Client` project's `Pages` folder (or `Shared` folder for non-routable, shared components) and provide the routable components in the `Pages` folder with ***either*** of the preceding directives, noting that a shared component typically inherits its render mode and doesn't require a directive. Such components render on the server first, then render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the Auto render mode. @@ -420,7 +436,7 @@ Use the following process: @rendermode RenderMode.InteractiveServer ``` - For Blazor Server components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. + For Blazor Server components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives to them and leave them in the Blazor Server project's `Pages`/`Shared` folders. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. When the app is run in the next step, navigate to each of the counter components (`/counter` and `/counter-2`) to inspect how they render. @@ -450,16 +466,18 @@ Use the following process: For the `Counter` component of the `.Client` project, navigate to `/counter`. - If the `Counter2` component configured for strict interactive server rendering was implemented, navigate to `/counter-2`. + If you added the `Counter2` component, which is strictly configured for interactive server rendering, navigate to `/counter-2`. ### Convert a Blazor Server app into a Blazor Web App To adopt all of the changes that were made to the project templates for this release, we recommend the following process: * Create a new project from the Blazor Web App project template. For more information, see . -* Move the app's components and code to the new app, making modifications to adopt [8.0 features](xref:aspnetcore-8#blazor). +* Move the app's components and code to the new app, making modifications to adopt new features. * Update the layout and styles of the Blazor Web App to match the Blazor Server app. +New .NET 8 features are covered in . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. + ### Update a Blazor WebAssembly app Follow the guidance in the first three sections of this article: @@ -468,7 +486,7 @@ Follow the guidance in the first three sections of this article: * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) -Adopt [8.0 features](xref:aspnetcore-8#blazor). +Adopt [.NET 8 features](xref:aspnetcore-8#blazor). When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. ### Update a hosted Blazor WebAssembly app @@ -483,6 +501,8 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: > [!IMPORTANT] > Using the preceding guidance, update the `Client`, `Server`, and `Shared` projects of the solution. + For information on .NET 8 features, see . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. + 1. Move the file content from the `Client/wwwroot/index.html` file to a new `Host` component file (`Host.razor`) created at the root of the `Client` project. 1. Make the following changes to the `Host.razor` file: @@ -501,7 +521,7 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: ``` - Update Blazor script to `blazor.web.js`: + Update the `blazor.webassembly.js` script to `blazor.web.js`: ```diff - @@ -550,7 +570,7 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: - app.MapFallbackToFile("index.html"); ``` - Replace the preceding line with with a call to `MapRazorComponents`, supplying the `Host` component as the root component type, and a chained call to `AddInteractiveWebAssemblyRenderMode`: + Replace the preceding line with with a call to `MapRazorComponents`, supplying the `Host` component as the root component type, and add a chained call to `AddInteractiveWebAssemblyRenderMode`: ```csharp app.MapRazorComponents() diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md index 8de1edc69330..8b03dc2e32dc 100644 --- a/aspnetcore/release-notes/aspnetcore-8.0.md +++ b/aspnetcore/release-notes/aspnetcore-8.0.md @@ -22,8 +22,8 @@ This article is under development and not complete. More information may be foun * [What's new in .NET 8 Preview 6](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-6/) * [What's new in .NET 8 Preview 7](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-7/) * [What's new in .NET 8 Release Candidate 1](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-rc-1/) - From 6fa016d6085f72c1c30a0d07b1e49dfd39ea8a82 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 08:14:24 -0400 Subject: [PATCH 10/20] Apply suggestions from code review Co-authored-by: Daniel Roth --- aspnetcore/migration/70-80.md | 84 ++++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 35 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 99538b3b87cc..82af4bc5dee5 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -26,7 +26,7 @@ This article explains how to update an existing ASP.NET Core 7.0 project to ASP. --- -## Update .NET Core SDK version in `global.json` +## Update the .NET SDK version in `global.json` If you rely on a [`global.json`](/dotnet/core/tools/global-json) file to target a specific .NET Core SDK version, update the `version` property to the .NET 8.0 SDK version that's installed. For example: @@ -77,13 +77,14 @@ In the project file, update each [`Microsoft.AspNetCore.*`](https://www.nuget.or The following migration scenarios are covered: -* [Update a Blazor Server app](#update-a-blazor-server-app) -* [Add interactive WebAssembly components to a Blazor Server app](#add-interactive-webassembly-components-to-a-blazor-server-app) +* [Adopt Blazor Web App conventions](#adopt-blazor-web-app-conventions) * [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) -* [Update a Blazor WebAssembly app](#update-a-blazor-webassembly-app) -* [Update a hosted Blazor WebAssembly app](#update-a-hosted-blazor-webassembly-app) +* [Add interactive WebAssembly components to a Blazor Server app](#add-interactive-webassembly-components-to-a-blazor-server-app) +* [Convert a hosted Blazor WebAssembly app into a Blazor Web App](#convert-a-hosted-blazor-webassembly-app-into-a-blazor-web-app) -For scenarios not covered or to convert a .NET 6 or earlier app into a Blazor Web App, we recommend the following process: +## Adopt Blazor Web App conventions + +To optionally adopt all of the new Blazor Web App conventions, we recommend the following process: * Create a new app from the Blazor Web App project template. For more information, see . * Move the your app's components and code to the new Blazor Web App app, making modifications to adopt new features. @@ -91,16 +92,16 @@ For scenarios not covered or to convert a .NET 6 or earlier app into a Blazor We New .NET 8 features are covered in . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. -### Update a Blazor Server app +### Convert a Blazor Server app into a Blazor Web App -Blazor Server apps are supported in .NET 8. Use the following guidance to update a Blazor Server app to .NET 8, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. +Blazor Server apps are supported in .NET 8 without any code changes. Use the following guidance to convert a Blazor Server app into an equivalent .NET 8 Blazor Web App, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. > [!IMPORTANT] -> This section focuses on the minimal changes required to update a .NET 7 Blazor Server app to .NET 8. The guidance in this section doesn't cover adoption of the Blazor Web App project template folder and file layout structure, nor does it adhere to new layout, error UI, navigation menu, stylesheet, and other changes introduced for Blazor Web Apps. To adopt all of the introduced changes for .NET 8, convert the Blazor Server app into a Blazor Web App by following the guidance in the [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) section. +> This section focuses on the minimal changes required to convert a .NET 7 Blazor Server app into a .NET 8 Blazor Web App. To adopt all of the new Blazor Web App conventions, follow the guidance in the [Adopt Blazor Web App conventions](#adopt-blazor-web-app-conventions) section. 1. Follow the guidance in the first three sections of this article: - * [Update .NET Core SDK version in `global.json`](#update-net-core-sdk-version-in-globaljson) + * [Update the .NET SDK version in `global.json`](#update-the-net-core-sdk-version-in-globaljson) * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) @@ -132,7 +133,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update @inject IHostEnvironment Env ``` - Remove the tilde (`~`) from the `href` of the `` tag: + Remove the tilde (`~`) from the `href` of the `` tag and replace with the base path for your app: ```diff - @@ -148,7 +149,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update Replace the preceding line's tag helper with the `HeadOutlet` component: ```razor - + ``` Remove the Component Tag Helper for the `App` component: @@ -160,7 +161,7 @@ Blazor Server apps are supported in .NET 8. Use the following guidance to update Replace the preceding line's tag helper with the `Routes` component: ```razor - + ``` > [!NOTE] @@ -488,24 +489,35 @@ Follow the guidance in the first three sections of this article: Adopt [.NET 8 features](xref:aspnetcore-8#blazor). When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. -### Update a hosted Blazor WebAssembly app +### Convert a hosted Blazor WebAssembly app into a Blazor Web App -To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: +Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use the following guidance to convert an ASP.NET Core hosted Blazor WebAssembly app into an equivalent .NET 8 Blazor Web App, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. + +> [!IMPORTANT] +> This section focuses on the minimal changes required to convert a .NET 7 ASP.NET Core hosted Blazor WebAssembly app into a .NET 8 Blazor Web App. To adopt all of the new Blazor Web App conventions, follow the guidance in the [Adopt Blazor Web App conventions](#adopt-blazor-web-app-conventions) section. 1. Follow the guidance in the first three sections of this article: - * [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) + * [Update the .NET SDK version in `global.json`](#update-the-net-sdk-version-in-globaljson) * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) > [!IMPORTANT] > Using the preceding guidance, update the `Client`, `Server`, and `Shared` projects of the solution. - For information on .NET 8 features, see . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. +1. Move the file content from the `Client/wwwroot/index.html` file to a new `App` component file (`App.razor`) created at the root of the `Server` project. + +1. Rename `App.razor` in the `Client` project to `Routes.razor`. -1. Move the file content from the `Client/wwwroot/index.html` file to a new `Host` component file (`Host.razor`) created at the root of the `Client` project. +1. Add an entry to the `_Imports.razor` file to make shorthand render modes available to the app: -1. Make the following changes to the `Host.razor` file: + ```razor + @using static Microsoft.AspNetCore.Components.Web.RenderMode + ``` + +1. Make a copy of the `_Imports.razor` file and add it to the `Server` project. + +1. Make the following changes to the `App.razor` file: Replace the `` tag with the `HeadOutlet` component. Start by removing the `<title>` tag: @@ -513,14 +525,24 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: - <title>... ``` - Add the `HeadOutlet` component to the `` content with the interactive WebAssembly render mode: - - + Add the `HeadOutlet` component to the `` content with the interactive WebAssembly render mode and prerendering disabled: ```razor - + + + Replace the app `div` tag in `App.razor` with the `Routes` component. Start by removing the `div` tag: + + ```diff + -
+ - ... + -
``` + Add the `Routes` component with the interactive WebAssembly render mode and prerendering disabled: + + ```razor + ``` -1. Remove the following line from `Client/Program.cs`: +1. Remove the following lines from `Client/Program.cs`: ```diff + - builder.RootComponents.Add("#app"); - builder.RootComponents.Add("head::after"); ``` 1. Update `Server/Program.cs`: - Add a `using` statement for the `Host` component at the top of the file. - - > [!NOTE] - > In the following example, the project's namespace is `Net8BlazorWebAssembly.Client`. Adjust the namespace to match your project. - - ```csharp - using Host = Net8BlazorWebAssembly.Client.Host; - ``` - Add Razor component and interactive WebAssembly component services to the project. Call `AddRazorComponents` with a chained call to `AddInteractiveWebAssemblyComponents`: ```csharp @@ -570,10 +584,10 @@ To upgrade an existing ASP.NET Core hosted Blazor WebAssembly app to .NET 8: - app.MapFallbackToFile("index.html"); ``` - Replace the preceding line with with a call to `MapRazorComponents`, supplying the `Host` component as the root component type, and add a chained call to `AddInteractiveWebAssemblyRenderMode`: + Replace the preceding line with a call to `MapRazorComponents`, supplying the `App` component as the root component type, and add a chained call to `AddInteractiveWebAssemblyRenderMode`: ```csharp - app.MapRazorComponents() + app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` From b19e4178ba623b8d3af156857cf82d2a8259b1dd Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 09:12:38 -0400 Subject: [PATCH 11/20] Updates --- aspnetcore/blazor/components/integration.md | 158 +++++++++++- aspnetcore/migration/70-80.md | 255 +------------------- 2 files changed, 164 insertions(+), 249 deletions(-) diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index b6e6bfd6b3e4..3da34f60b199 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -18,13 +18,169 @@ uid: blazor/components/integration This article explains Razor component integration scenarios for ASP.NET Core apps, including prerendering of Razor components on the server. -Razor components can be integrated into Razor Pages and MVC apps. When the page or view is rendered, components can be prerendered at the same time. Prerendering can improve [Search Engine Optimization (SEO)](https://developer.mozilla.org/docs/Glossary/SEO) by rendering content for the initial HTTP response that search engines can use to calculate page rank. +Razor components can be integrated into Razor Pages, MVC, and other types of ASP.NET Core apps with prerendering. Prerendering can improve [Search Engine Optimization (SEO)](https://developer.mozilla.org/docs/Glossary/SEO) by rendering content for the initial HTTP response that search engines can use to calculate page rank. Use the guidance in the following sections depending on the project's requirements: +* Blazor support can be [added to an ASP.NET Core app](#add-blazor-support-to-an-aspnet-core-app). * For interactive components that aren't directly routable from user requests, see the [Use non-routable components in pages or views](#use-non-routable-components-in-pages-or-views) section. Follow this guidance when the app embeds components into existing pages and views with the [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper). * For interactive components that are directly routable from user requests, see the [Use routable components](#use-routable-components) section. Follow this guidance when visitors should be able to make an HTTP request in their browser for a component with an [`@page`](xref:mvc/views/razor#page) directive. +## Add Blazor support to an ASP.NET Core app + +This section covers adding Blazor support to an ASP.NET Core app. + +> [!NOTE] +> For the examples in this section, the example app's name and namespace is `AspNetCoreApp`. + +1. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the app. + + [!INCLUDE[](~/includes/package-reference.md)] + + + +1. Create a donor Blazor Web App, which will provide assets to the app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. + + For the app's name, use the same name as the ASP.NET Core app, which results in matching app name markup in components and matching namespaces in code. + + * For **Interactivity type**, select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. + * Set the **Interactivity location** to **Per page/component**. + +1. From the donor Blazor Web App, copy the entire `.Client` project into the solution folder of the ASP.NET Core app. + + > [!IMPORTANT] + > Don't copy the `.Client` folder into the ASP.NET Core project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the ASP.NET Core project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder. The final project folder structure should have the following layout: + > + > * `AspNetCoreAppSolution` (top-level solution folder) + > * `AspNetCoreApp` (original ASP.NET Core project) + > * `AspNetCoreApp.Client` (`.Client` project folder from the donor Blazor Web App) + > + > For the ASP.NET Core solution file, you can leave it in the ASP.NET Core project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. + +1. In the ASP.NET Core project: + + * Create a `Components` folder. + * Create a `Pages` folder inside of the `Components` folder. + +1. From the donor Blazor Web App, copy the entire `Components` folder into the ASP.NET Core project folder. + +1. In the ASP.NET Core project's `Components` folder, delete the following components from the `Components/Pages` folder: + + * `Home` component (`Home.razor`) + * `Weather` component (`Weather.razor`) + +1. If you named the donor Blazor Web App when you created the donor project the same as the ASP.NET Core app, the namespaces used by the donated assets match those in the ASP.NET Core app. You shouldn't need to take further steps. If you used a different name, which results in a mismatch between the donor app's namespaces and the ASP.NET Core app, you must adjust the namespaces across the donated assets. If this is required, adjust the namespaces before proceeding. + +1. Delete the donor Blazor Web App, as it has no further use in this process. + +1. Add the `.Client` project to the solution: + + In Visual Studio, right-click the solution in **Solution Explorer** and select **Add** > **Existing Project**. Navigate to the `.Client` folder and select the project file (`.csproj`). + + If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the solution. + +1. Add a project reference to the ASP.NET Core project for the client project: + + In Visual Studio, right-click the ASP.NET Core project and select **Add** > **Project Reference**. Select the `.Client` project and select **OK**. + + If using the .NET CLI, from the ASP.NET Core project's folder, use the following command: + + ```dotnetcli + dotnet add reference ../AspNetCoreApp.Client/AspNetCoreApp.Client.csproj + ``` + + > [!NOTE] + > The preceding command assumes the following: + > + > * The project file name is `AspNetCoreApp.Client.csproj`. + > * The `.Client` project is in a `AspNetCoreApp.Client` folder inside the solution folder. The `.Client` folder is side-by-side with the ASP.NET Core project's folder. + > + > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). + +1. In the ASP.NET Core app's `Program` file, add the interactive component services (`AddInteractiveServerComponents` and `AddInteractiveWebAssemblyComponents`) with Razor component services (`AddRazorComponents`) before the app is built (the line that calls `builder.Build()`): + + ```csharp + builder.Services.AddRazorComponents() + .AddInteractiveServerComponents() + .AddInteractiveWebAssemblyComponents(); + ``` + + Add the interactive render modes (`AddInteractiveServerRenderMode` and `AddInteractiveWebAssemblyRenderMode`) and additional assemblies for the `.Client` project with `MapRazorComponents` before the app is run (the line that calls `app.Run`): + + ```csharp + app.MapRazorComponents() + .AddInteractiveServerRenderMode() + .AddInteractiveWebAssemblyRenderMode() + .AddAdditionalAssemblies(typeof(AspNetCoreApp.Client._Imports).Assembly); + ``` + +1. As you add Razor components to the solution, either in the ASP.NET Core project or the `.Client` project, configure the render mode of each component. + + The donor Blazor Web App supplies a `Counter` component to the solution (`Pages/Counter.razor` in the `AspNetCoreApp.Client` project), which can be used for development testing. + + Notice that the `Counter` component in the `.Client` project adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directive: + + ```razor + @attribute [RenderModeInteractiveAuto] + ``` + + ```razor + @rendermode InteractiveAuto + ``` + + For any of your ASP.NET Core app components that should also adopt the Auto render mode, place them in the `.Client` project's `Pages` folder (or `Shared` folder for non-routable, shared components) and provide the routable components in the `Pages` folder with ***either*** of the preceding directives, noting that a shared component typically inherits its render mode and doesn't require a directive. + + Such components render on the server first, then render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the Auto render mode. + + To further test in development with an interactive server `Counter` component, make a copy of the `Client` project's `Counter` component and change its file name to `Counter2.razor`. Place the file in the ASP.NET Core app (`Pages/Counter2.razor` in the `AspNetCoreApp` project). + + Open the `Counter2.razor` file and change the route to avoid a conflict with the existing `Counter` component: + + ```diff + - @page "/counter" + + @page "/counter-2" + ``` + + Also, change the interactive render mode using ***either*** of the following lines: + + ```razor + @attribute [RenderModeInteractiveServer] + ``` + + ```razor + @rendermode InteractiveServer + ``` + + For components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives to them and leave them in the ASP.NET Core project's `Pages`/`Shared` folders. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. + + When the app is run in the next step, navigate to each of the counter components (`/counter` and `/counter-2`) to inspect how they render. + + If any of your server-side components should also disable prerendering, see . + + For any components that should strictly adopt the interactive WebAssembly render mode in the `.Client` project (`Pages` folder of the `AspNetCoreApp.Client` project), explicitly configure the render mode: + + ```razor + @attribute [RenderModeInteractiveWebAssembly] + ``` + + ```razor + @rendermode InteractiveWebAssembly + ``` + + Such components only render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the interactive WebAssembly render mode. + + For additional information on applying render modes to components, see . + +1. Run the solution from the ***ASP.NET Core app*** project: + + For Visual Studio, confirm that the ASP.NET Core project is selected in **Solution Explorer** when running the app. + + If using the .NET CLI, run the project from the ASP.NET Core project's folder. + + For the `Counter` component of the `.Client` project, navigate to `/counter`. + + If you added the `Counter2` component, which is strictly configured for interactive server rendering, navigate to `/counter-2`. + ## Use non-routable components in pages or views Use the following guidance to integrate Razor components into pages and views of an existing Razor Pages or MVC app with the [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper). diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 82af4bc5dee5..f3b1404e569c 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -79,9 +79,10 @@ The following migration scenarios are covered: * [Adopt Blazor Web App conventions](#adopt-blazor-web-app-conventions) * [Convert a Blazor Server app into a Blazor Web App](#convert-a-blazor-server-app-into-a-blazor-web-app) -* [Add interactive WebAssembly components to a Blazor Server app](#add-interactive-webassembly-components-to-a-blazor-server-app) * [Convert a hosted Blazor WebAssembly app into a Blazor Web App](#convert-a-hosted-blazor-webassembly-app-into-a-blazor-web-app) +For guidance on adding Blazor support to an ASP.NET Core app, see . + ## Adopt Blazor Web App conventions To optionally adopt all of the new Blazor Web App conventions, we recommend the following process: @@ -101,7 +102,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol 1. Follow the guidance in the first three sections of this article: - * [Update the .NET SDK version in `global.json`](#update-the-net-core-sdk-version-in-globaljson) + * [Update the .NET SDK version in `global.json`](#update-the-net-sdk-version-in-globaljson) * [Update the target framework](#update-the-target-framework) * [Update package references](#update-package-references) @@ -116,14 +117,14 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol 1. Move the content in the `_Host` page (`Pages/_Host.cshtml`) to the empty `App.razor` file. Proceed to make the following changes to the `App` component. > [!NOTE] - > In the following example, the project's namespace is `Net8BlazorServer`. Adjust the namespace to match your project. + > In the following example, the project's namespace is `BlazorServerApp`. Adjust the namespace to match your project. Remove the following lines from the top of the file: ```diff - @page "/" - @using Microsoft.AspNetCore.Components.Web - - @namespace Net8BlazorServer.Pages + - @namespace BlazorServerApp.Pages - @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers ``` @@ -207,12 +208,12 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol 1. Update `Program.cs`: > [!NOTE] - > In the following example, the project's namespace is `Net8BlazorServer`. Adjust the namespace to match your project. + > In the following example, the project's namespace is `BlazorServerApp`. Adjust the namespace to match your project. Add a `using` statement to the top of the file for the project's namespace: ```csharp - using Net8BlazorServer; + using BlazorServerApp; ``` Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddInteractiveServerComponents`. @@ -273,222 +274,6 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol For more information, see . -### Add interactive WebAssembly components to a Blazor Server app - -This section covers adding interactive WebAssembly components to a Blazor Server app after updating the Blazor Server app to .NET 8. - -Use the following process: - -1. Follow the guidance in the [Update a Blazor Server app](#update-a-blazor-server-app) section. - - > [!NOTE] - > For the examples in this section, the Blazor Server app's name and namespace is carried over from the preceding *Update a Blazor Server app* section. The example app name and namespace is `Net8BlazorServer`. - -1. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the Blazor Server app. - - [!INCLUDE[](~/includes/package-reference.md)] - - - -1. Create a donor Blazor Web App, which will provide assets to the Blazor Server app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. - - For the app's name, use the same name as the Blazor Server app, which results in matching app name markup in components and matching namespaces in code. - - * For **Interactivity type**, select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. - * Ignore the **Interactivity location** setting. The `App` component of the donor project isn't used, and configuring the render mode globally or on a per-component basis is covered by a manual change made to the app in a later step. - -1. From the donor Blazor Web App, copy the entire `.Client` project into the solution folder of the Blazor Server app. - - > [!IMPORTANT] - > Don't copy the `.Client` folder into the Blazor Server project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the Blazor Server project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder. The final project folder structure should have the following layout: - > - > * `Net8BlazorServerSolution` (top-level solution folder) - > * `Net8BlazorServer` (original Blazor Server project) - > * `Net8BlazorServer.Client` (`.Client` project folder from the donor Blazor Web App) - > - > For the Blazor Server solution file, you can leave it in the Blazor Server project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. - -1. Delete the donor Blazor Web App, as it has no further use in this process. - -1. Add the `.Client` project to the solution: - - In Visual Studio, right-click the solution in **Solution Explorer** and select **Add** > **Existing Project**. Navigate to the `.Client` folder and select the project file (`.csproj`). - - If using the .NET CLI, use the [`dotnet sln add` command](/dotnet/core/tools/dotnet-sln#add) to add the `.Client` project to the solution. - -1. Add a project reference to the Blazor Server project for the client project: - - In Visual Studio, right-click the Blazor Server project and select **Add** > **Project Reference**. Select the `.Client` project and select **OK**. - - If using the .NET CLI, from the Blazor Server project's folder, use the following command: - - ```dotnetcli - dotnet add reference ../Net8BlazorServer.Client/Net8BlazorServer.Client.csproj - ``` - - > [!NOTE] - > The preceding command assumes the following: - > - > * The project file name is `Net8BlazorServer.Client.csproj`. - > * The `.Client` project is in a `Net8BlazorServer.Client` folder inside the solution folder. The `.Client` folder is side-by-side with the Blazor Server project's folder. - > - > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). - -1. In the Blazor Server app's `Routes` component (`Routes.razor`): - - Add the client project's assembly to the router in the first line of the file: - - ```diff - - - + - ``` - - Remove the `` tags and content, as this markup is no longer used: - - ```diff - - - - Not found - - - -

Sorry, there's nothing at this address.

- - - - - ``` - - If you want to replace the loss of `` functionality, implement [Status Code Pages](xref:fundamentals/error-handling#usestatuscodepages) in the Blazor Server app (`Net8BlazorServer` project), which includes options for a default response string, a custom response string, or a redirect to an error handling endpoint. - - For a default response string, place Status Code Pages Middleware immediately after the line that adds HTTPS Redirection Middleware (`app.UseHttpsRedirection`) in the `Program` file of the Blazor Server app: - - ```csharp - app.UseStatusCodePages(); - ``` - - For more information, see . - -1. Add the interactive WebAssembly component services (`AddInteractiveWebAssemblyComponents`) to the project's `Program` file where Razor component services are added with `AddRazorComponents`: - - ```csharp - builder.Services.AddRazorComponents() - .AddInteractiveServerComponents() - .AddInteractiveWebAssemblyComponents(); - ``` - - Add the interactive WebAssembly render mode (`AddInteractiveWebAssemblyRenderMode`) and additional assemblies for the `.Client` project where Razor components are mapped with `MapRazorComponents`: - - ```csharp - app.MapRazorComponents() - .AddInteractiveServerRenderMode() - .AddInteractiveWebAssemblyRenderMode() - .AddAdditionalAssemblies(typeof(Net8BlazorServer.Client._Imports).Assembly); - ``` - -1. Configure the root `HeadOutlet` and `Routes` components to set the render mode on a per-component definition or instance by removing the `@rendermode` directive attribute from each component instance. - - In the `App` component (`App.razor`): - - ```diff - - - + - - ... - - - - + - ``` - -1. Configure the render mode and location of each Razor component in the Blazor Server app. - - The donor Blazor Web App supplies a `Counter` component to the solution (`Pages/Counter.razor` in the `Net8BlazorServer.Client` project), which can be used for development testing. - - Notice that the `Counter` component in the `.Client` project adopts the Auto render mode either using the `@attribute` ***or*** `@rendermode` directive: - - ```razor - @attribute [RenderModeInteractiveAuto] - ``` - - - - ```razor - @rendermode RenderMode.InteractiveAuto - ``` - - For any of your Blazor Server app components that should also adopt the Auto render mode, move them to the `.Client` project's `Pages` folder (or `Shared` folder for non-routable, shared components) and provide the routable components in the `Pages` folder with ***either*** of the preceding directives, noting that a shared component typically inherits its render mode and doesn't require a directive. - - Such components render on the server first, then render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the Auto render mode. - - To further test in development with an interactive server `Counter` component, make a copy of the `Client` project's `Counter` component and change its file name to `Counter2.razor`. Place the file in the Blazor Server app (`Pages/Counter2.razor` in the `Net8BlazorServer` project). - - Open the `Counter2.razor` file and change the route to avoid a conflict with the existing `Counter` component: - - ```diff - - @page "/counter" - + @page "/counter-2" - ``` - - Also, change the interactive render mode using ***either*** of the following lines: - - ```razor - @attribute [RenderModeInteractiveServer] - ``` - - - - ```razor - @rendermode RenderMode.InteractiveServer - ``` - - For Blazor Server components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives to them and leave them in the Blazor Server project's `Pages`/`Shared` folders. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. - - When the app is run in the next step, navigate to each of the counter components (`/counter` and `/counter-2`) to inspect how they render. - - If any of your server-side components should also disable prerendering, see . - - For any components that should strictly adopt the interactive WebAssembly render mode in the `.Client` project (`Pages` folder of the `Net8BlazorServer.Client` project), explicitly configure the render mode: - - ```razor - @attribute [RenderModeInteractiveWebAssembly] - ``` - - - - ```razor - @rendermode RenderMode.InteractiveWebAssembly - ``` - - Such components only render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Keep in mind that component code is ***not*** private using the interactive WebAssembly render mode. - - For additional information on applying render modes to components, see . - -1. Run the solution from the ***Blazor Server*** project: - - For Visual Studio, confirm that the Blazor Server project is selected in **Solution Explorer** when running the app. - - If using the .NET CLI, run the project from the Blazor Server project's folder. - - For the `Counter` component of the `.Client` project, navigate to `/counter`. - - If you added the `Counter2` component, which is strictly configured for interactive server rendering, navigate to `/counter-2`. - -### Convert a Blazor Server app into a Blazor Web App - -To adopt all of the changes that were made to the project templates for this release, we recommend the following process: - -* Create a new project from the Blazor Web App project template. For more information, see . -* Move the app's components and code to the new app, making modifications to adopt new features. -* Update the layout and styles of the Blazor Web App to match the Blazor Server app. - -New .NET 8 features are covered in . When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. - -### Update a Blazor WebAssembly app - -Follow the guidance in the first three sections of this article: - -* [Update .NET Core SDK version in global.json](#update-net-core-sdk-version-in-globaljson) -* [Update the target framework](#update-the-target-framework) -* [Update package references](#update-package-references) - -Adopt [.NET 8 features](xref:aspnetcore-8#blazor). When updating an app from .NET 6 or earlier, see the migration and release notes (*What's new* articles) for intervening releases. - ### Convert a hosted Blazor WebAssembly app into a Blazor Web App Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use the following guidance to convert an ASP.NET Core hosted Blazor WebAssembly app into an equivalent .NET 8 Blazor Web App, which makes all of the [new .NET 8 features](xref:aspnetcore-8#blazor) available. @@ -591,32 +376,6 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th .AddInteractiveWebAssemblyRenderMode(); ``` -1. To enable prerendering: - - Update the app's Razor components to support prerendering from the server. - - - - In the `Client/Host.razor` file, remove the following markup: - - ```diff - -
- - - - - - - - - -
- -
- ``` - - Replace the preceding markup with the following line: - - ```razor - - ``` - 1. Run the solution from the `Server` project: For Visual Studio, confirm that the `Server` project is selected in **Solution Explorer** when running the app. From 8a0de29fafb8cf88dcc6f1d25a58feb5cb6b78fc Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 10:01:33 -0400 Subject: [PATCH 12/20] Updates --- aspnetcore/blazor/components/integration.md | 67 +++++++++++++++++---- aspnetcore/migration/70-80.md | 2 +- 2 files changed, 55 insertions(+), 14 deletions(-) diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index 3da34f60b199..4c5b2b7766d1 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -41,15 +41,21 @@ This section covers adding Blazor support to an ASP.NET Core app. 1. Create a donor Blazor Web App, which will provide assets to the app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. - For the app's name, use the same name as the ASP.NET Core app, which results in matching app name markup in components and matching namespaces in code. + > [!IMPORTANT] + > For the app's name, use the same name as the ASP.NET Core app, which results in matching app name markup in components and matching namespaces in code. Using the same name/namespace isn't strictly required, as namespaces can be adjusted after assets are moved from the donor app to the ASP.NET Core app. However, time is saved by matching the namespaces at the outset, so that assets can be moved from the donor app to the ASP.NET Core app and used without spending time making manual namespace adjustments. * For **Interactivity type**, select **Auto (Server and WebAssembly)** for Visual Studio or use the `-int Auto` option if using the .NET CLI. - * Set the **Interactivity location** to **Per page/component**. + * Set the **Interactivity location** to **Per page/component** for Visual Studio or ***avoid*** using the `-ai|--all-interactive` option when using the .NET CLI. + +1. From the donor Blazor Web App, copy Bootstrap and Blazor styles into the ASP.NET Core project's `wwwroot` folder: + + * `wwwroot/bootstrap` folder + * `app.css` 1. From the donor Blazor Web App, copy the entire `.Client` project into the solution folder of the ASP.NET Core app. > [!IMPORTANT] - > Don't copy the `.Client` folder into the ASP.NET Core project's folder. The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the ASP.NET Core project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder. The final project folder structure should have the following layout: + > **Don't copy the `.Client` folder into the ASP.NET Core project's folder.** The best approach for organizing .NET solutions is to place each project of the solution into its own folder inside of a top-level solution folder. If a solution folder above the ASP.NET Core project's folder doesn't exist, create one. Next, copy the `.Client` project's folder from the donor Blazor Web App into the solution folder. The final project folder structure should have the following layout: > > * `AspNetCoreAppSolution` (top-level solution folder) > * `AspNetCoreApp` (original ASP.NET Core project) @@ -57,11 +63,6 @@ This section covers adding Blazor support to an ASP.NET Core app. > > For the ASP.NET Core solution file, you can leave it in the ASP.NET Core project's folder. Alternatively, you can move the solution file or create a new one in the top-level solution folder as long as the project references correctly point to the project files (`.csproj`) of the two projects in the solution folder. -1. In the ASP.NET Core project: - - * Create a `Components` folder. - * Create a `Pages` folder inside of the `Components` folder. - 1. From the donor Blazor Web App, copy the entire `Components` folder into the ASP.NET Core project folder. 1. In the ASP.NET Core project's `Components` folder, delete the following components from the `Components/Pages` folder: @@ -69,7 +70,7 @@ This section covers adding Blazor support to an ASP.NET Core app. * `Home` component (`Home.razor`) * `Weather` component (`Weather.razor`) -1. If you named the donor Blazor Web App when you created the donor project the same as the ASP.NET Core app, the namespaces used by the donated assets match those in the ASP.NET Core app. You shouldn't need to take further steps. If you used a different name, which results in a mismatch between the donor app's namespaces and the ASP.NET Core app, you must adjust the namespaces across the donated assets. If this is required, adjust the namespaces before proceeding. +1. If you named the donor Blazor Web App when you created the donor project the same as the ASP.NET Core app, the namespaces used by the donated assets match those in the ASP.NET Core app. You shouldn't need to take further steps to match namespaces. If you used a different namespace when creating the donor Blazor Web App project, you must adjust the namespaces across the donated assets to match if you intend to use the rest of this guidance exactly as presented. If the namespaces don't match, ***either*** adjust the namespaces before proceeding ***or*** adjust the namespaces as you following the remaining guidance in this section. 1. Delete the donor Blazor Web App, as it has no further use in this process. @@ -86,7 +87,7 @@ This section covers adding Blazor support to an ASP.NET Core app. If using the .NET CLI, from the ASP.NET Core project's folder, use the following command: ```dotnetcli - dotnet add reference ../AspNetCoreApp.Client/AspNetCoreApp.Client.csproj + dotnet add reference ../AspNetCoreApp.Client/AspNetCoreApp.Client.csproj ``` > [!NOTE] @@ -97,7 +98,13 @@ This section covers adding Blazor support to an ASP.NET Core app. > > For more information on the `dotnet add reference` command, see [`dotnet add reference` (.NET documentation)](/dotnet/core/tools/dotnet-add-reference). -1. In the ASP.NET Core app's `Program` file, add the interactive component services (`AddInteractiveServerComponents` and `AddInteractiveWebAssemblyComponents`) with Razor component services (`AddRazorComponents`) before the app is built (the line that calls `builder.Build()`): +1. In the ASP.NET Core project's `Program` file, add a `using` statement to the top of the file for the project's components: + + ```csharp + using AspNetCoreApp.Components; + ``` + + Add the interactive component services (`AddInteractiveServerComponents` and `AddInteractiveWebAssemblyComponents`) with Razor component services (`AddRazorComponents`) before the app is built (the line that calls `builder.Build()`): ```csharp builder.Services.AddRazorComponents() @@ -105,6 +112,12 @@ This section covers adding Blazor support to an ASP.NET Core app. .AddInteractiveWebAssemblyComponents(); ``` + Add [Antiforgery Middleware](xref:blazor/security/index#antiforgery-support) to the request processing pipeline after the call to `app.UseRouting`. If there are calls to `app.UseRouting` and `app.UseEndpoints`, the call to `app.UseAntiforgery` must go between them. A call to `app.UseAntiforgery` must be placed after calls to `app.UseAuthentication` and `app.UseAuthorization`. + + ```csharp + app.UseAntiforgery(); + ``` + Add the interactive render modes (`AddInteractiveServerRenderMode` and `AddInteractiveWebAssemblyRenderMode`) and additional assemblies for the `.Client` project with `MapRazorComponents` before the app is run (the line that calls `app.Run`): ```csharp @@ -140,8 +153,8 @@ This section covers adding Blazor support to an ASP.NET Core app. - @page "/counter" + @page "/counter-2" ``` - - Also, change the interactive render mode using ***either*** of the following lines: + + Change the interactive render mode using ***either*** of the following lines: ```razor @attribute [RenderModeInteractiveServer] @@ -151,6 +164,34 @@ This section covers adding Blazor support to an ASP.NET Core app. @rendermode InteractiveServer ``` + Change the page title and heading markup to reflect that this is the 2nd counter component in the app: + + ```razor + Counter 2 + +

Counter 2

+ ``` + + Add the `Counter2` component to the `NavMenu` component (`Pages/Layout/NavMenu.razor`): + + ```razor +
+ + Counter 2 + +
+ ``` + + Remove the `Weather` component navigation menu entry from the `NavMenu` component: + + ```diff + -
+ - + - Weather + - + -
+ ``` + For components that should also strictly adopt the interactive server render mode, add ***either*** of the preceding directives to them and leave them in the ASP.NET Core project's `Pages`/`Shared` folders. Such components only ever render on the server. Component code is kept private on the server using the interactive server render mode. When the app is run in the next step, navigate to each of the counter components (`/counter` and `/counter-2`) to inspect how they render. diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index f3b1404e569c..369b9663529b 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -252,7 +252,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol - app.MapFallbackToPage("/_Host"); ``` - Add [Antiforgery Middleware](xref:blazor/security/index#antiforgery-support) to the request processing pipeline immediately after the call to `app.UseRouting`. If there are calls to `app.UseRouting` and `app.UseEndpoints`, the call to `app.UseAntiforgery` must go between them. Calls to `app.UseAntiforgery` must be placed after calls to `app.UseAuthentication` and `app.UseAuthorization`. + Add [Antiforgery Middleware](xref:blazor/security/index#antiforgery-support) to the request processing pipeline after the call to `app.UseRouting`. If there are calls to `app.UseRouting` and `app.UseEndpoints`, the call to `app.UseAntiforgery` must go between them. A call to `app.UseAntiforgery` must be placed after calls to `app.UseAuthentication` and `app.UseAuthorization`. ```csharp app.UseAntiforgery(); From 43f76cf1814db38b40f6f089affb6ce702e3843b Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 10:30:27 -0400 Subject: [PATCH 13/20] Updates --- aspnetcore/migration/70-80.md | 43 ++++++++++------------------------- 1 file changed, 12 insertions(+), 31 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 369b9663529b..b174cf26bfa0 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -119,7 +119,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol > [!NOTE] > In the following example, the project's namespace is `BlazorServerApp`. Adjust the namespace to match your project. - Remove the following lines from the top of the file: + Remove the following lines from the top of the file and replace them with a line that injects an instance: ```diff - @page "/" @@ -127,8 +127,6 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol - @namespace BlazorServerApp.Pages - @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers ``` - - Replace the preceding lines with the following: ```razor @inject IHostEnvironment Env @@ -141,26 +139,22 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol + ``` - Remove the Component Tag Helper for the `HeadOutlet` component: + Remove the Component Tag Helper for the `HeadOutlet` component and replace the preceding line with the `HeadOutlet` component: ```diff - ``` - Replace the preceding line's tag helper with the `HeadOutlet` component: - ```razor ``` - Remove the Component Tag Helper for the `App` component: + Remove the Component Tag Helper for the `App` component and replace it with the `Routes` component: ```diff - ``` - Replace the preceding line's tag helper with the `Routes` component: - ```razor ``` @@ -168,7 +162,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol > [!NOTE] > The preceding configuration assumes that the app's components adopt interactive server rendering. For more information, including how to adopt static server rendering, see . - Remove the Environment Tag Helpers for error UI: + Remove the Environment Tag Helpers for error UI and replace them with the following Razor markup: ```diff - @@ -179,8 +173,6 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol - ``` - Replace the preceding tag helpers with the following lines: - ```razor @if (Env.IsDevelopment()) { @@ -218,29 +210,23 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol Replace `AddServerSideBlazor` with `AddRazorComponents` and a chained call to `AddInteractiveServerComponents`. - Remove the following line: + Remove the following line and replace it with Razor component and interactive server component services: ```diff - builder.Services.AddServerSideBlazor(); ``` - Replace the line with the following lines: - ```csharp builder.Services.AddRazorComponents() .AddInteractiveServerComponents(); ``` - Replace `MapBlazorHub` with `MapRazorComponents`, supplying the `App` component as the root component type, and add a chained call to `AddInteractiveServerRenderMode`. - - Remove the following line: + Remove the following line and replace it with a call to `MapRazorComponents`, supplying the `App` component as the root component type, and add a chained call to `AddInteractiveServerRenderMode`: ```diff - app.MapBlazorHub(); ``` - Replace the line with the following lines: - ```csharp app.MapRazorComponents() .AddInteractiveServerRenderMode(); @@ -260,14 +246,12 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol 1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components. - Remove the following from the `HeadOutlet` and `Routes` components: + Remove the following from the `HeadOutlet` and `Routes` components and replace with the following `@rendermode` that disables prerendering: ```diff - @rendermode="RenderMode.InteractiveServer" ``` - Replace with the following: - ```razor @rendermode="new InteractiveServerRenderMode(prerender: false)" ``` @@ -315,7 +299,7 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th ```razor - Replace the app `div` tag in `App.razor` with the `Routes` component. Start by removing the `div` tag: + Replace the following `div` tag with the `Routes` component using the interactive WebAssembly render mode and prerendering disabled: ```diff -
@@ -323,11 +307,10 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th -
``` - Add the `Routes` component with the interactive WebAssembly render mode and prerendering disabled: - ```razor () .AddInteractiveWebAssemblyRenderMode(); From 38c2b3d4b994d78c552e9520f020efd62c9e4612 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 10:33:45 -0400 Subject: [PATCH 14/20] Updates --- aspnetcore/migration/70-80.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index b174cf26bfa0..f48637185f97 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -139,7 +139,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol + ``` - Remove the Component Tag Helper for the `HeadOutlet` component and replace the preceding line with the `HeadOutlet` component: + Remove the Component Tag Helper for the `HeadOutlet` component and replace it with the `HeadOutlet` component: ```diff - @@ -246,7 +246,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol 1. If the Blazor Server app was configured to disable prerendering, you can continue to disable prerendering for the updated app. In the `App` component, change the value assigned to the `@rendermode` Razor directive attributes for the `HeadOutlet` and `Routes` components. - Remove the following from the `HeadOutlet` and `Routes` components and replace with the following `@rendermode` that disables prerendering: + Remove the following from the `HeadOutlet` and `Routes` components and replace them with the following `@rendermode` that disables prerendering: ```diff - @rendermode="RenderMode.InteractiveServer" From 203611a01782cf0be00337e8791f1464e93e4813 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 11:40:00 -0400 Subject: [PATCH 15/20] Update aspnetcore/migration/70-80.md Co-authored-by: Daniel Roth --- aspnetcore/migration/70-80.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index f48637185f97..fe1e19dae342 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -249,7 +249,7 @@ Blazor Server apps are supported in .NET 8 without any code changes. Use the fol Remove the following from the `HeadOutlet` and `Routes` components and replace them with the following `@rendermode` that disables prerendering: ```diff - - @rendermode="RenderMode.InteractiveServer" + - @rendermode="InteractiveServer" ``` ```razor From 9a0ac6bbfd7d20cea29e1e38e1614ae6aec291f2 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 12:59:29 -0400 Subject: [PATCH 16/20] Apply suggestions from code review Co-authored-by: Daniel Roth --- aspnetcore/migration/70-80.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index fe1e19dae342..0d3592c3517b 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -294,10 +294,11 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th - ... ``` - Add the `HeadOutlet` component to the `` content with the interactive WebAssembly render mode and prerendering disabled: + Add the `HeadOutlet` component at the end of the `` content with the interactive WebAssembly render mode and prerendering disabled: ```razor + ``` Replace the following `div` tag with the `Routes` component using the interactive WebAssembly render mode and prerendering disabled: From 312addc0feb7b8b76c27ac5ffc181b6c17381461 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 13:00:25 -0400 Subject: [PATCH 17/20] Updates --- aspnetcore/migration/70-80.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 0d3592c3517b..f240b2cb4a41 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -274,7 +274,7 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th > [!IMPORTANT] > Using the preceding guidance, update the `Client`, `Server`, and `Shared` projects of the solution. -1. Move the file content from the `Client/wwwroot/index.html` file to a new `App` component file (`App.razor`) created at the root of the `Server` project. +1. Move the file content from the `Client/wwwroot/index.html` file to a new `App` component file (`App.razor`) created at the root of the `Server` project. After you move the file's contents, delete the `index.html` file. 1. Rename `App.razor` in the `Client` project to `Routes.razor`. From 390791cbef0a3332d14744e91c9c0e24641f2abf Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 19 Oct 2023 16:23:26 -0400 Subject: [PATCH 18/20] Update aspnetcore/migration/70-80.md Co-authored-by: Daniel Roth --- aspnetcore/migration/70-80.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index f240b2cb4a41..a247f32c681a 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -278,6 +278,8 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th 1. Rename `App.razor` in the `Client` project to `Routes.razor`. +1. In `Routes.razor`, update the value of the `AppAssembly` attribute to `typeof(Program).Assembly`. + 1. Add an entry to the `_Imports.razor` file to make shorthand render modes available to the app: ```razor From 8324de4cc1059ab200729901f23cb578dcf4b320 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Fri, 20 Oct 2023 07:14:14 -0400 Subject: [PATCH 19/20] Apply suggestions from code review Co-authored-by: Daniel Roth --- aspnetcore/blazor/components/integration.md | 4 ++-- aspnetcore/migration/70-80.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index 4c5b2b7766d1..d2bb99c5ee11 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -16,9 +16,9 @@ uid: blazor/components/integration --> -This article explains Razor component integration scenarios for ASP.NET Core apps, including prerendering of Razor components on the server. +This article explains Razor component integration scenarios for ASP.NET Core apps. -Razor components can be integrated into Razor Pages, MVC, and other types of ASP.NET Core apps with prerendering. Prerendering can improve [Search Engine Optimization (SEO)](https://developer.mozilla.org/docs/Glossary/SEO) by rendering content for the initial HTTP response that search engines can use to calculate page rank. +Razor components can be integrated into Razor Pages, MVC, and other types of ASP.NET Core apps. Razor components can also be integrated into any web app, including apps not based on ASP.NET Core, as [custom HTML elements](https://learn.microsoft.com/aspnet/core/blazor/components/js-spa-frameworks#blazor-custom-elements). Use the guidance in the following sections depending on the project's requirements: diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index a247f32c681a..091e52e4f287 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -349,7 +349,7 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th - app.UseBlazorFrameworkFiles(); ``` - Remove the following line and replace it with a call to `MapRazorComponents`, supplying the `App` component as the root component type, and add a chained call to `AddInteractiveWebAssemblyRenderMode`: + Remove the following line and replace it with a call to `MapRazorComponents`, supplying the `App` component as the root component type, and add chained calls to `AddInteractiveWebAssemblyRenderMode` and `AddAdditionalAssemblies`: ```diff - app.MapFallbackToFile("index.html"); @@ -357,8 +357,8 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th ```csharp app.MapRazorComponents() - .AddInteractiveWebAssemblyRenderMode(); - ``` + .AddInteractiveWebAssemblyRenderMode() + .AddAdditionalAssemblies(typeof(Counter).Assembly); 1. Run the solution from the `Server` project: From 20ae3176ee1c3c74088cf0ae6e2cac9da4230577 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 20 Oct 2023 07:22:28 -0400 Subject: [PATCH 20/20] Updates --- aspnetcore/blazor/components/integration.md | 10 +++++++--- aspnetcore/migration/70-80.md | 5 ++++- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index d2bb99c5ee11..8da12d79a4b4 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -18,14 +18,16 @@ uid: blazor/components/integration This article explains Razor component integration scenarios for ASP.NET Core apps. -Razor components can be integrated into Razor Pages, MVC, and other types of ASP.NET Core apps. Razor components can also be integrated into any web app, including apps not based on ASP.NET Core, as [custom HTML elements](https://learn.microsoft.com/aspnet/core/blazor/components/js-spa-frameworks#blazor-custom-elements). +Razor components can be integrated into Razor Pages, MVC, and other types of ASP.NET Core apps. Razor components can also be integrated into any web app, including apps not based on ASP.NET Core, as [custom HTML elements](xref:blazor/components/js-spa-frameworks#blazor-custom-elements). Use the guidance in the following sections depending on the project's requirements: -* Blazor support can be [added to an ASP.NET Core app](#add-blazor-support-to-an-aspnet-core-app). + * For interactive components that aren't directly routable from user requests, see the [Use non-routable components in pages or views](#use-non-routable-components-in-pages-or-views) section. Follow this guidance when the app embeds components into existing pages and views with the [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper). * For interactive components that are directly routable from user requests, see the [Use routable components](#use-routable-components) section. Follow this guidance when visitors should be able to make an HTTP request in their browser for a component with an [`@page`](xref:mvc/views/razor#page) directive. + +UPDATE 8.0 'Interactivity type' will change to 'Interactive render mode' at RTM 1. Create a donor Blazor Web App, which will provide assets to the app. Follow the guidance in the article, selecting support for the following template features when generating the Blazor Web App. @@ -222,6 +224,8 @@ This section covers adding Blazor support to an ASP.NET Core app. If you added the `Counter2` component, which is strictly configured for interactive server rendering, navigate to `/counter-2`. +--> + ## Use non-routable components in pages or views Use the following guidance to integrate Razor components into pages and views of an existing Razor Pages or MVC app with the [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper). diff --git a/aspnetcore/migration/70-80.md b/aspnetcore/migration/70-80.md index 091e52e4f287..c67f885aec3e 100644 --- a/aspnetcore/migration/70-80.md +++ b/aspnetcore/migration/70-80.md @@ -358,7 +358,10 @@ Blazor WebAssembly apps are supported in .NET 8 without any code changes. Use th ```csharp app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode() - .AddAdditionalAssemblies(typeof(Counter).Assembly); + .AddAdditionalAssemblies(typeof({CLIENT APP NAMESPACE}._Imports).Assembly); + ``` + + In the preceding example, the `{CLIENT APP NAMESPACE}` placeholder is the namespace of the `Client` project (for example, `HostedBlazorApp.Client`). Replace the placeholder with the `Client` project's namespace. 1. Run the solution from the `Server` project: