Skip to content
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

Blazor What's New and Migration guidance #27288

Merged
merged 12 commits into from
Oct 17, 2022
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions aspnetcore/migration/60-70.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Migrate from ASP.NET Core 6.0 to 7.0
author: rick-anderson
description: Learn how to migrate an ASP.NET Core 6 project to ASP.NET Core 7.0.
ms.author: riande
ms.date: 09/26/2022
ms.date: 10/14/2022
uid: migration/60-to-70
---
# Migrate from ASP.NET Core 6.0 to 7.0
Expand Down Expand Up @@ -71,15 +71,29 @@ In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/
</ItemGroup>
```

<!--
## Blazor

After following the guidance earlier in this article to update an app to 7.0, adopt specific features by following the links in <xref:aspnetcore-7.0#blazor>.
### Adopt .NET 7 features

After following the guidance earlier in this article to update an app to 7.0, adopt specific features by following the links in <xref:aspnetcore-7#blazor>.

To adopt all of the [new 6.0 features for Blazor apps](xref:aspnetcore-7.0#blazor), we recommend the following process:
To adopt all of the [new 7.0 features for Blazor apps](xref:aspnetcore-7#blazor), we recommend the following process:

* Create a new 7.0 Blazor project from one of the Blazor project templates. For more information, see <xref:blazor/tooling>.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's expensive 💰 ... describing every template change step-by-step? I did that once before. It took hours to write out.

* Move the app's components and code to the 7.0 app making modifications to adopt the new 7.0 features.

<!--

IN PROGRESS

Waiting for the PR to merge.

### Migrate unmarshalled JavaScript interop

Unmarshalled interop using the <xref:Microsoft.JSInterop.IJSUnmarshalledRuntime> interface is obsolete and should be replaced with .NET JavaScript `[JSImport]`/`[JSExport]` interop.

For more information, see <xref:blazor/js-interop/import-export-interop>.

-->

## Update Docker images
Expand Down
305 changes: 304 additions & 1 deletion aspnetcore/release-notes/aspnetcore-7.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ author: rick-anderson
description: Learn about the new features in ASP.NET Core 7.0.
ms.author: riande
ms.custom: mvc
ms.date: 08/19/2022
ms.date: 10/14/2022
uid: aspnetcore-7
---
# What's new in ASP.NET Core 7.0 preview
Expand Down Expand Up @@ -209,6 +209,309 @@ SignalR hub methods now support injecting services through dependency injection

Hub constructors can accept services from DI as parameters, which can be stored in properties on the class for use in a hub method. For more information, see [Inject services into a hub](xref:signalr/hubs?view=aspnetcore-7.0&preserve-view=true#inject-services-into-a-hub)

## Blazor

### Handle location changing events

In .NET 7, Blazor supports location changing events. This allows you to warn users about unsaved work or to perform related actions when the user performs a page navigation.

For more information, see the following sections of the *Routing and navigation* article:

* [Navigation options](xref:blazor/fundamentals/routing?view=aspnetcore-7.0#navigation-options)
* [Handle/prevent location changes](xref:blazor/fundamentals/routing?view=aspnetcore-7.0#handleprevent-location-changes)

### Calling `InvokeAsync(StateHasChanged)` causes page to fallback to the default culture
guardrex marked this conversation as resolved.
Show resolved Hide resolved

If a Razor component defines an event that's triggered from a background thread, the component might be required to capture and restore the execution context (`ExecutionContext`) at the time the handler is registered.
guardrex marked this conversation as resolved.
Show resolved Hide resolved

For more information, see the following resources:

* [Calling `InvokeAsync(StateHasChanged)` causes page to fallback to default culture (dotnet/aspnetcore #28521)](https://github.com/dotnet/aspnetcore/issues/28521)
* <xref:blazor/components/index?view=aspnetcore-7.0#invoke-component-methods-externally-to-update-state>

### Empty Blazor project templates

Blazor has two new project templates for starting from a blank slate. The new **Blazor Server App Empty** and **Blazor WebAssembly App Empty** project templates are just like their non-empty counterparts but without demonstration code. These empty templates only include a basic home page, and we've removed Bootstrap so that you can start with a different CSS framework.
guardrex marked this conversation as resolved.
Show resolved Hide resolved

For more information, see the following articles:

* <xref:blazor/tooling?view=aspnetcore-7.0>
* <xref:blazor/project-structure?view=aspnetcore-7.0>

### Blazor custom elements no longer experimental
guardrex marked this conversation as resolved.
Show resolved Hide resolved

The [`Microsoft.AspNetCore.Components.CustomElements`](https://www.nuget.org/packages/microsoft.aspnetcore.components.customelements) package for building [standards based custom elements](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements) is no longer experimental.
guardrex marked this conversation as resolved.
Show resolved Hide resolved
guardrex marked this conversation as resolved.
Show resolved Hide resolved

For more information, see <xref:blazor/components/index?view=aspnetcore-7.0#blazor-custom-elements>.

<!--

IN PROGRESS

### Improve prerendering and authentication experience in Blazor
guardrex marked this conversation as resolved.
Show resolved Hide resolved

[27592](https://github.com/dotnet/aspnetcore/issues/27592)

-->

### Bind get/set/after modifiers

New modifiers, `@bind:get`/`@bind:set`/`@bind:after`, allow you to customize how Blazor's `@bind` attribute directive reads and writes bound values.

<!--
guardrex marked this conversation as resolved.
Show resolved Hide resolved

NOTE

`@bind:get`/`@bind:set` are only covered in an example for binding across more than two components.
There isn't textual coverage outside of that section or dedicated examples for these.

-->

For more information, see the following content in the *Data binding* article:

* [`@bind:after="{EVENT}"` content](xref:blazor/components/data-binding?view=aspnetcore-7.0) at the end of the article's introductory guidance.
* The [Bind across more than two components](xref:blazor/components/data-binding?view=aspnetcore-7.0#bind-across-more-than-two-components) section demonstrates the use of `@bind:get`/`@bind:set` syntax.

Additional information:
guardrex marked this conversation as resolved.
Show resolved Hide resolved

* [Design proposal: Bind get/set/after modifiers (dotnet/aspnetcore #39837)](https://github.com/dotnet/aspnetcore/issues/39837)
* [Support `@bind:get`, `@bind:set`, `@bind:after` (dotnet/razor-compiler #70)](https://github.com/dotnet/razor-compiler/pull/70)

> [!WARNING]
> Final design changes prior to the general release might not be reflected in the initial design described by the product unit's GitHub issue and pull request. For the latest information on this feature, see the preceding cross-links to the official Blazor documentation.

<!--

IN PROGRESS

### Enable integration with third-party assets management solutions
guardrex marked this conversation as resolved.
Show resolved Hide resolved

[38445](https://github.com/dotnet/aspnetcore/issues/38445)

-->

<!--

HOLD

This is a tooling update for what Steve says is a rare situation.
No doc updates were made to cover this, but we could include something here on it.
The following is a bit draft content for it.

### Components don't reset their received parameters during Hot Reload updates
guardrex marked this conversation as resolved.
Show resolved Hide resolved

When using Hot Reload and removing a parameter value that's passed to a child component, the prior Hot Reload refresh mechanism didn't account for the change.

Example:

For the default project template under .NET 6 using Hot Reload, change the `SurveyPrompt` component's `Title` parameter value in the `Index` component:

```diff
- <SurveyPrompt Title="How is Blazor working for you?" />
+ <SurveyPrompt />
```

The change isn't reflected in the UI. This is because the existing `SurveyPrompt` instance already has a value for its `Title` property. The prior value isn't overwritten.

In .NET 7, `SetParametersAsync` determines if a Hot Reload refresh is in progress. If a refresh occurs, `[Parameter]` properties are reset to their default values before receiving the new set of values from the component's parent.

-->

### Dynamic authentication requests with MSAL in Blazor WebAssembly

New in .NET 7, Blazor WebAssembly supports creating dynamic authentication requests at runtime with custom parameters to handle advanced authentication scenarios.

For more information, see the following articles:

* <xref:blazor/security/webassembly/index?view=aspnetcore-7.0#customize-authentication>
* <xref:blazor/security/webassembly/additional-scenarios?view=aspnetcore-7.0#custom-authentication-request-scenarios>

### Blazor WebAssembly debugging improvements

Blazor WebAssembly debugging has the following improvements:

* Support for the **Just My Code** setting to show or hide type members that aren't from user code.
* Support for inspecting multidimensional arrays.
* **Call Stack** now shows the correct name for asynchronous methods.
* Improved expression evaluation.
* Correct handling of the `new` keyword on derived members.
* Support for debugger-related attributes in `System.Diagnostics`.

### `System.Security.Cryptography` support on WebAssembly

.NET 6 supported the SHA family of hashing algorithms when running on WebAssembly. .NET 7 enables more cryptographic algorithms by taking advantage of [:::no-loc text="SubtleCrypto":::](https://developer.mozilla.org/docs/Web/API/SubtleCrypto), when possible, and falling back to a .NET implementation when :::no-loc text="SubtleCrypto"::: can't be used. The following algorithms are supported on WebAssembly in .NET 7:

* SHA1
* SHA256
* SHA384
* SHA512
* HMACSHA1
* HMACSHA256
* HMACSHA384
* HMACSHA512
* AES-CBC
* PBKDF2
* HKDF

For more information, see [Developers targeting browser-wasm can use Web Crypto APIs (dotnet/runtime #40074)](https://github.com/dotnet/runtime/issues/40074).

<!--

HOLD

🪲 fix ... not addressed in docs

### Generic Blazor component can't correctly infer it's type when type has an additional constraint
guardrex marked this conversation as resolved.
Show resolved Hide resolved

https://github.com/dotnet/aspnetcore/issues/25588

-->

<!--

HOLD

🪲 fix ... not addressed in docs

### `CascadingTypeParameter` problem
guardrex marked this conversation as resolved.
Show resolved Hide resolved

https://github.com/dotnet/aspnetcore/issues/38479

-->

### Inject services into custom validation attributes

You can now inject services into custom validation attributes. Blazor sets up the `ValidationContext` so that it can be used as a service provider.

For more information, see <xref:blazor/forms-and-input-components?view=aspnetcore-7.0#custom-validation-attributes>.

### Blazor WebAssembly's default browser for debugging adopts Microsoft Edge
guardrex marked this conversation as resolved.
Show resolved Hide resolved

In release versions prior to .NET 7, the default browser for debugging is Google Chrome. In .NET 7, the default browser for debugging is Microsoft Edge.

### `Input*` components outside of an `EditContext`/`EditForm`

The built-in input components are now supported outside of a form in Razor component markup.

For more information, see <xref:blazor/forms-and-input-components?view=aspnetcore-7.0#built-in-input-components>.

### Project template changes

When .NET 6 was released last year, the HTML markup of the `_Host` page (`Pages/_Host.chstml`) was split between the `_Host` page and a new `_Layout` page (`Pages/_Layout.chstml`) in the .NET 6 Blazor Server project template.

In .NET 7, the HTML markup has been recombined with the `_Host` page in project templates.

Several additional changes were made to the Blazor project templates. It isn't feasible to list every change to the templates in the documentation. To migrate an app to .NET 7 in order to adopt all of the changes, see <xref:migration/60-to-70#blazor>.
guardrex marked this conversation as resolved.
Show resolved Hide resolved

### Experimental `QuickGrid` component

The new `QuickGrid` component provides a convenient data grid component for most common requirements and as a reference architecture and performance baseline for anyone building Blazor data grid components.

For more information, see <xref:blazor/components/index?view=aspnetcore-7.0#quickgrid-component>.

Live demo: [QuickGrid for Blazor sample app](https://aspnet.github.io/quickgridsamples/)

<!--

HOLD

It looks like this is an impl detail that only pertains to browser nav history state.

### `NavigationManager` supports state
guardrex marked this conversation as resolved.
Show resolved Hide resolved

https://github.com/dotnet/aspnetcore/pull/42534

-->

### Virtualization enhancements

Virtualization enhancements in .NET 7:

* The `Virtualize` component supports using the document itself as the scroll root, as an alternative to having some other element with `overflow-y: scroll` applied.
* If the `Virtualize` component is placed inside an element that requires a specific child tag name, `SpacerElement` allows you to obtain or set the virtualization spacer tag name.

For more information, see the following sections of the *Virtualization* article:

* [Root-level virtualization](xref:blazor/components/virtualization?view=aspnetcore-7.0#root-level-virtualization)
* [Control the spacer element tag name](xref:blazor/components/virtualization?view=aspnetcore-7.0#control-the-spacer-element-tag-name)

<!--

HOLD

This is covered via the existing ref source link in the article.
I don't think we need to remark on it in the article, but you may wish to say something here.
I'll float some draft language.

### `MouseEventArgs` updates
guardrex marked this conversation as resolved.
Show resolved Hide resolved

`MovementX` and `MovementY` have been added to `MouseEventArgs`.

For more information, see <xref:blazor/components/event-handling?view=aspnetcore-7.0#built-in-event-arguments>.

-->

### New Blazor loading page

The Blazor WebAssembly project template has a new loading UI that shows the progress of loading the app.

For more information, see <xref:blazor/fundamentals/startup?view=aspnetcore-7.0#loading-progress-indicators>.

### Improved diagnostics for authentication in Blazor WebAssembly

To help diagnose authentication issues in Blazor WebAssembly apps, detailed logging is available.

For more information, see <xref:blazor/fundamentals/logging?view=aspnetcore-7.0#blazor-webassembly-authentication-logging>.

<!--

IN PROGRESS

### .NET JavaScript interop on WebAssembly

.NET JavaScript `[JSImport]`/`[JSExport]` interop API is a new low-level mechanism for using .NET in Blazor WebAssembly and JavaScript-based apps. With this new JavaScript interop capability, you can invoke .NET code from JavaScript using the .NET WebAssembly runtime and call into JavaScript functionality from .NET without any dependency on the Blazor UI component model.

For more information, see the following articles:

* <xref:blazor/js-interop/import-export-interop>: Pertains only to Blazor WebAssebmly apps.
* <xref:client-side/import-export-interop>: Pertains only to JavaScript apps that don't depend on the Blazor UI component model.

Under consideration for docs ...

[Blog Post (WebAssembly multithreading experimental)](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-7-rc-2/#webassembly-multithreading-experimental)

-->

### Conditional registration of the authentication state provider

Prior to the release of .NET 7, `AuthenticationStateProvider` was registered in the service container with `AddScoped`. This made it difficult to debug apps, as it forced a specific order of service registrations when providing a custom implementation. Due to internal framework changes over time, it's no longer necessary to register `AuthenticationStateProvider` with `AddScoped`:

```diff
guardrex marked this conversation as resolved.
Show resolved Hide resolved
- builder.Services.AddScoped<AuthenticationStateProvider, ExternalAuthStateProvider>();
+ builder.Services.TryAddScoped<AuthenticationStateProvider, ExternalAuthStateProvider>();
```

### .NET WebAssembly build tools for .NET 6 projects
guardrex marked this conversation as resolved.
Show resolved Hide resolved
guardrex marked this conversation as resolved.
Show resolved Hide resolved

You can now use the .NET WebAssembly build tools with a .NET 6 project when working with the .NET 7 SDK. The new `wasm-tools-net6` workload includes the .NET WebAssembly build tools for .NET 6 projects so that they can be used with the .NET 7 SDK. The existing `wasm-tools` workload installs the .NET WebAssembly build tools for .NET 7 projects. However, the .NET 7 version of the .NET WebAssembly build tools are incompatible with existing projects built with .NET 6. Projects using the .NET WebAssembly build tools that need to support both .NET 6 and .NET 7 must use multi-targeting.

For more information, see <xref:blazor/tooling?view=aspnetcore-7.0#net-webassembly-build-tools>.

## Blazor Hybrid

### External URLs

An option has been added that permits opening external webpages in the browser.

For more information, see <xref:blazor/hybrid/routing?view=aspnetcore-7.0#external-navigation>.

### Security

New guidance is available for Blazor Hybrid security scenarios. For more information, see the following articles:

* <xref:blazor/hybrid/security/index?view=aspnetcore-7.0>
* <xref:blazor/hybrid/security/security-considerations?view=aspnetcore-7.0>

## Performance

### HTTP/2 Performance improvements
Expand Down