From f2597408f269a4b292f5b7c5e85d3dab50060813 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Wed, 10 Nov 2021 03:51:51 -0600 Subject: [PATCH] Blazor API and What's New updates --- .../blazor/components/built-in-components.md | 3 +++ .../blazor/components/control-head-content.md | 8 ++++---- .../blazor/components/dynamiccomponent.md | 10 +++++----- aspnetcore/blazor/components/index.md | 4 ++-- aspnetcore/blazor/components/lifecycle.md | 12 +++++------ .../prerendering-and-integration.md | 8 ++++---- .../blazor/components/templated-components.md | 4 ++-- .../blazor/fundamentals/handle-errors.md | 8 ++++---- aspnetcore/blazor/fundamentals/routing.md | 20 +++++++++---------- .../webassembly-deployment-layout.md | 2 +- .../blazor/host-and-deploy/webassembly.md | 12 +++++------ .../built-in/persist-component-state.md | 19 ++++++------------ aspnetcore/release-notes/aspnetcore-6.0.md | 9 ++++++++- 13 files changed, 61 insertions(+), 58 deletions(-) diff --git a/aspnetcore/blazor/components/built-in-components.md b/aspnetcore/blazor/components/built-in-components.md index 5d1715e880c4..e52a851027a2 100644 --- a/aspnetcore/blazor/components/built-in-components.md +++ b/aspnetcore/blazor/components/built-in-components.md @@ -22,6 +22,8 @@ The following built-in Razor components are provided by the Blazor framework: * [`DynamicComponent`](xref:blazor/components/dynamiccomponent) * [`ErrorBoundary`](xref:blazor/fundamentals/handle-errors#error-boundaries) * [`FocusOnNavigate`](xref:blazor/fundamentals/routing#focus-an-element-on-navigation) +* [`HeadContent`](xref:blazor/components/control-head-content) +* [`HeadOutlet`](xref:blazor/components/control-head-content) * [`InputCheckbox`](xref:blazor/forms-validation#built-in-form-components) * [`InputDate`](xref:blazor/forms-validation#built-in-form-components) * [`InputFile`](xref:blazor/file-uploads) @@ -35,6 +37,7 @@ The following built-in Razor components are provided by the Blazor framework: * [`MainLayout`](xref:blazor/components/layouts#mainlayout-component) * [`NavLink`](xref:blazor/fundamentals/routing#navlink-and-navmenu-components) * [`NavMenu`](xref:blazor/fundamentals/routing#navlink-and-navmenu-components) +* [`PageTitle`](xref:blazor/components/control-head-content) * [`Router`](xref:blazor/fundamentals/routing#route-templates) * [`Virtualize`](xref:blazor/components/virtualization) diff --git a/aspnetcore/blazor/components/control-head-content.md b/aspnetcore/blazor/components/control-head-content.md index 7baf227bff85..b0a2fa87c617 100644 --- a/aspnetcore/blazor/components/control-head-content.md +++ b/aspnetcore/blazor/components/control-head-content.md @@ -15,7 +15,7 @@ Razor components can modify the HTML `` element content of a page, includi ## Control `` content in a Razor component -Specify the page's title with the `PageTitle` component. Specify `` element content with the `HeadContent` component. The following example sets the page's title and description using Razor. +Specify the page's title with the component. Specify `` element content with the component. The following example sets the page's title and description using Razor. `Pages/ControlHeadContent.razor`: @@ -46,9 +46,9 @@ Specify the page's title with the `PageTitle` component. Specify `` elemen ## `HeadOutlet` component -The `HeadOutlet` component renders content provided by `HeadContent` components. +The component renders content provided by components. -In an app created from the Blazor WebAssembly project template, the `HeadOutlet` component is added to the collection of the in `Program.cs`: +In an app created from the Blazor WebAssembly project template, the component is added to the collection of the in `Program.cs`: ```csharp builder.RootComponents.Add("head::after"); @@ -56,7 +56,7 @@ builder.RootComponents.Add("head::after"); When the [`::after` pseudo-selector](https://developer.mozilla.org/docs/Web/CSS/::after) is specified, the contents of the root component are appended to the existing head contents instead of replacing the content. This allows the app to retain static head content in `wwwroot/index.html` without having to repeat the content in the app's Razor components. -In Blazor Server apps created from the Blazor Server project template, a [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper) renders `` content for the `HeadOutlet` component in `Pages/_Layout.cshtml`: +In Blazor Server apps created from the Blazor Server project template, a [Component Tag Helper](xref:mvc/views/tag-helpers/builtin-th/component-tag-helper) renders `` content for the component in `Pages/_Layout.cshtml`: ```cshtml diff --git a/aspnetcore/blazor/components/dynamiccomponent.md b/aspnetcore/blazor/components/dynamiccomponent.md index 0aeb29b52a34..d2f7e70a277a 100644 --- a/aspnetcore/blazor/components/dynamiccomponent.md +++ b/aspnetcore/blazor/components/dynamiccomponent.md @@ -13,9 +13,9 @@ uid: blazor/components/dynamiccomponent By [Dave Brock](https://twitter.com/daveabrock) -Use the built-in `DynamicComponent` component to render components by type. +Use the built-in component to render components by type. -A `DynamicComponent` is useful for rendering components without iterating through possible types or using conditional logic. For example, `DynamicComponent` can render a component based on a user selection from a dropdown list. +A is useful for rendering components without iterating through possible types or using conditional logic. For example, can render a component based on a user selection from a dropdown list. In the following example: @@ -33,7 +33,7 @@ In the following example: For more information on passing parameter values, see the [Pass parameters](#pass-parameters) section later in this article. -Use the `Instance` property to access the dynamically-created component instance: +Use the property to access the dynamically-created component instance: ```razor @@ -155,7 +155,7 @@ In the preceding example: ## Pass parameters -If dynamically-rendered components have [component parameters](xref:blazor/components/index#component-parameters), pass them into the `DynamicComponent` as an `IDictionary`. The `string` is the name of the parameter, and the `object` is the parameter's value. +If dynamically-rendered components have [component parameters](xref:blazor/components/index#component-parameters), pass them into the as an `IDictionary`. The `string` is the name of the parameter, and the `object` is the parameter's value. The following example configures a component metadata object (`ComponentMetadata`) to supply parameter values to dynamically-rendered components based on the type name. The example is just one of several approaches that you can adopt. Parameter data can also be provided from a web API, a database, or a method. The only requirement is that the approach returns an `IDictionary`. @@ -289,7 +289,7 @@ The `RocketLab` component (`Shared/RocketLab.razor`) includes a component parame ## Avoid catch-all parameters -Avoid the use of [catch-all parameters](xref:blazor/fundamentals/routing#catch-all-route-parameters). If catch-all parameters are used, every explicit parameter on `DynamicComponent` effectively is a reserved word that you can't pass to a dynamic child. Any new parameters passed to `DynamicComponent` are a breaking change, as they start shadowing child component parameters that happen to have the same name. It's unlikely that the caller always knows a fixed set of parameter names to pass to all possible dynamic children. +Avoid the use of [catch-all parameters](xref:blazor/fundamentals/routing#catch-all-route-parameters). If catch-all parameters are used, every explicit parameter on effectively is a reserved word that you can't pass to a dynamic child. Any new parameters passed to are a breaking change, as they start shadowing child component parameters that happen to have the same name. It's unlikely that the caller always knows a fixed set of parameter names to pass to all possible dynamic children. ## Trademarks diff --git a/aspnetcore/blazor/components/index.md b/aspnetcore/blazor/components/index.md index 855029ad4918..0ebf0415183e 100644 --- a/aspnetcore/blazor/components/index.md +++ b/aspnetcore/blazor/components/index.md @@ -375,7 +375,7 @@ public DateTime StartData { get; set; } = DateTime.Now; After the initial assignment of , do **not** assign a value to `StartData` in developer code. For more information, see the [Overwritten parameters](#overwritten-parameters) section of this article. -Apply the `[EditorRequired]` attribute to specify a required component parameter. If a parameter value isn't provided, editors or build tools may display warnings to the user. This attribute is only valid on properties also marked with the `[Parameter]` attribute. The `[EditorRequired]` attribute is enforced at design-time and when the app is built. The attribute isn't enforced at runtime, and it doesn't guarantee a non-`null` parameter value. +Apply the [`[EditorRequired]` attribute](xref:Microsoft.AspNetCore.Components.EditorRequiredAttribute) to specify a required component parameter. If a parameter value isn't provided, editors or build tools may display warnings to the user. This attribute is only valid on properties also marked with the [`[Parameter]` attribute](xref:Microsoft.AspNetCore.Components.ParameterAttribute). The is enforced at design-time and when the app is built. The attribute isn't enforced at runtime, and it doesn't guarantee a non-`null` parameter value. ```csharp [Parameter] @@ -1039,7 +1039,7 @@ To render a Razor component from JS, register the component as a root component > [!NOTE] > The preceding code example requires a namespace for the app's components (for example, `using BlazorSample.Pages;`) in the `Program.cs` file. -* In a Blazor WebAssembly app, call `RegisterForJavaScript` on in `Program.cs`: +* In a Blazor WebAssembly app, call on in `Program.cs`: ```csharp builder.RootComponents.RegisterForJavaScript(identifier: "counter"); diff --git a/aspnetcore/blazor/components/lifecycle.md b/aspnetcore/blazor/components/lifecycle.md index d1bd48a8d570..bf06b230aa9e 100644 --- a/aspnetcore/blazor/components/lifecycle.md +++ b/aspnetcore/blazor/components/lifecycle.md @@ -95,7 +95,7 @@ Blazor apps that prerender their content on the server call from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +To prevent developer code in from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . While a Blazor app is prerendering, certain actions, such as calling into JavaScript (JS interop), aren't possible. Components may need to render differently when prerendered. For more information, see the [Detect when the app is prerendering](#detect-when-the-app-is-prerendering) section. @@ -208,7 +208,7 @@ The following code demonstrates an updated `WeatherForecastService` in a templat For more information on the , see . -Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . ## Detect when the app is prerendering @@ -536,7 +536,7 @@ Blazor apps that prerender their content on the server call from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +To prevent developer code in from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . While a Blazor app is prerendering, certain actions, such as calling into JavaScript (JS interop), aren't possible. Components may need to render differently when prerendered. For more information, see the [Detect when the app is prerendering](#detect-when-the-app-is-prerendering) section. @@ -649,7 +649,7 @@ The following code demonstrates an updated `WeatherForecastService` in a templat For more information on the , see . -Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . ## Detect when the app is prerendering @@ -977,7 +977,7 @@ Blazor apps that prerender their content on the server call from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +To prevent developer code in from running twice when prerendering, see the [Stateful reconnection after prerendering](#stateful-reconnection-after-prerendering) section. Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . While a Blazor app is prerendering, certain actions, such as calling into JavaScript (JS interop), aren't possible. Components may need to render differently when prerendered. For more information, see the [Detect when the app is prerendering](#detect-when-the-app-is-prerendering) section. @@ -1087,7 +1087,7 @@ The following code demonstrates an updated `WeatherForecastService` in a templat For more information on the , see . -Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . +Although the content in this section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . ## Detect when the app is prerendering diff --git a/aspnetcore/blazor/components/prerendering-and-integration.md b/aspnetcore/blazor/components/prerendering-and-integration.md index acc8ed024aa4..f6199414da14 100644 --- a/aspnetcore/blazor/components/prerendering-and-integration.md +++ b/aspnetcore/blazor/components/prerendering-and-integration.md @@ -734,7 +734,7 @@ For more information, see . Without persisting prerendered state, state used during prerendering is lost and must be recreated when the app is fully loaded. If any state is setup asynchronously, the UI may flicker as the prerendered UI is replaced with temporary placeholders and then fully rendered again. -To solve these problems, Blazor supports persisting state in a prerendered page using the [Persist Component State Tag Helper](xref:mvc/views/tag-helpers/builtin-th/persist-component-state-tag-helper) (``). Add the `` tag inside the closing `` tag. +To solve these problems, Blazor supports persisting state in a prerendered page using the [Persist Component State Tag Helper](xref:mvc/views/tag-helpers/builtin-th/persist-component-state-tag-helper). Add the Tag Helper's tag, ``, inside the closing `` tag. `Pages/_Layout.cshtml`: @@ -746,7 +746,7 @@ To solve these problems, Blazor supports persisting state in a prerendered page ``` -In the app, decide what state to persist using the `PersistentComponentState` service. The `PersistentComponentState.RegisterOnPersisting` event is fired just before the state is persisted into the prerendered page, which allows a component to retrieve the state when initializing the component. +In the app, decide what state to persist using the service. The [`PersistentComponentState.RegisterOnPersisting`](xref:Microsoft.AspNetCore.Components.PersistentComponentState.RegisterOnPersisting%2A) event is fired just before the state is persisted into the prerendered page, which allows a component to retrieve the state when initializing the component. The following example shows how the weather forecast in the `FetchData` component from a hosted Blazor WebAssembly app based on the Blazor project template is persisted during prerendering and then retrieved to initialize the component. The Persist Component State Tag Helper persists the component state after all component invocations. @@ -836,7 +836,7 @@ By initializing components with the same state used during prerendering, any exp * Razor component lifecycle subjects that pertain to prerendering * [Component initialization (`OnInitialized{Async}`)](xref:blazor/components/lifecycle#component-initialization-oninitializedasync) * [After component render (`OnAfterRender{Async}`)](xref:blazor/components/lifecycle#after-component-render-onafterrenderasync) - * [Stateful reconnection after prerendering](xref:blazor/components/lifecycle#stateful-reconnection-after-prerendering): Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . + * [Stateful reconnection after prerendering](xref:blazor/components/lifecycle#stateful-reconnection-after-prerendering): Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . * [Detect when the app is prerendering](xref:blazor/components/lifecycle#detect-when-the-app-is-prerendering) * Authentication and authorization subjects that pertain to prerendering * [General aspects](xref:blazor/security/index#aspnet-core-blazor-authentication-and-authorization) @@ -1517,7 +1517,7 @@ For more information, see . * Razor component lifecycle subjects that pertain to prerendering * [Component initialization (`OnInitialized{Async}`)](xref:blazor/components/lifecycle#component-initialization-oninitializedasync) * [After component render (`OnAfterRender{Async}`)](xref:blazor/components/lifecycle#after-component-render-onafterrenderasync) - * [Stateful reconnection after prerendering](xref:blazor/components/lifecycle#stateful-reconnection-after-prerendering): Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . + * [Stateful reconnection after prerendering](xref:blazor/components/lifecycle#stateful-reconnection-after-prerendering): Although the content in the section focuses on Blazor Server and stateful SignalR *reconnection*, the scenario for prerendering in hosted Blazor WebAssembly apps () involves similar conditions and approaches to prevent executing developer code twice. To preserve state during the execution of initialization code while prerendering, see . * [Detect when the app is prerendering](xref:blazor/components/lifecycle#detect-when-the-app-is-prerendering) * Authentication and authorization subjects that pertain to prerendering * [General aspects](xref:blazor/security/index#aspnet-core-blazor-authentication-and-authorization) diff --git a/aspnetcore/blazor/components/templated-components.md b/aspnetcore/blazor/components/templated-components.md index b11d543d93fb..572f0e9927f1 100644 --- a/aspnetcore/blazor/components/templated-components.md +++ b/aspnetcore/blazor/components/templated-components.md @@ -54,7 +54,7 @@ When using generic-typed components, the type parameter is inferred if possible. ## Infer generic types based on ancestor components -An ancestor component can cascade a type parameter by name to descendants using the `CascadingTypeParameter` attribute. This attribute allows a generic type inference to use the specified type parameter automatically with descendants that have a type parameter with the same name. +An ancestor component can cascade a type parameter by name to descendants using the [`[CascadingTypeParameter]` attribute](xref:Microsoft.AspNetCore.Components.CascadingTypeParameterAttribute). This attribute allows a generic type inference to use the specified type parameter automatically with descendants that have a type parameter with the same name. For example, the following `Chart` component receives stock price data and cascades a generic type parameter named `TLineData` to its descendent components. @@ -115,7 +115,7 @@ By adding `@attribute [CascadingTypeParameter(...)]` to a component, the specifi * Also declare a [`@typeparam`](xref:mvc/views/razor#typeparam) with the exact same name. * Don't have another value supplied or inferred for the type parameter. If another value is supplied or inferred, it takes precedence over the cascaded generic type. -When receiving a cascaded type parameter, components obtain the parameter value from the closest ancestor that has a `CascadingTypeParameter` with a matching name. Cascaded generic type parameters are overridden within a particular subtree. +When receiving a cascaded type parameter, components obtain the parameter value from the closest ancestor that has a with a matching name. Cascaded generic type parameters are overridden within a particular subtree. Matching is only performed by name. Therefore, we recommend avoiding a cascaded generic type parameter with a generic name, for example `T` or `TItem`. If a developer opts into cascading a type parameter, they're implicitly promising that its name is unique enough not to clash with other cascaded type parameters from unrelated components. diff --git a/aspnetcore/blazor/fundamentals/handle-errors.md b/aspnetcore/blazor/fundamentals/handle-errors.md index cd3a48bc495d..d26d3bfb5e76 100644 --- a/aspnetcore/blazor/fundamentals/handle-errors.md +++ b/aspnetcore/blazor/fundamentals/handle-errors.md @@ -118,12 +118,12 @@ Because the approaches in this section handle errors with a [`try-catch`](/dotne ## Error boundaries -Error boundaries provide a convenient approach for handling exceptions. The `ErrorBoundary` component: +Error boundaries provide a convenient approach for handling exceptions. The component: * Renders its child content when an error hasn't occurred. * Renders error UI when an unhandled exception is thrown. -To define an error boundary, use the `ErrorBoundary` component to wrap existing content. For example, an error boundary can be added around the body content of the app's main layout. +To define an error boundary, use the component to wrap existing content. For example, an error boundary can be added around the body content of the app's main layout. `Shared/MainLayout.razor`: @@ -160,7 +160,7 @@ If the unhandled exception is thrown for a `currentCount` over five: * The exception is handled by the error boundary. * Error UI is rendered (`An error has occurred!`). -By default, the `ErrorBoundary` component renders an empty `
` element with the `blazor-error-boundary` CSS class for its error content. The colors, text, and icon for the default UI are defined using CSS in the app's stylesheet in the `wwwroot` folder, so you're free to customize the error UI. +By default, the component renders an empty `
` element with the `blazor-error-boundary` CSS class for its error content. The colors, text, and icon for the default UI are defined using CSS in the app's stylesheet in the `wwwroot` folder, so you're free to customize the error UI. You can also change the default error content by setting the `ErrorContent` property: @@ -175,7 +175,7 @@ You can also change the default error content by setting the `ErrorContent` prop ``` -Because the error boundary is defined in the layout in the preceding examples, the error UI is seen regardless of which page the user navigated to. We recommend narrowly scoping error boundaries in most scenarios. If you do broadly scope an error boundary, you can reset it to a non-error state on subsequent page navigation events by calling the error boundary's `Recover` method: +Because the error boundary is defined in the layout in the preceding examples, the error UI is seen regardless of which page the user navigated to. We recommend narrowly scoping error boundaries in most scenarios. If you do broadly scope an error boundary, you can reset it to a non-error state on subsequent page navigation events by calling the error boundary's method: ```razor ... diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 42ff9c443e2c..7e8078c1d359 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -45,7 +45,7 @@ Components support multiple route templates using multiple [`@page` directives]( ## Focus an element on navigation -Use the `FocusOnNavigate` component to set the UI focus to an element based on a CSS selector after navigating from one page to another. You can see the `FocusOnNavigate` component in use by the `App` component of an app generated from a Blazor project template. +Use the component to set the UI focus to an element based on a CSS selector after navigating from one page to another. You can see the component in use by the `App` component of an app generated from a Blazor project template. `App.razor`: @@ -63,7 +63,7 @@ Use the `FocusOnNavigate` component to set the UI focus to an element based on a ``` -When the preceding `Router` component navigates to a new page, the `FocusOnNavigate` component sets the focus to the page's top-level header (`

