diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index 44038002e7cb..83a305706d4a 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -29,7 +29,35 @@ For various QuickGrid demonstrations, see the [**QuickGrid for Blazor** sample a To implement a `QuickGrid` component: -:::moniker range=">= aspnetcore-9.0" +:::moniker range=">= aspnetcore-11.0" + + + +* Specify tags for the `QuickGrid` component in Razor markup (`...`). +* Name a queryable source of data for the grid. Use ***either*** of the following data sources: + * : A nullable `IQueryable`, where `TGridItem` is the type of data represented by each row in the grid. + * : A callback that supplies data for the grid. +* `QueryParameterNamePrefix`: The parameter from which the page and sorting URL parameters are derived. The default value is an empty string, which results in query parameters named "`page`", "`sort`", and "`order`". Setting a prefix for the preceding query string parameters allows the use of multiple `QuickGrid` components on the same page without their URL parameters conflicting with each other. For more information, see the [Pagination modes](#pagination-modes) and [Multiple grids on the same page](#multiple-grids-on-the-same-page) sections. +* : An optional CSS class name. If provided, the class name is included in the `class` attribute of the rendered table. +* : A theme name (default value: `default`). This affects which styling rules match the table. +* : 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 , you should supply a value for and must ensure that every row renders with a constant height. Generally, it's preferable not to use if the amount of data rendered is small or if you're using pagination. +* : Only applicable when using . 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. +* : 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. +* : 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 . +* : Optionally links this `TGridItem` instance with a model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a component or some other UI logic that displays and updates the supplied instance. includes API for interacting with the current zero-based page index, the number of items on each page, the zero-based index of the last page, and the total number of items across all pages. +* In the QuickGrid child content (), specify s, which represent `TGridItem` columns whose cells display values: + * : Defines the value to be displayed in this column's cells. + * : Optionally specifies a format string for the value. Using requires the `TProp` type to implement . + * : Indicates whether the data should be sortable by this column. The default value may vary according to the column type. For example, a is sorted if any parameter is specified. + * : Indicates the sort direction if is `true`. + * : Indicates whether this column should be sorted by default. + * : If specified, virtualized grids use this template to render cells whose data hasn't been loaded. + * : An optional template for this column's header cell. If not specified, the default header template includes the , along with any applicable sort indicators and options buttons. + * : Title text for the column. The title is rendered automatically if isn't used. + +:::moniker-end + +:::moniker range=">= aspnetcore-9.0 < aspnetcore-11.0" * Specify tags for the `QuickGrid` component in Razor markup (`...`). * Name a queryable source of data for the grid. Use ***either*** of the following data sources: @@ -80,8 +108,12 @@ To implement a `QuickGrid` component: For example, add the following component to render a grid. +:::moniker range="< aspnetcore-11.0" + For Blazor Web Apps, the `QuickGrid` component must adopt an [interactive render mode](xref:blazor/components/render-modes#render-modes) to enable interactive features, such as paging and sorting. +:::moniker-end + `PromotionGrid.razor`: :::moniker range=">= aspnetcore-9.0" @@ -100,22 +132,20 @@ Access the component in a browser at the relative path `/promotion-grid`. There aren't current plans to extend QuickGrid with features that full-blown commercial grids tend to offer, for example, hierarchical rows, drag-to-reorder columns, or Excel-like range selections. If you require advanced features that you don't wish to develop on your own, continue using third-party grids. -## Sort by column - -The `QuickGrid` component can sort items by columns. In Blazor Web Apps, sorting requires the component to adopt an [interactive render mode](xref:blazor/components/render-modes#render-modes). +## Page items with a `Paginator` component -Add `Sortable="true"` () to the tag: +:::moniker range=">= aspnetcore-11.0" -```razor - -``` +The `QuickGrid` component can page data from the data source. -In the running app, sort the QuickGrid column by selecting the rendered column title. +:::moniker-end -## Page items with a `Paginator` component +:::moniker range="< aspnetcore-11.0" The `QuickGrid` component can page data from the data source. In Blazor Web Apps, paging requires the component to adopt an [interactive render mode](xref:blazor/components/render-modes#render-modes). +:::moniker-end + Add a instance to the component's `@code` block. Set the to the number of items to display per page. In the following example, the instance is named `pagination`, and ten items per page is set: ```csharp @@ -128,51 +158,212 @@ Set the `QuickGrid` component's ``` - +:::moniker range=">= aspnetcore-11.0" + +To provide a UI for pagination, add a [`Paginator` component](xref:Microsoft.AspNetCore.Components.QuickGrid.Paginator) above, below, or both above and below the `QuickGrid` component. Set the to `pagination`: + +:::moniker-end + +:::moniker range="< aspnetcore-11.0" To provide a UI for pagination, add a [`Paginator` component](xref:Microsoft.AspNetCore.Components.QuickGrid.Paginator) above or below the `QuickGrid` component. Set the to `pagination`: +:::moniker-end + ```razor ``` In the running app, page through the items using a rendered `Paginator` component. +:::moniker range="< aspnetcore-11.0" + QuickGrid renders additional empty rows to fill in the final page of data when used with a `Paginator` component. In .NET 9 or later, empty data cells (``) are added to the empty rows. The empty rows are intended to facilitate rendering the QuickGrid with stable row height and styling across all pages. -## Open and return from a details page with a paged QuickGrid component +:::moniker-end -A paged QuickGrid component can open a details page for a record and return to the correct page of results using the approach in this section. +:::moniker range=">= aspnetcore-11.0" + + + +`GetPageUrl` returns a URL with the one-based page number. Page index 0 (page 1) omits the query parameter entirely. - + +Multiple `QuickGrid` components on the same page require unique `QueryParameterNamePrefix` values to avoid query string conflicts. The default prefix is an empty string, producing parameters named `page`, `sort`, `order`. For example, setting the prefix to "`cities`" produces `cities_page`, `cities_sort`, and `cities_order`. + +Each `QuickGrid` must have its own `PaginationState` instance. Multiple grids must not share a `PaginationState` if they have different prefixes—the last grid to render overwrites the query parameter name on the shared state, causing the `Paginator` to read from the wrong parameter. + +In the following example, each `QuickGrid` requires a unique `QueryParameterNamePrefix`. The first `QuickGrid` uses the default empty string prefix, while the second one sets `cities` as the prefix: + +```razor + + ... + + + + + + ... + + + +``` + +In the following query string: + +* The `page=2&sort=Name&order=asc` portion applies to the first `QuickGrid` component. +* The `cities_sort=Country&cities_order=desc` portion applies to the second `QuickGrid` component. + +``` +?page=2&sort=Name&order=asc&cities_page=3&cities_sort=Country&cities_order=desc +``` + +:::moniker-end + +:::moniker range=">= aspnetcore-11.0" + +#### Row click event (`OnRowClick`) + +The `QuickGrid` component supports row click events through the parameter. When set, the grid automatically applies appropriate styling (cursor pointer) and invokes the callback with the clicked item: + +```razor +@using Microsoft.AspNetCore.Components.QuickGrid +@inject NavigationManager NavigationManager + + + + + + +@code { + private List people = new() + { + new(1, "Alice Smith", "alice@example.com", "Engineering"), + new(2, "Bob Johnson", "bob@example.com", "Marketing"), + new(3, "Carol Williams", "carol@example.com", "Engineering"), + }; + + private void HandleRowClick(Person person) + { + NavigationManager.NavigateTo($"/person/{person.Id}"); + } + + private record Person(int Id, string Name, string Email, string Department); +} +``` + +The feature includes built-in CSS styling that applies a pointer cursor to clickable rows through the row-clickable CSS class, providing clear visual feedback to users. + +:::moniker-end + +## Sort by column + +:::moniker range=">= aspnetcore-11.0" + +The `QuickGrid` component can sort items by columns. Selecting a header navigates to a URL with updated `sort` and `order` parameters. `SortByColumnAsync` navigates via `NavigationManager.NavigateTo(GetSortQueryStringUrl(...))`, so the URL always reflects the sort state. + +:::moniker-end + +:::moniker range="< aspnetcore-11.0" + +The `QuickGrid` component can sort items by columns. In Blazor Web Apps, sorting requires the component to adopt an [interactive render mode](xref:blazor/components/render-modes#render-modes). + +:::moniker-end + +Add `Sortable="true"` () to the tag: + +```razor + +``` + +In the running app, sort the QuickGrid column by selecting the rendered column title. + +:::moniker range=">= aspnetcore-11.0" + +Sort state in the URL uses the column's `Title` property as the identifier. The `sort` query parameter is set to `column.Title` (example for column title `Name`: `?sort=Name&order=asc`). On a URL change, `QuickGrid` matches the `sort` value back to a column by executing `_columns.FirstOrDefault(c => c.Title == sort.ColumnTitle)`. If no column title matches, the sort is ignored and the grid falls back to its default sort. + +Renaming a column's `Title` is a URL-breaking change. Any bookmarked or shared URLs containing the old title in the `sort` parameter stop matching, and the grid silently falls back to the default sort instead of sorting by the intended column. For `PropertyColumn`, the `Title` defaults to the property name (example: `Property="@(p => p.FirstName)"` produces `Title="First Name"`), so renaming the property or explicitly changing the `Title` parameter both break existing URLs. + > [!NOTE] -> The approach described in this section is simplified by URL-based navigation in .NET 11 or later. For more information, see this section in a .NET 11 or later version of this article. +> If you want to share stylesheet classes between URL-based and inner-state based pagination, selectors targeting `button.col-title` must also target `a.col-title`, and `nav button`/`nav button:disabled` require `nav a`/`nav a[aria-disabled="true"]`. The built-in QuickGrid stylesheet provides both by default. + +:::moniker-end + +## Open and return from a details page with a paged QuickGrid component + +:::moniker range=">= aspnetcore-11.0" + +A paged QuickGrid component can open a details page for a record and return to the correct page of results using the approach in this section. URL-based navigation is used to save the page number and return the user to the same page of items from a details page. ---> +:::moniker-end + +:::moniker range="< aspnetcore-11.0" + +A paged QuickGrid component can open a details page for a record and return to the correct page of results using the approach in this section. + +> [!NOTE] +> The approach described in this section is simplified by URL-based navigation in .NET 11 or later. For more information, see this section in a .NET 11 or later version of this article. The following API is used: * : Gets the current zero-based page index. * : Sets the current page index and notifies any associated `QuickGrid` components to fetch and render updated data. - - The `Details` component receives the page number from the query string in the `Page` property and uses it to form a link back to the `QuickGrid` component at `/scifi-characters`. `Details.razor`: @@ -199,14 +390,10 @@ The `Details` component receives the page number from the query string in the `P The `SciFiCharacters` component: - - * Pages the `QuickGrid` component by calling on component initialization, setting the page index with the value of `Page` (page number) minus one (`-1`). The `page` query string parameter is removed after setting the page index using and [`GetUriWithQueryParameter`](xref:blazor/fundamentals/navigation#query-strings). * Opens the preceding `Details` component with the current page number, the page index incremented by one (`+1`), to make the value a one-based index () in the query string. A one-based index for the `page` query string parameter matches the rendered `Paginator` component's rendered one-based page number in the UI. @@ -336,12 +523,8 @@ In `Details.razor`: } ``` - - ## Apply row styles Apply styles to rows using [CSS isolation](xref:blazor/components/css-isolation), which can include styling empty rows for `QuickGrid` components that [page data with a `Paginator` component](#page-items-with-a-paginator-component). diff --git a/aspnetcore/blazor/debug.md b/aspnetcore/blazor/debug.md index 19e5fd200fe2..de540ad24af0 100644 --- a/aspnetcore/blazor/debug.md +++ b/aspnetcore/blazor/debug.md @@ -85,6 +85,35 @@ Unsupported scenarios for Blazor WebAssembly apps include: :::moniker-end +:::moniker range=">= aspnetcore-11.0" + +## Blazor WebAssembly Gateway + + + +`Microsoft.AspNetCore.Components.Gateway` is a lightweight ASP.NET Core host for serving standalone Blazor WebAssembly apps during development and production. + +The Gateway is a full ASP.NET Core host, not merely a static-file dev tool, so standalone Blazor WebAssembly apps feature: + +* Built-in SPA fallback routing: Requests that don't match a static asset fall back to `index.html`, so client-side routes such as `/orders/42` work on browser refresh and direct navigation without a custom MSBuild target. +* Multiple Blazor WebAssembly clients per host: A single Gateway instance can serve more than one Blazor WebAssembly client under different path prefixes, configured through its `ClientApps` section. This is the integration point .NET Aspire uses to host Blazor WebAssembly clients alongside backend services in a single AppHost run. +* Built-in YARP reverse-proxy infrastructure: YARP is bundled with the Gateway, providing the foundation for forwarding backend traffic alongside the WebAssembly client and enabling the Aspire multi-client scenarios. + +To adopt the Gateway in an existing standalone Blazor WebAssembly app that targets .NET 11 or later, reference the `Microsoft.AspNetCore.Components.Gateway` package in the app's project file. + +[!INCLUDE[](~/includes/package-reference.md)] + +Custom routing code and middleware aren't required by the app. Fallback endpoints come from the static web assets manifest the SDK emits when the `StaticWebAssetSpaFallbackEnabled` property is set in the app's project file, which is present by default in standalone Blazor WebAssembly apps created from the project template: + +```xml +true +``` + +:::moniker-end + ## Prerequisites This section explains the prerequisites for debugging. @@ -133,6 +162,8 @@ Installing the C# Dev Kit automatically installs the following additional extens If you encounter warnings or errors, you can [open an issue (`microsoft/vscode-dotnettools` GitHub repository)](https://github.com/microsoft/vscode-dotnettools/issues) describing the problem. +:::moniker range="< aspnetcore-11.0" + ### App configuration prerequisites *The guidance in this subsection applies to client-side debugging.* @@ -152,6 +183,8 @@ The placeholder values for the WebSocket protocol (`wsProtocol`), host (`url.hos [!INCLUDE[](~/includes/default-launch-profile-for-dotnet-cli.md)] +:::moniker-end + ## Packages :::moniker range=">= aspnetcore-8.0" diff --git a/aspnetcore/blazor/fundamentals/configuration.md b/aspnetcore/blazor/fundamentals/configuration.md index b9ba6aef0afb..6dcfde4c0063 100644 --- a/aspnetcore/blazor/fundamentals/configuration.md +++ b/aspnetcore/blazor/fundamentals/configuration.md @@ -373,3 +373,22 @@ The following Razor component retrieves the settings with the [`@inject`](xref:m ``` Not all of the ASP.NET Core Options features are supported in Razor components. For example, and configuration is supported, but recomputing option values for these interfaces isn't supported outside of reloading the app by either requesting the app in a new browser tab or selecting the browser's reload button. Merely calling [`StateHasChanged`](xref:blazor/components/lifecycle#state-changes-statehaschanged) doesn't update snapshot or monitored option values when the underlying configuration changes. + +:::moniker range=">= aspnetcore-11.0" + +### Environment variables in Blazor WebAssembly configuration + +Blazor WebAssembly applications access environment variables through . This enables runtime configuration without rebuilding the app, making it easier to deploy the same build to different environments. + +In the following example, the `API_ENDPOINT` and `ENABLE_FEATURE_X` environment variables are automatically included in configuration: + +```csharp +var builder = WebAssemblyHostBuilder.CreateDefault(args); + +var apiEndpoint = builder.Configuration["API_ENDPOINT"]; +var featureFlag = builder.Configuration["ENABLE_FEATURE_X"]; +``` + +Environment variables are loaded into the configuration system alongside other configuration sources, such as app settings (`appsettings.json`), providing a unified way to access configuration values regardless of their source. + +:::moniker-end diff --git a/aspnetcore/blazor/fundamentals/environments.md b/aspnetcore/blazor/fundamentals/environments.md index fc1d8cbe7f0c..479b23872d45 100644 --- a/aspnetcore/blazor/fundamentals/environments.md +++ b/aspnetcore/blazor/fundamentals/environments.md @@ -289,6 +289,36 @@ App settings from the `appsettings.{ENVIRONMENT}.json` file are loaded by the ap :::moniker-end +:::moniker range=">= aspnetcore-11.0" + +## `EnvironmentBoundary` component + + + +Use the `EnvironmentBoundary` component for conditional rendering based on the hosting environment. This component provides a consistent way to render content based on the current environment across both server-side and client-side hosting models. + +The `EnvironmentBoundary` component accepts `Include` and `Exclude` parameters for specifying environment names. The component performs case-insensitive matching. + +```razor +@using Microsoft.AspNetCore.Components.Web + + +
+ Debug mode enabled +
+ + + +

Pre-production environment

+ + + +

@DateTime.Now

+ +``` + +:::moniker-end + ## Read the environment in a Blazor WebAssembly app Obtain the app's environment in a component by injecting and reading the property. diff --git a/aspnetcore/blazor/fundamentals/navigation.md b/aspnetcore/blazor/fundamentals/navigation.md index 0046c6ea899a..8901f39b8d20 100644 --- a/aspnetcore/blazor/fundamentals/navigation.md +++ b/aspnetcore/blazor/fundamentals/navigation.md @@ -1165,11 +1165,42 @@ For more information on JavaScript isolation with JavaScript modules, see + +Use the `GetUriWithHash` extension method to construct a URI with a hash fragment. This helper method provides an efficient, zero-allocation way to append hash fragments to the current URI. The following example demonstrates two use cases: + +* Inline call that jumps to Section 1 (`id="section-1"`) of the rendered page. +* Method call that receives a section identifier (`sectionId`) and navigates to the section of the page. + +```razor +@inject NavigationManager Navigation + + + Jump to Section 1 + + +@code { + private void NavigateToSection(string sectionId) + { + var uri = Navigation.GetUriWithHash(sectionId); + Navigation.NavigateTo(uri); + } +} +``` + +The method uses `string.Create` for optimal performance and works correctly with non-root base URIs (for example, when using ``). + +:::moniker-end + :::moniker range=">= aspnetcore-8.0" -## Navigate to named elements +## Navigate to an element with a hashed (`#`) reference -Navigate to a named element using the following approaches with a hashed (`#`) reference to the element. Routes to elements within the component and routes to elements in external components use root-relative paths. A leading forward slash (`/`) is optional. +Navigate to an element using the following approaches with a hashed (`#`) reference to the element. Routes to elements within the component and routes to elements in external components use root-relative paths. A leading forward slash (`/`) is optional. Examples for each of the following approaches demonstrate navigation to an element with an `id` of `targetElement` in the `Counter` component: @@ -1191,7 +1222,68 @@ Examples for each of the following approaches demonstrate navigation to an eleme Navigation.NavigateTo("/counter#targetElement"); ``` -The following example demonstrates navigating to named H2 headings within a component and to external components. +:::moniker-end + +:::moniker range=">= aspnetcore-11.0" + +The following example demonstrates navigating to an H2 heading in an external component. + +> [!NOTE] +> For element navigation at the same URI, see [Navigate to an element at the current URI](#navigate-to-an-element-at-the-current-uri). + +In the `Home` (`Home.razor`) and `Counter` (`Counter.razor`) components, place the following markup at the bottoms of the existing component markup to serve as navigation targets. The `
` creates artificial vertical space to demonstrate browser scrolling behavior: + +```razor +
+ +

Target H2 heading

+

Content!

+``` + +Add the following `FragmentRouting` component to the app. + +`FragmentRouting.razor`: + +```razor +@page "/fragment-routing" +@inject NavigationManager Navigation + +Fragment routing + +

Fragment routing to elements

+ + + +@code { + private void NavigateToElement() + { + Navigation.NavigateTo("/counter#targetElement"); + } +} +``` + +:::moniker-end + +:::moniker range=">= aspnetcore-8.0 < aspnetcore-11.0" + +The following example demonstrates navigating to H2 headings within a component and to external components. In the `Home` (`Home.razor`) and `Counter` (`Counter.razor`) components, place the following markup at the bottoms of the existing component markup to serve as navigation targets. The `
` creates artificial vertical space to demonstrate browser scrolling behavior: @@ -1212,7 +1304,7 @@ Add the following `FragmentRouting` component to the app. Fragment routing -

Fragment routing to named elements

+

Fragment routing to elements