Skip to content

Commit

Permalink
API cross-links and other 9.0 updates (#34072)
Browse files Browse the repository at this point in the history
  • Loading branch information
guardrex authored Nov 8, 2024
1 parent e651e0a commit 3780f2d
Show file tree
Hide file tree
Showing 23 changed files with 69 additions and 117 deletions.
2 changes: 1 addition & 1 deletion aspnetcore/blazor/blazor-ef-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ The recommended approach to create a new <xref:Microsoft.EntityFrameworkCore.DbC
In the preceding factory:

* <xref:Microsoft.Extensions.DependencyInjection.ActivatorUtilities.CreateInstance%2A?displayProperty=nameWithType> satisfies any dependencies via the service provider.
* `IDbContextFactory` is available in EF Core ASP.NET Core 5.0 or later, so the interface is [implemented in the sample app for ASP.NET Core 3.x](https://github.com/dotnet/blazor-samples/blob/main/3.1/BlazorServerEFCoreSample/Data/IDbContextFactory.cs).
* <xref:Microsoft.EntityFrameworkCore.IDbContextFactory%601> is available in EF Core ASP.NET Core 5.0 or later, so the interface is [implemented in the sample app for ASP.NET Core 3.x](https://github.com/dotnet/blazor-samples/blob/main/3.1/BlazorServerEFCoreSample/Data/IDbContextFactory.cs).
:::moniker-end

Expand Down
12 changes: 5 additions & 7 deletions aspnetcore/blazor/call-web-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,13 +222,11 @@ For more information, see [Client-side services fail to resolve during prerender

When prerendering, components render twice: first statically, then interactively. State doesn't automatically flow from the prerendered component to the interactive one. If a component performs asynchronous initialization operations and renders different content for different states during initialization, such as a "Loading..." progress indicator, you may see a flicker when the component renders twice.

<!-- UPDATE 9.0 Keep an eye on the status of the enhanced nav fix
currently scheduled for Pre4. Remove the cross-link
to the PU issue when 9.0 releases.
Note that the README of the "weather" call web API
sample has a cross-link and remark on this, and the
sample app disabled enhanced nav on the weather
component link. -->
<!-- UPDATE 10.0 The status of the enhanced nav fix is scheduled for .NET 10.
Note that the README of the "weather" call web API
sample has a cross-link and remark on this, and the
sample app disabled enhanced nav on the weather
component link. -->

You can address this by flowing prerendered state using the Persistent Component State API, which the `BlazorWebAppCallWebApi` and `BlazorWebAppCallWebApi_Weather` [sample apps](#sample-apps) demonstrate. When the component renders interactively, it can render the same way using the same state. However, the API doesn't currently work with enhanced navigation, which you can work around by disabling enhanced navigation on links to the page (`data-enhanced-nav=false`). For more information, see the following resources:

Expand Down
6 changes: 3 additions & 3 deletions aspnetcore/blazor/components/js-spa-frameworks.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,10 @@ This article covers how to render Razor components from JavaScript, use Blazor c

## Angular sample apps

<!-- UPDATE 9.0 Add migration instructions cross-link to .NET 9 -->
<!-- UPDATE 10.0 Add migration instructions -->

* [CustomElementsBlazorSample (Blazor Server) (`javiercn/CustomElementsBlazorSample`, branch: `blazor-server`)](https://github.com/javiercn/CustomElementsBlazorSample/tree/blazor-server): Blazor Server is supported in .NET 8. To migrate this .NET 7 sample to .NET 8, see <xref:migration/70-to-80#update-a-blazor-server-app>.
* [CustomElementsBlazorSample (Blazor WebAssembly) (`javiercn/CustomElementsBlazorSample`, branch: `blazor-wasm`)](https://github.com/javiercn/CustomElementsBlazorSample/tree/blazor-wasm): To migrate this .NET 7 sample to .NET 8, see <xref:migration/70-to-80#update-a-blazor-webassembly-app>.
* [CustomElementsBlazorSample (Blazor Server) (`javiercn/CustomElementsBlazorSample`, branch: `blazor-server`)](https://github.com/javiercn/CustomElementsBlazorSample/tree/blazor-server): Blazor Server is supported in .NET 8/9. To migrate this .NET 7 sample, see <xref:migration/70-to-80#update-a-blazor-server-app> and <xref:migration/80-to-90>.
* [CustomElementsBlazorSample (Blazor WebAssembly) (`javiercn/CustomElementsBlazorSample`, branch: `blazor-wasm`)](https://github.com/javiercn/CustomElementsBlazorSample/tree/blazor-wasm): To migrate this .NET 7 sample, see <xref:migration/70-to-80#update-a-blazor-webassembly-app> and <xref:migration/80-to-90>.

## Render Razor components from JavaScript

Expand Down
3 changes: 0 additions & 3 deletions aspnetcore/blazor/components/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,6 @@ Component lifecycle events:
A parent component renders before its children components because rendering is what determines which children are present. If synchronous parent component initialization is used, the parent initialization is guaranteed to complete first. If asynchronous parent component initialization is used, the completion order of parent and child component initialization can't be determined because it depends on the initialization code running.

<!-- UPDATE 9.0 Update the diagram to drop "Property injection"?
https://github.com/dotnet/AspNetCore.Docs/issues/32091 -->

![Component lifecycle events of a Razor component in Blazor](~/blazor/components/lifecycle/_static/lifecycle1.png)

DOM event processing:
Expand Down
Binary file modified aspnetcore/blazor/components/lifecycle/_static/lifecycle1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 3 additions & 12 deletions aspnetcore/blazor/components/quickgrid.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ To implement a `QuickGrid` component:
* <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A>: If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A>, you should supply a value for <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.ItemSize%2A> and must ensure that every row renders with a constant height. Generally, it's preferable not to use <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A> if the amount of data rendered is small or if you're using pagination.
* <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.ItemSize%2A>: Only applicable when using <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A>. <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.ItemSize%2A> defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling.
* <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.ItemKey%2A>: Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance.
* `OverscanCount`: Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is 3. Only available when using <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A>.
* <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.OverscanCount%2A>: Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is 3. Only available when using <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Virtualize%2A>.
* <xref:Microsoft.AspNetCore.Components.QuickGrid.QuickGrid%601.Pagination%2A>: Optionally links this `TGridItem` instance with a <xref:Microsoft.AspNetCore.Components.QuickGrid.PaginationState> model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a <xref:Microsoft.AspNetCore.Components.QuickGrid.Paginator> component or some other UI logic that displays and updates the supplied <xref:Microsoft.AspNetCore.Components.QuickGrid.PaginationState> instance.
* In the `QuickGrid` child content (<xref:Microsoft.AspNetCore.Components.RenderFragment>), specify <xref:Microsoft.AspNetCore.Components.QuickGrid.PropertyColumn`2>s, which represent `TGridItem` columns whose cells display values:
* <xref:Microsoft.AspNetCore.Components.QuickGrid.PropertyColumn%602.Property%2A>: Defines the value to be displayed in this column's cells.
Expand Down Expand Up @@ -131,8 +131,8 @@ Set the `QuickGrid` component's <xref:Microsoft.AspNetCore.Components.QuickGrid.
<QuickGrid Items="..." Pagination="pagination">
```

<!-- UPDATE 9.0 Check on RC2 per https://github.com/dotnet/aspnetcore/issues/57289
to see if it's resolved for multiple paginator components. -->
<!-- UPDATE 10.0 Tracked by https://github.com/dotnet/aspnetcore/issues/57289
for multiple paginator components problem. -->

To provide a UI for pagination, add a [`Paginator` component](xref:Microsoft.AspNetCore.Components.QuickGrid.Paginator) above or below the `QuickGrid` component. Set the <xref:Microsoft.AspNetCore.Components.QuickGrid.Paginator.State%2A?displayProperty=nameWithType> to `pagination`:

Expand Down Expand Up @@ -236,14 +236,10 @@ The following example filters movies by a movie title entered in a search box. T
}
```

<!-- UPDATE 9.0 - Enable this cross-link after merging
https://github.com/dotnet/AspNetCore.Docs/pull/32747.
For a working example, see the following resources:

* [Build a Blazor movie database app tutorial](xref:blazor/tutorials/movie-database-app/index)
* [Blazor movie database sample app](https://github.com/dotnet/blazor-samples): Select the latest version folder in the repository. The sample folder for the tutorial's project is named `BlazorWebAppMovies`.
-->

## Display name support

Expand Down Expand Up @@ -492,9 +488,4 @@ dotnet aspnet-codegenerator blazor -h

---

<!-- UPDATE 9.0 Uncomment link after
https://github.com/dotnet/AspNetCore.Docs/pull/32747
merges.
For an example use of the `QuickGrid` scaffolder, see <xref:blazor/tutorials/movie-database-app/index>.
-->
20 changes: 10 additions & 10 deletions aspnetcore/blazor/components/render-modes.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,15 +217,15 @@ Additional information on render mode propagation is provided in the [Render mod

## Detect rendering location, interactivity, and assigned render mode at runtime

The `ComponentBase.RendererInfo` and `ComponentBase.AssignedRenderMode` properties permit the app to detect details about the location, interactivity, and assigned render mode of a component:
The <xref:Microsoft.AspNetCore.Components.ComponentBase.RendererInfo?displayProperty=nameWithType> and <xref:Microsoft.AspNetCore.Components.ComponentBase.AssignedRenderMode?displayProperty=nameWithType> properties permit the app to detect details about the location, interactivity, and assigned render mode of a component:

* `RendererInfo.Name` returns the location where the component is executing:
* <xref:Microsoft.AspNetCore.Components.RendererInfo.Name?displayProperty=nameWithType> returns the location where the component is executing:
* `Static`: On the server (SSR) and incapable of interactivity.
* `Server`: On the server (SSR) and capable of interactivity after prerendering.
* `WebAssembly`: On the client (CSR) and capable of interactivity after prerendering.
* `WebView`: On the native device and capable of interactivity after prerendering.
* `RendererInfo.IsInteractive` indicates if the component supports interactivity at the time of rendering. The value is `true` when rendering interactively or `false` when prerendering or for static SSR (`Platform.Name` of `Static`).
* `ComponentBase.AssignedRenderMode` exposes the component's assigned render mode:
* <xref:Microsoft.AspNetCore.Components.RendererInfo.IsInteractive?displayProperty=nameWithType> indicates if the component supports interactivity at the time of rendering. The value is `true` when rendering interactively or `false` when prerendering or for static SSR (<xref:Microsoft.AspNetCore.Components.RendererInfo.Name?displayProperty=nameWithType> of `Static`).
* <xref:Microsoft.AspNetCore.Components.ComponentBase.AssignedRenderMode?displayProperty=nameWithType> exposes the component's assigned render mode:
* `InteractiveServer` for Interactive Server.
* `InteractiveAuto` for Interactive Auto.
* `InteractiveWebAssembly` for Interactive WebAssembly.
Expand Down Expand Up @@ -281,7 +281,7 @@ else

In the preceding example:

* When the value of `AssignedRenderMode` is `null`, the component adopts static SSR. Blazor event handling isn't functional in a browser with static SSR, so the component submits a form (GET request) with a `titleFilter` query string set to the user's `<input>` value. The `Movie` component (`/movie`) can read the query string and process the value of `titleFilter` to render the component with the filtered results.
* When the value of <xref:Microsoft.AspNetCore.Components.ComponentBase.AssignedRenderMode> is `null`, the component adopts static SSR. Blazor event handling isn't functional in a browser with static SSR, so the component submits a form (GET request) with a `titleFilter` query string set to the user's `<input>` value. The `Movie` component (`/movie`) can read the query string and process the value of `titleFilter` to render the component with the filtered results.
* Otherwise, the render mode is any of `InteractiveServer`, `InteractiveWebAssembly`, or `InteractiveAuto`. The component is capable of using an event handler delegate (`FilterMovies`) and the value bound to the `<input>` element (`titleFilter`) to filter movies interactively over the background SignalR connection.

:::moniker-end
Expand Down Expand Up @@ -606,20 +606,20 @@ This approach is only useful when the app has specific pages that can't work wit

:::moniker range=">= aspnetcore-9.0"

Mark any Razor component page with the `[ExcludeFromInteractiveRouting]` attribute assigned with the `@attribute` Razor directive:
Mark any Razor component page with the [`[ExcludeFromInteractiveRouting]` attribute](xref:Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute) assigned with the `@attribute` Razor directive:

```razor
@attribute [ExcludeFromInteractiveRouting]
```

Applying the attribute causes navigation to the page to exit from [interactive routing](xref:blazor/fundamentals/routing#static-versus-interactive-routing). Inbound navigation is forced to perform a full-page reload instead resolving the page via interactive routing. The full-page reload forces the top-level root component, typically the `App` component (`App.razor`), to rerender from the server, allowing the app to switch to a different top-level render mode.

The `HttpContext.AcceptsInteractiveRouting` extension method allows the component to detect whether `[ExcludeFromInteractiveRouting]` is applied to the current page.
The <xref:Microsoft.AspNetCore.Components.Routing.RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting%2A?displayProperty=nameWithType> extension method allows the component to detect whether the [`[ExcludeFromInteractiveRouting]` attribute](xref:Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute) is applied to the current page.

In the `App` component, use the pattern in the following example:

* Pages that aren't annotated with `[ExcludeFromInteractiveRouting]` default to the `InteractiveServer` render mode with global interactivity. You can replace `InteractiveServer` with `InteractiveWebAssembly` or `InteractiveAuto` to specify a different default global render mode.
* Pages annotated with `[ExcludeFromInteractiveRouting]` adopt static SSR (`PageRenderMode` is assigned `null`).
* Pages that aren't annotated with the [`[ExcludeFromInteractiveRouting]` attribute](xref:Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute) default to the `InteractiveServer` render mode with global interactivity. You can replace `InteractiveServer` with `InteractiveWebAssembly` or `InteractiveAuto` to specify a different default global render mode.
* Pages annotated with the [`[ExcludeFromInteractiveRouting]` attribute](xref:Microsoft.AspNetCore.Components.ExcludeFromInteractiveRoutingAttribute) adopt static SSR (`PageRenderMode` is assigned `null`).

```razor
<!DOCTYPE html>
Expand All @@ -643,7 +643,7 @@ In the `App` component, use the pattern in the following example:
}
```

An alternative to using the `HttpContext.AcceptsInteractiveRouting` extension method is to read endpoint metadata manually using `HttpContext.GetEndpoint()?.Metadata`.
An alternative to using the <xref:Microsoft.AspNetCore.Components.Routing.RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting%2A?displayProperty=nameWithType> extension method is to read endpoint metadata manually using `HttpContext.GetEndpoint()?.Metadata`.

:::moniker-end

Expand Down
4 changes: 2 additions & 2 deletions aspnetcore/blazor/components/rendering.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ The state manager approach is similar to the earlier case with <xref:System.Time

## WebAssembly loading progress indicator for Blazor Web Apps

<!-- UPDATE 9.0 Will be removed for a new feature in this area.
Tracked by: https://github.com/dotnet/aspnetcore/issues/49056 -->
<!-- UPDATE 10.0 Will be removed for a new feature in this area.
Tracked by: https://github.com/dotnet/aspnetcore/issues/49056 -->

A loading progress indicator isn't present in an app created from the Blazor Web App project template. A new loading progress indicator feature is planned for a future release of .NET. In the meantime, an app can adopt custom code to create a loading progress indicator. For more information, see <xref:blazor/fundamentals/startup#client-side-loading-progress-indicators>.
2 changes: 1 addition & 1 deletion aspnetcore/blazor/forms/input-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -458,7 +458,7 @@ The validation summary displays the friendly name when the field's value is inva

> The Production Date field must be a date.
<!-- UPDATE 9.0 The feature has been backlogged.
<!-- UPDATE 10.0 The feature has been backlogged.
https://github.com/dotnet/aspnetcore/issues/49147
> [!NOTE]
Expand Down
12 changes: 6 additions & 6 deletions aspnetcore/blazor/fundamentals/environments.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ This article explains how to configure and read the [environment](xref:fundament

When running an app locally, the environment defaults to `Development`. When the app is published, the environment defaults to `Production`.

<!-- UPDATE 9.0 The underlying problem with app settings filename
case sensitivity is tracked for 9.0 by ...
https://github.com/dotnet/aspnetcore/issues/25152 -->
<!-- UPDATE 10.0 The underlying problem with app settings filename
case sensitivity is tracked for 10.0 by ...
https://github.com/dotnet/aspnetcore/issues/25152 -->
We recommend the following conventions:

Expand Down Expand Up @@ -153,9 +153,9 @@ In the following example for IIS, the custom header (`blazor-environment`) is ad
## Set the environment for Azure App Service

<!-- UPDATE 9.0 The underlying problem with app settings filename
case sensitivity is tracked for 9.0 by ...
https://github.com/dotnet/aspnetcore/issues/25152 -->
<!-- UPDATE 10.0 The underlying problem with app settings filename
case sensitivity is tracked for 10.0 by ...
https://github.com/dotnet/aspnetcore/issues/25152 -->

For a standalone Blazor WebAssembly app, you can set the environment manually via [start configuration](#set-the-client-side-environment-via-blazor-startup-configuration) or the [`blazor-environment` header](#set-the-client-side-environment-via-header).

Expand Down
Loading

0 comments on commit 3780f2d

Please sign in to comment.