`). This is a common strategy for ensuring that page navigations are announced when using a screen reader. +When the preceding component navigates to a new page, the component sets the focus to the page's top-level header (`

`). This is a common strategy for ensuring that page navigations are announced when using a screen reader. ## Provide custom content when content isn't found @@ -169,7 +169,7 @@ Route constraints also work with [optional parameters](#route-parameters). In th ## Routing with URLs that contain dots -For hosted Blazor WebAssembly and Blazor Server apps, the server-side default route template assumes that if the last segment of a request URL contains a dot (`.`) that a file is requested. For example, the URL `https://localhost.com:5001/example/some.thing` is interpreted by the router as a request for a file named `some.thing`. Without additional configuration, an app returns a *404 - Not Found* response if `some.thing` was meant to route to a component with an [`@page` directive](xref:mvc/views/razor#page) and `some.thing` is a route parameter value. To use a route with one or more parameters that contain a dot, the app must configure the route with a custom template. +For hosted Blazor WebAssembly and Blazor Server apps, the server-side default route template assumes that if the last segment of a request URL contains a dot (`.`) that a file is requested. For example, the URL `https://localhost.com:5001/example/some.thing` is interpreted by the router as a request for a file named `some.thing`. Without additional configuration, an app returns a *404 - Not Found* response if `some.thing` was meant to route to a component with an [`@page`](xref:mvc/views/razor#page) directive and `some.thing` is a route parameter value. To use a route with one or more parameters that contain a dot, the app must configure the route with a custom template. Consider the following `Example` component that can receive a route parameter from the last segment of the URL. @@ -247,10 +247,10 @@ For more information on component disposal, see [!NOTE] -> Component parameters can only receive query parameter values in routable components with an `@page` directive. +> Component parameters can only receive query parameter values in routable components with an [`@page`](xref:mvc/views/razor#page) directive. Component parameters supplied from the query string support the following types: @@ -260,7 +260,7 @@ Component parameters supplied from the query string support the following types: The correct culture-invariant formatting is applied for the given type (). -Specify the `[SupplyParameterFromQuery]` attribute's `Name` property to use a query parameter name different from the component parameter name. In the following example, the C# name of the component parameter is `{COMPONENT PARAMETER NAME}`. A different query parameter name is specified for the `{QUERY PARAMETER NAME}` placeholder: +Specify the `[SupplyParameterFromQuery]` attribute's property to use a query parameter name different from the component parameter name. In the following example, the C# name of the component parameter is `{COMPONENT PARAMETER NAME}`. A different query parameter name is specified for the `{QUERY PARAMETER NAME}` placeholder: ```csharp [Parameter] @@ -309,7 +309,7 @@ In the following example with a URL of `/search?filter=scifi%20stars&page=3&star } ``` -Use `NavigationManager.GetUriWithQueryParameter` to add, change, or remove one or more query parameters on the current URL: +Use [`NavigationManager.GetUriWithQueryParameter`](xref:Microsoft.AspNetCore.Components.NavigationManagerExtensions.GetUriWithQueryParameter%2A) to add, change, or remove one or more query parameters on the current URL: ```razor @inject NavigationManager NavigationManager @@ -330,7 +330,7 @@ For the preceding example: * The query parameter name and value are URL-encoded. * All of the values with the matching query parameter name are replaced if there are multiple instances of the type. -Call `NavigationManager.GetUriWithQueryParameters` to create a URI constructed from with multiple parameters added, updated, or removed. For each value, the framework uses `value?.GetType()` to determine the runtime type for each query parameter and selects the correct culture-invariant formatting. The framework throws an error for unsupported types. +Call [`NavigationManager.GetUriWithQueryParameters`](xref:Microsoft.AspNetCore.Components.NavigationManagerExtensions.GetUriWithQueryParameters%2A) to create a URI constructed from with multiple parameters added, updated, or removed. For each value, the framework uses `value?.GetType()` to determine the runtime type for each query parameter and selects the correct culture-invariant formatting. The framework throws an error for unsupported types. ```razor @inject NavigationManager NavigationManager @@ -342,7 +342,7 @@ NavigationManager.GetUriWithQueryParameters({PARAMETERS}) The `{PARAMETERS}` placeholder is an `IReadOnlyDictionary`. -Pass a URI string to `GetUriWithQueryParameters` to generate a new URI from a provided URI with multiple parameters added, updated, or removed. For each value, the framework uses `value?.GetType()` to determine the runtime type for each query parameter and selects the correct culture-invariant formatting. The framework throws an error for unsupported types. Supported types are listed later in this section. +Pass a URI string to to generate a new URI from a provided URI with multiple parameters added, updated, or removed. For each value, the framework uses `value?.GetType()` to determine the runtime type for each query parameter and selects the correct culture-invariant formatting. The framework throws an error for unsupported types. Supported types are listed later in this section. ```razor @inject NavigationManager NavigationManager @@ -467,7 +467,7 @@ To navigate with an added or modified query string, pass a generated URL to to add or replace the `name` query parameter using a value of `Morena Baccarin`. * Calls to trigger navigation to the new URL. ```csharp diff --git a/aspnetcore/blazor/host-and-deploy/webassembly-deployment-layout.md b/aspnetcore/blazor/host-and-deploy/webassembly-deployment-layout.md index 5e98610545b7..fde7700721e0 100644 --- a/aspnetcore/blazor/host-and-deploy/webassembly-deployment-layout.md +++ b/aspnetcore/blazor/host-and-deploy/webassembly-deployment-layout.md @@ -34,7 +34,7 @@ The approach described in this article is used by the experimental [`Microsoft.A [Experimental code (includes the NuGet package reference source and `CustomPackagedApp` sample app)](https://github.com/aspnet/AspLabs/tree/main/src/BlazorWebAssemblyCustomInitialization) > [!WARNING] -> **`Microsoft.AspNetCore.Components.WebAssembly.MultipartBundle` and the `CustomPackagedApp` sample app are unsupported, experimental demonstration resources not intended for production use.** For more information and to provide feedback to the ASP.NET Core product unit, see [Consider releasing a supported version of `Microsoft.AspNetCore.Components.WebAssembly.MultipartBundle` (dotnet/aspnetcore #36978)](https://github.com/dotnet/aspnetcore/issues/36978). +> **The `Microsoft.AspNetCore.Components.WebAssembly.MultipartBundle` NuGet package and the `CustomPackagedApp` sample app are unsupported, experimental demonstration resources not intended for production use.** For more information and to provide feedback to the ASP.NET Core product unit, see [Consider releasing a supported version of `Microsoft.AspNetCore.Components.WebAssembly.MultipartBundle` (dotnet/aspnetcore #36978)](https://github.com/dotnet/aspnetcore/issues/36978). Later in this article, the [Customize the Blazor WebAssembly loading process via a NuGet package](#customize-the-blazor-webassembly-loading-process-via-a-nuget-package) section with its three subsections provide detailed explanations on the configuration and code in the `Microsoft.AspNetCore.Components.WebAssembly.MultipartBundle` package. The detailed explanations are important to understand when you create your own strategy and custom loading process for Blazor WebAssembly apps. To use the published, experimental, unsupported NuGet package without customization as a **local demonstration**, perform the following steps: diff --git a/aspnetcore/blazor/host-and-deploy/webassembly.md b/aspnetcore/blazor/host-and-deploy/webassembly.md index 7378cf7cfaa7..0686bfd0884c 100644 --- a/aspnetcore/blazor/host-and-deploy/webassembly.md +++ b/aspnetcore/blazor/host-and-deploy/webassembly.md @@ -62,7 +62,7 @@ The .NET WebAssembly build tools are based on [Emscripten](https://emscripten.or * Select the optional component in the Visual Studio installer. * Run `dotnet workload install wasm-tools` from an administrative command prompt. -Add native dependencies to a Blazor WebAssembly app by adding `NativeFileReference` items in the app's project file. When the project is built, each `NativeFileReference` is passed to Emscripten by the .NET WebAssembly build tools so that they are compiled and linked into the runtime. Next, [`p/invoke`](/dotnet/standard/native-interop/pinvoke) into the native code from the app's .NET code. +Add native dependencies to a Blazor WebAssembly app by adding `` items in the app's project file. When the project is built, each `` is passed to Emscripten by the .NET WebAssembly build tools so that they are compiled and linked into the runtime. Next, [`p/invoke`](/dotnet/standard/native-interop/pinvoke) into the native code from the app's .NET code. Generally, any portable native code can be used as a native dependency with Blazor WebAssembly. You can add native dependencies to C/C++ code or code previously compiled using Emscripten: @@ -89,7 +89,7 @@ Add a simple native C function to a Blazor WebAssembly app: } ``` -1. Add a `NativeFileReference` for `Test.c` in the app's project file: +1. Add a `` for `Test.c` in the app's project file: ```xml @@ -114,7 +114,7 @@ When you build the app with the .NET WebAssembly build tools installed, the nati ### Use libraries -NuGet packages can contain native dependencies for use on WebAssembly. These libraries and their native functionality are then available to any Blazor WebAssembly app. The files for the native dependencies should be built for WebAssembly and packaged in the `browser-wasm` [architecture-specific folder](/nuget/create-packages/supporting-multiple-target-frameworks#architecture-specific-folders). WebAssembly-specific dependencies aren't referenced automatically and must be referenced manually as `NativeFileReference`s. Package authors can choose to add the native references by including a `.props` file in the package with the references. +NuGet packages can contain native dependencies for use on WebAssembly. These libraries and their native functionality are then available to any Blazor WebAssembly app. The files for the native dependencies should be built for WebAssembly and packaged in the `browser-wasm` [architecture-specific folder](/nuget/create-packages/supporting-multiple-target-frameworks#architecture-specific-folders). WebAssembly-specific dependencies aren't referenced automatically and must be referenced manually as `` items. Package authors can choose to add the native references by including a `.props` file in the package with the references. [SkiaSharp](https://github.com/mono/SkiaSharp) is a cross-platform 2D graphics library for .NET based on the native [Skia graphics library](https://skia.org/), and it now has preview support for Blazor WebAssembly. @@ -132,10 +132,10 @@ To use SkiaSharp in a Blazor WebAssembly app: > [!NOTE] > At the time of writing, the [`SkiaSharp.Views.Blazor`](https://www.nuget.org/packages/SkiaSharp.Views.Blazor) package is a prerelease NuGet package not intended for production use. -1. Add a `SKCanvasView` component to the app with the following: +1. Add a `SKCanvasView` component to the app with the following: - * `SkiaSharp` and `SkiaSharp.Views.Blazor` namespaces. - * Logic to draw in the SkiaSharp Canvas View component (`SKCanvasView`). + * and `SkiaSharp.Views.Blazor` namespaces. + * Logic to draw in the SkiaSharp Canvas View component (`SKCanvasView`). `Pages/NativeDependencyExample.razor`: diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/persist-component-state.md b/aspnetcore/mvc/views/tag-helpers/built-in/persist-component-state.md index 1e0ab83d8d51..fadb3ac3eb31 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/persist-component-state.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/persist-component-state.md @@ -8,7 +8,6 @@ ms.custom: mvc ms.date: 07/16/2021 no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] uid: mvc/views/tag-helpers/builtin-th/persist-component-state-tag-helper -zone_pivot_groups: blazor-hosting-models --- # Persist Component State Tag Helper in ASP.NET Core @@ -19,13 +18,13 @@ Follow the guidance in the *Configuration* section for either: * [Blazor WebAssembly](xref:blazor/components/prerendering-and-integration?pivots=webassembly) * [Blazor Server](xref:blazor/components/prerendering-and-integration?pivots=server) -## Persist Component State Tag Helper +## Persist state for prerendered components -To persist state for prerendered components, use the Persist Component State Tag Helper (``). Add the `` tag inside the closing `` tag of the `_Host` page in an app that prerenders components: +To persist state for prerendered components, use the Persist Component State Tag Helper ([reference source](https://github.com/dotnet/aspnetcore/blob/main/src/Mvc/Mvc.TagHelpers/src/PersistComponentStateTagHelper.cs)). Add the Tag Helper's tag, ``, inside the closing `` tag of the `_Host` page in an app that prerenders components. -::: zone pivot="webassembly" +[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)] -`Pages/_Host.cshtml`: +In Blazor WebAssembly apps (`Pages/_Host.cshtml`): ```cshtml @@ -37,11 +36,7 @@ To persist state for prerendered components, use the Persist Component State Tag ``` -::: zone-end - -::: zone pivot="server" - -`Pages/_Host.cshtml`: +In Blazor Server apps (`Pages/_Host.cshtml`): ```cshtml @@ -53,9 +48,7 @@ To persist state for prerendered components, use the Persist Component State Tag ``` -::: zone-end - -Decide what state to persist using the `ComponentApplicationState` service. The `ComponentApplicationState.OnPersisting` event is fired just before the state is persisted into the prerendered page, which allows you to retrieve any persisted state when initializing a component. +Decide what state to persist using the service. The [`PersistentComponentState.RegisterOnPersisting`](xref:Microsoft.AspNetCore.Components.PersistentComponentState.RegisterOnPersisting%2A) event is fired just before the state is persisted into the prerendered page, which allows you to retrieve any persisted state when initializing a component. In the following example: diff --git a/aspnetcore/release-notes/aspnetcore-6.0.md b/aspnetcore/release-notes/aspnetcore-6.0.md index 62678ff72aa6..83c3aab26e32 100644 --- a/aspnetcore/release-notes/aspnetcore-6.0.md +++ b/aspnetcore/release-notes/aspnetcore-6.0.md @@ -152,7 +152,7 @@ Blazor WebAssembly apps can use native dependencies built to run on WebAssembly. Blazor WebAssembly supports ahead-of-time (AOT) compilation, where you can compile your .NET code directly into WebAssembly. AOT compilation results in runtime performance improvements at the expense of a larger app size. Relinking the .NET WebAssembly runtime trims unused runtime code and thus improves download speed. For more information, see [Ahead-of-time (AOT) compilation](xref:blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#ahead-of-time-aot-compilation) and [Runtime relinking](xref:blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#runtime-relinking). -### Persist prerendering state +### Persist prerendered state Blazor supports persisting state in a prerendered page so that the state doesn't need to be recreated when the app is fully loaded. For more information, see . @@ -255,6 +255,13 @@ HOLD HOLD --> +### New Blazor articles + +In addition to the Blazor features described in the preceding sections, new Blazor articles are available on the following subjects: + +* : Learn how to download a file using native `byte[]` streaming interop to ensure efficient transfer to the client. +* : Discover how to work with images in Blazor apps, including how to stream image data and preview an image. + ## Kestrel [HTTP/3](https://datatracker.ietf.org/doc/html/draft-ietf-quic-http-34) is currently in draft and therefore subject to change. HTTP/3 support in ASP.NET Core is not released, it's a preview feature included in .NET 6.