-
Notifications
You must be signed in to change notification settings - Fork 25k
[11.0 P1] Blazor release notes and initial migration guidance #36449
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
guardrex
wants to merge
10
commits into
main
Choose a base branch
from
guardrex/blazor-release-notes-p1
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+218
−1
Open
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
ba51309
[11.0 P1] Blazor release notes
guardrex 1681f1a
Updates
guardrex 6a7fa20
Updates
guardrex f4209b3
Add BasePath component coverage
guardrex 18c8f5b
Inline JS removal and add Migration guidance
guardrex ee4fb2c
Updates
guardrex 5171ef5
Updates
guardrex c327766
Updates
guardrex 7debfd5
Update aspnetcore/release-notes/aspnetcore-11/includes/blazor.md
guardrex b764bf0
Update aspnetcore/migration/100-to-110.md
guardrex File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| * [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the **ASP.NET and web development** workload. | ||
|
|
||
|  |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| * [Visual Studio Code](https://code.visualstudio.com/download) | ||
| * [C# Dev Kit for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) | ||
| * [!INCLUDE [](~/includes/0-latest-SDK.md)] | ||
|
|
||
| You can follow the Visual Studio Code instructions on macOS, Linux, or Windows. Changes may be required if you use an integrated development environment (IDE) other than Visual Studio Code. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| --- | ||
| title: Migrate from ASP.NET Core in .NET 10 to ASP.NET Core in .NET 11 | ||
| author: wadepickett | ||
| description: Learn how to migrate an ASP.NET Core in .NET 10 to ASP.NET Core in .NET 11. | ||
| ms.author: wpickett | ||
| ms.date: 01/26/2026 | ||
| uid: migration/100-to-110 | ||
| --- | ||
| # Migrate from ASP.NET Core in .NET 10 to ASP.NET Core in .NET 11 | ||
|
|
||
| <!-- New content should be added to the includes files in the '100-to-110' folder. This will help prevent merge conflicts in this file. --> | ||
|
|
||
| This article explains how to update an ASP.NET Core in .NET 10 to ASP.NET Core in .NET 10. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| # [Visual Studio](#tab/visual-studio) | ||
|
|
||
| [!INCLUDE[](~/includes/net-prereqs-vs-11-latest.md)] | ||
|
|
||
| # [Visual Studio Code](#tab/visual-studio-code) | ||
|
|
||
| [!INCLUDE[](~/includes/net-prereqs-vsc-11.0.md)] | ||
|
|
||
| --- | ||
|
|
||
| ## 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 SDK version, update the `version` property to the .NET 11 SDK version that's installed. For example: | ||
|
|
||
| ```diff | ||
| { | ||
| "sdk": { | ||
| - "version": "10.0.102" | ||
| + "version": "11.0.100" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Update the target framework | ||
|
|
||
| Update the project file's [Target Framework Moniker (TFM)](/dotnet/standard/frameworks) to `net11.0`: | ||
|
|
||
| ```diff | ||
| <Project Sdk="Microsoft.NET.Sdk.Web"> | ||
|
|
||
| <PropertyGroup> | ||
| - <TargetFramework>net10.0</TargetFramework> | ||
| + <TargetFramework>net11.0</TargetFramework> | ||
| </PropertyGroup> | ||
|
|
||
| </Project> | ||
| ``` | ||
|
|
||
| ## 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 11.0.0 or later. For example: | ||
|
|
||
| ```diff | ||
| <ItemGroup> | ||
| - <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="10.0.0" /> | ||
| - <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.0" /> | ||
| - <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.0" /> | ||
| - <PackageReference Include="System.Net.Http.Json" Version="10.0.0" /> | ||
| + <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="11.0.0" /> | ||
| + <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="11.0.0" /> | ||
| + <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="11.0.0" /> | ||
| + <PackageReference Include="System.Net.Http.Json" Version="11.0.0" /> | ||
| </ItemGroup> | ||
| ``` | ||
|
|
||
| ## Blazor | ||
|
|
||
| [!INCLUDE[](~/migration/100-to-110/includes/blazor.md)] | ||
|
|
||
| ## Breaking changes | ||
|
|
||
| Use the articles in [Breaking changes in .NET](/dotnet/core/compatibility/breaking-changes) to find breaking changes that might apply when upgrading an app to a newer version of .NET. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| ### Blazor release notes | ||
|
|
||
| For new feature coverage, see <xref:aspnetcore-11>. | ||
|
|
||
| ### Adopt Inline JS event handler removed from the `NavMenu` component | ||
|
|
||
| *This section only applies to Blazor Web Apps.* | ||
|
|
||
| The inline JS event handler for the navigation bar toggler isn't present in the `NavMenu` component of the Blazor Web App project template in .NET 11 or later. Apps generated from the project template use a [collocated JS module](xref:blazor/js-interop/javascript-location#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component) approach to show or hide the navigation links on the rendered page. The approach improves [Content Security Policy (CSP) compliance](xref:blazor/security/content-security-policy) because it doesn't require the CSP to include an unsafe hash for the inline JS. | ||
|
|
||
| Use the following instructions to adopt the new JS module approach for the navigation links toggler in an existing app. | ||
|
|
||
| Add a [collocated JS module](xref:blazor/js-interop/javascript-location#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component) next to the app's `NavMenu` component. | ||
|
|
||
| `NavMenu.razor.js`: | ||
|
|
||
| ```javascript | ||
| // Handle navigation menu toggle | ||
| const navScrollable = document.getElementById("nav-scrollable"); | ||
| const navToggler = document.querySelector(".navbar-toggler"); | ||
|
|
||
| if (navScrollable && navToggler) { | ||
| navScrollable.addEventListener("click", function() { | ||
| navToggler.click(); | ||
| }); | ||
| } | ||
| ``` | ||
|
|
||
| At the top of the app's `NavMenu` component (`NavMenu.razor`), add a `<script>` tag for the collocated JS module: | ||
|
|
||
| * If the app adopts client-side rendering (has a `.Client` project) with global interactivity (the render mode is set globally for the app by the app's `App` component), use the following tag, which indicates the path to the module in the `Layout` folder: | ||
|
|
||
| ```razor | ||
| <script type="module" src="@Assets["Layout/NavMenu.razor.js"]"></script> | ||
| ``` | ||
|
|
||
| * Otherwise, use the following tag, which indicates the path to the module in the `Components/Layout` folder: | ||
|
|
||
| ```razor | ||
| <script type="module" src="@Assets["Components/Layout/NavMenu.razor.js"]"></script> | ||
| ``` | ||
|
|
||
| Also in the app's `NavMenu` component, change the line that has the inline JS to toggle the navigation links: | ||
|
|
||
| ```diff | ||
| - <div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()"> | ||
| + <div id="nav-scrollable" class="nav-scrollable"> | ||
| ``` | ||
|
|
||
| If the app has a [Content Security Policy (CSP)](xref:blazor/security/content-security-policy#server-side-blazor-apps) with an unsafe hash for the inline JS removed by the preceding step, remove the unsafe hash: | ||
|
|
||
| ```diff | ||
| - 'unsafe-hashes' 'sha256-qnHnQs7NjQNHHNYv/I9cW+I62HzDJjbnyS/OFzqlix0=' | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,78 @@ | ||
| *Release notes appear in this section as preview features become available.* | ||
| ### New `DisplayName` component and support for `[Display]` and `[DisplayName]` attributes | ||
|
|
||
| <!-- UPDATE 11.0 - API cross-link | ||
|
|
||
| <xref:Microsoft.AspNetCore.Components.Forms.DisplayName%601> | ||
| --> | ||
| The `DisplayName` component can be used to display property names from metadata attributes: | ||
|
|
||
| ```csharp | ||
| [Required, DisplayName("Production Date")] | ||
| public DateTime ProductionDate { get; set; } | ||
| ``` | ||
|
|
||
| The [`[Display]` attribute](xref:System.ComponentModel.DataAnnotations.DisplayAttribute) on the model class property is supported: | ||
|
|
||
| ```csharp | ||
| [Required, Display(Name = "Production Date")] | ||
| public DateTime ProductionDate { get; set; } | ||
| ``` | ||
|
|
||
| Of the two approaches, the `[Display]` attribute is recommended, which makes additional properties available. The `[Display]` attribute also enables assigning a resource type for localization. When both attributes are present, `[Display]` takes precedence over `[DisplayName]`. If neither attribute is present, the component falls back to the property name. | ||
|
|
||
| Use the `DisplayName` component in labels or table headers: | ||
|
|
||
| ```razor | ||
| <label> | ||
| <DisplayName For="@(() => Model!.ProductionDate)" /> | ||
| <InputDate @bind-Value="Model!.ProductionDate" /> | ||
| </label> | ||
| ``` | ||
|
|
||
| ### Blazor Web script startup options format now supported for Blazor Server and Blazor WebAssembly scripts | ||
|
|
||
| The Blazor Web App script (`blazor.web.js`) options object passed to `Blazor.start()` uses the following format since the release of .NET 8: | ||
|
|
||
| ```javascript | ||
| Blazor.start({ | ||
| ssr: { ... }, | ||
| circuit: { ... }, | ||
| webAssembly: { ... }, | ||
| }); | ||
| ``` | ||
|
|
||
| Now, Blazor Server (`blazor.server.js`) and Blazor WebAssembly (`blazor.webassembly.js`) scripts can use the same options format. | ||
|
|
||
| The following example shows the prior options format, which remains supported: | ||
|
|
||
| ```javascript | ||
| Blazor.start({ | ||
| loadBootResource: function (...) { | ||
| ... | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| The newly supported options format for the preceding example: | ||
|
|
||
| ```javascript | ||
| Blazor.start({ | ||
| webAssembly: { | ||
| loadBootResource: function (...) { | ||
| ... | ||
| }, | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| For more information, see <xref:blazor/fundamentals/startup#startup-process-and-configuration>. | ||
|
|
||
| ### New `BasePath` component | ||
|
|
||
| Blazor Web Apps can use the new `BasePath` component (`<BasePath />`) to render the app's app base path (`<base href>`) HTML tag automatically. For more information, see <xref:blazor/host-and-deploy/app-base-path>. | ||
|
|
||
| ### Inline JS event handler removed from the `NavMenu` component | ||
|
|
||
| The inline JS event handler that toggles the display of navigation links is no longer present in the `NavMenu` component of the Blazor Web App project template. Apps generated from the project template now use a [collocated JS module](xref:blazor/js-interop/javascript-location#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component) approach to show or hide the navigation bar on the rendered page. The new approach improves [Content Security Policy (CSP) compliance](xref:blazor/security/content-security-policy) because it doesn't require the CSP to include an unsafe hash for the inline JS. | ||
|
|
||
| To migrate an existing app to .NET 11, including adopting the new JS module approach for the navigation bar toggler, see <xref:migration/100-to-110>. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should there be an blank line on the end since this is an include?
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, there should be a newline at the end of every last content line for every file in GH ... thus a blank line showing at the end of every file.