diff --git a/aspnetcore/blazor/components/render-modes.md b/aspnetcore/blazor/components/render-modes.md new file mode 100644 index 000000000000..ea99877614f8 --- /dev/null +++ b/aspnetcore/blazor/components/render-modes.md @@ -0,0 +1,460 @@ +--- +title: ASP.NET Core Blazor render modes +author: guardrex +description: Learn about Blazor render modes and how to apply them in Blazor Web Apps. +monikerRange: '>= aspnetcore-8.0' +ms.author: riande +ms.custom: mvc +ms.date: 09/08/2023 +uid: blazor/components/render-modes +--- +# ASP.NET Core Blazor render modes + +This article explains control of Razor component rendering in Blazor Web Apps, either at compile time or runtime. + +## Render modes + +Every component in a Blazor Web App adopts a *render mode* to determine the hosting model that it uses, where it's rendered, and whether or not it's interactive. + +The following table shows the available render modes for rendering Razor components in a Blazor Web App. To apply a render mode to a component use the `@rendermode` directive on the component instance or use the [`@attribute` Razor directive](xref:mvc/views/razor#attribute) with the corresponding render mode attribute in the component's Razor markup. Later in this article, examples are shown for each render mode scenario. + +Name | Description | Render location | Interactive +---- | ----------- | :-------------: | :---------: +Static | Static server rendering | Server | +Server | Interactive server rendering using Blazor Server | Server | +WebAssembly | Interactive client rendering using Blazor WebAssembly | Client | +Auto | Interactive client rendering using Blazor Server initially and then WebAssembly on subsequent visits after the Blazor bundle is downloaded | Server, then client | + +Prerendering is enabled by default for interactive components. Guidance on controlling prerendering is provided later in this article. + +The following examples demonstrate setting the component's render mode with a few basic Razor component features. + +To test the render mode behaviors locally, you can place the following components in an app created from the *Blazor Web App* project template. When you create the app, select the checkboxes (Visual Studio) or apply the CLI options (.NET CLI) to enable both server-side and client-side interactivity. For guidance on how to create a Blazor Web App, see . + +## Enable support for interactive render modes + +A Blazor Web App must be configured to support interactive render modes. The following extensions are automatically applied to apps created from the *Blazor Web App* project template during app creation. Individual components are still required to declare their render mode per the [*Render modes*](#render-modes) section after the component services and endpoints are configured in the app's `Program` file. + +Services for Razor components are added by calling . + +Component builder extensions: + +* adds services to support rendering interactive server components. +* `AddWebAssemblyComponents` adds services to support rendering interactive WebAssembly components. + + + + discovers available components and specifies the root component for the app, which by default is the `App` component (`App.razor`). + +Endpoint convention builder extensions: + +* configures the Server render mode for the app. +* `AddWebAssemblyRenderMode` configures the WebAssembly render mode for the app. + + + +> [!NOTE] +> For orientation on the placement of the API in the following examples, inspect the `Program` file of an app generated from the Blazor Web App project template. For guidance on how to create a Blazor Web App, see . + +Example 1: The following `Program` file API adds services and configuration for enabling the Server render mode: + +```csharp +builder.Services.AddRazorComponents() + .AddServerComponents(); +``` + +```csharp +app.MapRazorComponents() + .AddServerRenderMode(); +``` + +Example 2: The following `Program` file API adds services and configuration for enabling the WebAssembly render mode: + +```csharp +builder.Services.AddRazorComponents() + .AddWebAssemblyComponents(); +``` + +```csharp +app.MapRazorComponents() + .AddWebAssemblyRenderMode(); +``` + +Example 3: The following `Program` file API adds services and configuration for enabling the Server, WebAssembly, and Auto render modes: + +```csharp +builder.Services.AddRazorComponents() + .AddServerComponents() + .AddWebAssemblyComponents(); +``` + +```csharp +app.MapRazorComponents() + .AddServerRenderMode() + .AddWebAssemblyRenderMode(); +``` + +Blazor uses the Blazor WebAssembly hosting model to download and execute components that use the WebAssembly render mode. A separate client project is required to set up Blazor WebAssembly hosting for these components. The client project contains the startup code for the Blazor WebAssembly host and sets up the .NET runtime for running in a browser. The Blazor Web App template adds this client project for you when you select the option to enable WebAssembly interactivity. Any components using the WebAssembly render mode should be built from the client project, so they get included in the downloaded app bundle. + +## Apply a render mode to a component instance + +To apply a render mode to a component instance use the [`@rendermode` Razor directive attribute](xref:mvc/views/razor#attribute) where the component is used. + +In the following example, the Server render mode is applied to the `Dialog` component instance: + +```razor + +``` + +> [!NOTE] +> During .NET 8 *Release Candidate 1*, use the following values: +> +> Render mode | Value +> ----------- | ----- +> Server | `@RenderMode.Server` +> WebAssembly | `@RenderMode.WebAssembly` +> Auto | `@RenderMode.Auto` +> +> The preceding syntax will be simplified in an upcoming preview release. + +## Apply a render mode to a component definition + +To specify the render mode for a component as part of its definition, use the [`@attribute` Razor directive](xref:mvc/views/razor#attribute) and the corresponding render mode attribute. + +```razor +@page "{ROUTE}" +@attribute [RenderModeServer] +``` + +In the preceding example, the `{ROUTE}` placeholder is the route template. + +Applying a render mode to a component definition is commonly used when applying a render mode to a specific page. Routable pages by default use the same render mode as the router component that rendered the page. + +> [!NOTE] +> Component authors should avoid coupling a component's implementation to a specific render mode. Instead, component authors should typically design components to support any render mode or hosting model. A component's implementation should avoid assumptions on where it's running (server or client) and should degrade gracefully when rendered statically. Specifying the render mode in the component definition may be needed if the component isn't instantiated directly (such as with a routable page component) or to specify a render mode for all component instances. + +> [!NOTE] +> During .NET 8 *Release Candidate 1*, use the following attributes: +> +> Render mode | Value +> ----------- | ----- +> Server | `[RenderModeServer]` +> WebAssembly | `[RenderModeWebAssembly]` +> Auto | `[RenderModeAuto]` +> +> The preceding syntax will be simplified in an upcoming preview release. + +## Prerendering + +Prerendering is enabled by default for interactive components. + +To disable prerendering, pass the `prerender` flag with a value of `false`. + +For a component instance: + +```razor + +``` + +From the component definition: + +```razor +@page "{ROUTE}" +@attribute [RenderModeServer(prerender: false)] +``` + +In the preceding example, the `{ROUTE}` placeholder is the route template. + +> [!NOTE] +> During .NET 8 *Release Candidate 1*, use the following values: +> +> Render mode | Value +> ----------- | ----- +> Server | `@(new ServerRenderMode(prerender: false))` +> WebAssembly | `@(new WebAssemblyRenderMode(prerender: false))` +> Auto | `@(new AutoRenderMode(prerender: false))` +> +> The preceding syntax will be simplified in an upcoming preview release. + +## Static render mode + +By default, components use the Static render mode. The component renders to the response stream and interactivity isn't enabled. + +In the following example, there's no designation for the component's render mode, and the component inherits the default render mode from its parent. Therefore, the component is *statically rendered* on the server. The button isn't interactive and doesn't call the `UpdateMessage` method when selected. The value of `message` doesn't change, and the component isn't rerendered in response to UI events. + +`RenderMode1.razor`: + +```razor +@page "/render-mode-1" + + @message + +@code { + private string message = "Not clicked yet."; + + private void UpdateMessage() + { + message = "Somebody clicked me!"; + } +} +``` + +If using the preceding component locally in a Blazor Web App, place the component in the server-side project's `Components/Pages` folder. The server-side project is the solution's project with a name that doesn't end in `.Client`. When the app is running, navigate to `/render-mode-1` in the browser's address bar. + +## Server render mode + +The Server render mode renders the component interactively from the server using Blazor Server. User interactions are handled over a real-time connection with the browser. The circuit connection is established when the Server component is rendered. + +In the following example, the render mode is set to Server by adding `@attribute [RenderModeServer]` to the component definition. The button calls the `UpdateMessage` method when selected. The value of `message` changes, and the component is rerendered to update the message in the UI. + +`RenderMode2.razor`: + +```razor +@page "/render-mode-2" +@attribute [RenderModeServer] + + @message + +@code { + private string message = "Not clicked yet."; + + private void UpdateMessage() + { + message = "Somebody clicked me!"; + } +} +``` + +If using the preceding component locally in a Blazor Web App, place the component in the server-side project's `Components/Pages` folder. The server-side project is the solution's project with a name that doesn't end in `.Client`. When the app is running, navigate to `/render-mode-2` in the browser's address bar. + +## WebAssembly render mode + +The WebAssembly render mode renders the component interactively on the client using Blazor WebAssembly. The .NET runtime and app bundle are downloaded and cached when the WebAssembly component is initially rendered. Components using the WebAssembly render mode must be built from a separate client project that sets up the Blazor WebAssembly host. + +In the following example, the render mode is set to WebAssembly with `@attribute [RenderModeWebAssembly]`. The button calls the `UpdateMessage` method when selected. The value of `message` changes, and the component is rerendered to update the message in the UI. + +`RenderMode3.razor`: + +```razor +@page "/render-mode-3" +@attribute [RenderModeWebAssembly] + + @message + +@code { + private string message = "Not clicked yet."; + + private void UpdateMessage() + { + message = "Somebody clicked me!"; + } +} +``` + +If using the preceding component locally in a Blazor Web App, place the component in the client-side project's `Pages` folder. The client-side project is the solution's project with a name that ends in `.Client`. When the app is running, navigate to `/render-mode-3` in the browser's address bar. + +## Auto render mode + +The Auto render mode determines how to render the component at runtime. The component is initially rendered server-side with interactivity using the Blazor Server hosting model. The .NET runtime and app bundle are downloaded to the client in the background and cached so that they can be used on future visits. Components using the Auto render mode must be built from a separate client project that sets up the Blazor WebAssembly host. + +In the following example, the component is interactive throughout the process. The button calls the `UpdateMessage` method when selected. The value of `message` changes, and the component is rerendered to update the message in the UI. Initially, the component is rendered interactively from the server, but on subsequent visits it's rendered from the client after the .NET runtime and app bundle are downloaded and cached. + +`RenderMode4.razor`: + +```razor +@page "/render-mode-4" +@attribute [RenderModeAuto] + + @message + +@code { + private string message = "Not clicked yet."; + + private void UpdateMessage() + { + message = "Somebody clicked me!"; + } +} +``` + +If using the preceding component locally in a Blazor Web App, place the component in the client-side project's `Pages` folder. The client-side project is the solution's project with a name that ends in `.Client`. When the app is running, navigate to `/render-mode-4` in the browser's address bar. + +## Render mode propagation + +Render modes propagate down the component hierarchy. + +Rules for applying render modes: + +* The default render mode is Static. +* The interactive Server, WebAssembly, and Auto render modes can be used from a Static component, including using different render modes for sibling components. +* You can't switch to a different interactive render mode in a child component. For example, a Server component can't be a child of a WebAssembly component. +* Parameters passed to an interactive child component from a Static parent must be JSON serializable. This means that you can't pass render fragments or child content from a Static parent component to an interactive child component. + +The following examples use a non-routable, non-page `SharedMessage` component. The render mode agnostic `SharedMessage` component doesn't apply a render mode with an [`@attribute` directive](xref:mvc/views/razor#attribute). If you're testing these scenarios with a Blazor Web App, place the following component in the app's `Components` folder. + +`SharedMessage.razor`: + +```razor +

@Greeting

+ + @message + +

@ChildContent

+ +@code { + private string message = "Not clicked yet."; + + [Parameter] + public RenderFragment? ChildContent { get; set; } + + [Parameter] + public string Greeting { get; set; } = "Hello!"; + + private void UpdateMessage() + { + message = "Somebody clicked me!"; + } +} +``` + +### Render mode inheritance + +If the `SharedMessage` component is placed in a statically-rendered parent component, the `SharedMessage` component is also rendered statically and isn't interactive. The button doesn't call `UpdateMessage`, and the message isn't updated. + +`RenderMode5.razor`: + +```razor +@page "/render-mode-5" + + +``` + +If the `SharedMessage` component is placed in a component that defines the render mode, it inherits the applied render mode. + +In the following example, the `SharedMessage` component is interactive over a SignalR connection to the client. The button calls `UpdateMessage`, and the message is updated. + +`RenderMode6.razor`: + +```razor +@page "/render-mode-6" +@attribute [RenderModeServer] + + +``` + +### Child components with different render modes + +In the following example, both `SharedMessage` components are prerendered (by default) and appear when the page is displayed in the browser. + +* The first `SharedMessage` component with Server rendering is interactive after the SignalR circuit is established. +* The second `SharedMessage` component with WebAssembly rendering is interactive *after* the Blazor app bundle is downloaded and the .NET runtime is active on the client. + +`RenderMode7.razor`: + +```razor +@page "/render-mode-7" + + + +``` + +### Child component with a serializable parameter + +The following example demonstrates an interactive child component that takes a parameter. Parameters must be serializable. + +`RenderMode8.razor`: + +```razor +@page "/render-mode-8" + + +``` + +Non-serializable component parameters, such as child content or a render fragment, are ***not*** supported. In the following example, passing child content to the `SharedMessage` component results in a runtime error. + +`RenderMode9.razor`: + +```razor +@page "/render-mode-9" + + + Child content + +``` + + **Error**: + +> :::no-loc text="System.InvalidOperationException: Cannot pass the parameter 'ChildContent' to component 'SharedMessage' with rendermode 'ServerRenderMode'. This is because the parameter is of the delegate type 'Microsoft.AspNetCore.Components.RenderFragment', which is arbitrary code and cannot be serialized."::: + +To circumvent the preceding limitation, wrap the child component in another component that doesn't have the parameter. This is the approach taken in the Blazor Web App project template with the `Routes` component (`Components/Routes.razor`) to wrap the Blazor router. + +`WrapperComponent.razor`: + +```razor + + Child content + +``` + +`RenderMode10.razor`: + +```razor +@page "/render-mode-10" + + +``` + +In the preceding example: + +* The child content is passed to the `SharedMessage` component without generating a runtime error. +* The `SharedMessage` component renders interactively on the server. + +### Child component with a different render mode than its parent + +Don't try to apply a different interactive render mode to a child component than its parent's render mode. + +The following component results in a runtime error when the component is rendered: + +`RenderMode11.razor`: + +```razor +@page "/render-mode-11" +@attribute [RenderModeServer] + + +``` + + **Error**: + +> :::no-loc text="Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.WebAssemblyRenderMode' is not supported by interactive server-side rendering."::: + +## Set the render mode for the entire app + +To set the render mode for the entire app, indicate the render mode at the highest-level component in the app's component hierarchy that isn't a root component (root components can't be interactive). Typically, this is where the `Routes` component is used in the `App` component (`Components/App.razor`) for apps based on the Blazor Web App project template: + +```razor + +``` + +> [!NOTE] +> The preceding syntax will be simplified in an upcoming preview release. + +The Blazor router propagates its render mode to the pages it routes. The pages aren't technically child components of the router, but when the routes are discovered at runtime for the router, they inherit the router's render mode. + +You also typically must set the same interactive render mode on the `HeadOutlet` component, which is also found in the `App` component of a Blazor Web App generated from the project template: + +``` + +``` + +> [!NOTE] +> Making a root component interactive, such as the `App` component, isn't supported because the Blazor script may be evaluated multiple times. + +> [!NOTE] +> In an upcoming preview release, a template option for the Blazor Web App template to create the app with root-level interactivity. + + diff --git a/aspnetcore/blazor/fundamentals/index.md b/aspnetcore/blazor/fundamentals/index.md index 8bdc6741057a..f0698c9275fc 100644 --- a/aspnetcore/blazor/fundamentals/index.md +++ b/aspnetcore/blazor/fundamentals/index.md @@ -38,8 +38,6 @@ The following is an example counter component and part of an app created from a `Counter.razor`: - - :::moniker range=">= aspnetcore-7.0" :::code language="razor" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Pages/Counter.razor"::: diff --git a/aspnetcore/blazor/hosting-models.md b/aspnetcore/blazor/hosting-models.md index 8ae2f80749e8..48ae924d54f3 100644 --- a/aspnetcore/blazor/hosting-models.md +++ b/aspnetcore/blazor/hosting-models.md @@ -18,9 +18,31 @@ NOTE: Daggered lines under the table (†, ‡) use a double-space at --> -This article explains the different Blazor hosting models and how to choose which one to use. +:::moniker range=">= aspnetcore-8.0" -:::moniker range=">= aspnetcore-6.0" +This article explains Blazor hosting models, which can be applied in different parts of a Blazor app at either compile time or runtime. + +:::moniker-end + +:::moniker range="< aspnetcore-8.0" + +This article explains Blazor hosting models and how to choose which one to use. + +:::moniker-end + +:::moniker range=">= aspnetcore-8.0" + +Blazor is a web framework for building web UI components ([Razor components](xref:blazor/components/index)) that can be hosted in different ways: + +* Server-side in ASP.NET Core (*Blazor Server* or statically rendered). +* Client-side in the browser on a [WebAssembly](https://webassembly.org/)-based .NET runtime (*Blazor WebAssembly*). +* Client-side in a native mobile or desktop app that renders components to an embedded Web View control (*Blazor Hybrid*). + +Regardless of the hosting model, the way you build Razor components *is the same*. The same Razor components can be used with any of the hosting models unchanged. + +:::moniker-end + +:::moniker range=">= aspnetcore-6.0 < aspnetcore-8.0" Blazor is a web framework for building web UI components ([Razor components](xref:blazor/components/index)) that can be hosted in different ways. Razor components can run server-side in ASP.NET Core (*Blazor Server*) versus client-side in the browser on a [WebAssembly](https://webassembly.org/)-based .NET runtime (*Blazor WebAssembly*, *Blazor WASM*). You can also host Razor components in native mobile and desktop apps that render to an embedded Web View control (*Blazor Hybrid*). Regardless of the hosting model, the way you build Razor components *is the same*. The same Razor components can be used with any of the hosting models unchanged. @@ -34,38 +56,50 @@ Blazor is a web framework for building web UI components ([Razor components](xre ## Blazor Server -With the Blazor Server hosting model, the app is executed on the server from within an ASP.NET Core app. UI updates, event handling, and JavaScript calls are handled over a [SignalR](xref:signalr/introduction) connection using the [WebSockets protocol](xref:fundamentals/websockets). The state on the server associated with each connected client is called a *circuit*. Circuits aren't tied to a specific network connection and can tolerate temporary network interruptions and attempts by the client to reconnect to the server when the connection is lost. +With the Blazor Server hosting model, components are executed on the server from within an ASP.NET Core app. UI updates, event handling, and JavaScript calls are handled over a [SignalR](xref:signalr/introduction) connection using the [WebSockets protocol](xref:fundamentals/websockets). The state on the server associated with each connected client is called a *circuit*. Circuits aren't tied to a specific network connection and can tolerate temporary network interruptions and attempts by the client to reconnect to the server when the connection is lost. -In a traditional server-rendered app, opening the same app in multiple browser screens (tabs or `iframes`) typically doesn't translate into additional resource demands on the server. In a Blazor Server app, each browser screen requires a separate circuit and separate instances of server-managed component state. Blazor considers closing a browser tab or navigating to an external URL a *graceful* termination. In the event of a graceful termination, the circuit and associated resources are immediately released. A client may also disconnect non-gracefully, for instance due to a network interruption. Blazor Server stores disconnected circuits for a configurable interval to allow the client to reconnect. +In a traditional server-rendered app, opening the same app in multiple browser screens (tabs or `iframes`) typically doesn't translate into additional resource demands on the server. For the Blazor Server hosting model, each browser screen requires a separate circuit and separate instances of server-managed component state. Blazor considers closing a browser tab or navigating to an external URL a *graceful* termination. In the event of a graceful termination, the circuit and associated resources are immediately released. A client may also disconnect non-gracefully, for instance due to a network interruption. Blazor Server stores disconnected circuits for a configurable interval to allow the client to reconnect. -![The browser interacts with the app (hosted inside of an ASP.NET Core app) on the server over a SignalR connection.](~/blazor/hosting-models/_static/blazor-server.png) +![The browser interacts with Blazor (hosted inside of an ASP.NET Core app) on the server over a SignalR connection.](~/blazor/hosting-models/_static/blazor-server.png) -On the client, the Blazor script (`blazor.server.js`) establishes the SignalR connection with the server. The script is served to the client-side app from an embedded resource in the ASP.NET Core shared framework. The client-side app is responsible for persisting and restoring app state as required. +On the client, the Blazor script establishes the SignalR connection with the server. The script is served from an embedded resource in the ASP.NET Core shared framework. The Blazor Server hosting model offers several benefits: -* Download size is significantly smaller than a Blazor WebAssembly app, and the app loads much faster. +* Download size is significantly smaller than when the Blazor WebAssembly hosting model is used, and the app loads much faster. * The app takes full advantage of server capabilities, including the use of .NET Core APIs. * .NET Core on the server is used to run the app, so existing .NET tooling, such as debugging, works as expected. -* Thin clients are supported. For example, Blazor Server apps work with browsers that don't support WebAssembly and on resource-constrained devices. +* Thin clients are supported. For example, Blazor Server works with browsers that don't support WebAssembly and on resource-constrained devices. * The app's .NET/C# code base, including the app's component code, isn't served to clients. The Blazor Server hosting model has the following limitations: * Higher latency usually exists. Every user interaction involves a network hop. -* There's no offline support. If the client connection fails, the app stops working. +* There's no offline support. If the client connection fails, interactivity fails. * Scaling apps with many users requires server resources to handle multiple client connections and client state. * An ASP.NET Core server is required to serve the app. Serverless deployment scenarios aren't possible, such as serving the app from a Content Delivery Network (CDN). -We recommend using the [Azure SignalR Service](/azure/azure-signalr) for Blazor Server apps. The service allows for scaling up a Blazor Server app to a large number of concurrent SignalR connections. +We recommend using the [Azure SignalR Service](/azure/azure-signalr) for apps that adopt the Blazor Server hosting model. The service allows for scaling up a Blazor Server app to a large number of concurrent SignalR connections. ## Blazor WebAssembly -Blazor WebAssembly (WASM) apps run client-side in the browser on a WebAssembly-based .NET runtime. The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser. The app is executed directly on the browser UI thread. UI updates and event handling occur within the same process. The app's assets are deployed as static files to a web server or service capable of serving static content to clients. +The Blazor WebAssembly hosting model runs components client-side in the browser on a WebAssembly-based .NET runtime. Razor components, their dependencies, and the .NET runtime are downloaded to the browser. Components are executed directly on the browser UI thread. UI updates and event handling occur within the same process. Assets are deployed as static files to a web server or service capable of serving static content to clients. + +![Blazor WebAssembly: Blazor runs on a UI thread inside the browser.](~/blazor/hosting-models/_static/blazor-webassembly.png) -![Blazor WebAssembly: The Blazor app runs on a UI thread inside the browser.](~/blazor/hosting-models/_static/blazor-webassembly.png) +:::moniker range=">= aspnetcore-8.0" -When the Blazor WebAssembly app is created for deployment without a backend ASP.NET Core app to serve its files, the app is called a *standalone* Blazor WebAssembly app. When the app is created for deployment with a backend app to serve its files, the app is called a *hosted* Blazor WebAssembly app. +Blazor web apps can use the Blazor WebAssembly hosting model to enable client-side interactivity. When an app is created that exclusively runs on the Blazor WebAssembly hosting model without server-side rendering and interactivity, the app is called a *standalone* Blazor WebAssembly app. + +:::moniker-end + +:::moniker range="< aspnetcore-8.0" + +When the Blazor WebAssembly app is created for deployment without a backend ASP.NET Core app to serve its files, the app is called a *standalone* Blazor WebAssembly app. + +:::moniker-end + +When a standalone Blazor WebAssembly app uses a backend ASP.NET Core app to serve its files, the app is called a *hosted* Blazor WebAssembly app. Using hosted Blazor WebAssembly, you get a full-stack web development experience with .NET, including the ability to share code between the client and server apps, support for prerendering, and integration with MVC and Razor Pages. A hosted client app can interact with its backend server app over the network using a variety of messaging frameworks and protocols, such as [web API](xref:web-api/index), [gRPC-web](xref:grpc/index), and [SignalR](xref:signalr/introduction) (). :::moniker range=">= aspnetcore-6.0" @@ -73,26 +107,24 @@ A Blazor WebAssembly app built as a [Progressive Web App (PWA)](xref:blazor/prog :::moniker-end -Using hosted Blazor WebAssembly, you get a full-stack web development experience with .NET, including the ability to share code between the client and server apps, support for prerendering, and integration with MVC and Razor Pages. A hosted client app can interact with its backend server app over the network using a variety of messaging frameworks and protocols, such as [web API](xref:web-api/index), [gRPC-web](xref:grpc/index), and [SignalR](xref:signalr/introduction) (). - -The `blazor.webassembly.js` script is provided by the framework and handles: +The Blazor script handles: -* Downloading the .NET runtime, the app, and the app's dependencies. -* Initialization of the runtime to run the app. +* Downloading the .NET runtime, Razor components, and the component's dependencies. +* Initialization of the runtime. -The Blazor WebAssembly (WASM) hosting model offers several benefits: +The Blazor WebAssembly hosting model offers several benefits: -* There's no .NET server-side dependency after the app is downloaded from the server, so the app remains functional if the server goes offline. +* For standalone Blazor WebAssembly apps, there's no .NET server-side dependency after the app is downloaded from the server, so the app remains functional if the server goes offline. * Client resources and capabilities are fully leveraged. * Work is offloaded from the server to the client. -* An ASP.NET Core web server isn't required to host the app. Serverless deployment scenarios are possible, such as serving the app from a Content Delivery Network (CDN). +* For standalone Blazor WebAssembly apps, an ASP.NET Core web server isn't required to host the app. Serverless deployment scenarios are possible, such as serving the app from a Content Delivery Network (CDN). The Blazor WebAssembly hosting model has the following limitations: -* The app is restricted to the capabilities of the browser. +* Razor components are restricted to the capabilities of the browser. * Capable client hardware and software (for example, WebAssembly support) is required. -* Download size is larger, and apps take longer to load. -* The app's code can't be protected from inspection and tampering by users. +* Download size is larger, and components take longer to load. +* Code sent to the client can't be protected from inspection and tampering by users. :::moniker range=">= aspnetcore-8.0" @@ -102,13 +134,11 @@ The .NET [Intermediate Language (IL)](/dotnet/standard/glossary#il) interpreter :::moniker range=">= aspnetcore-6.0" -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. For more information, see . +Blazor 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. For more information, see . -The same [.NET WebAssembly build tools](xref:blazor/tooling#net-webassembly-build-tools) used for AOT compilation also [relink the .NET WebAssembly runtime](xref:blazor/host-and-deploy/webassembly#runtime-relinking) to trim unused runtime code. +The same [.NET WebAssembly build tools](xref:blazor/tooling#net-webassembly-build-tools) used for AOT compilation also [relink the .NET WebAssembly runtime](xref:blazor/host-and-deploy/webassembly#runtime-relinking) to trim unused runtime code. Blazor also trims unused code from .NET framework libraries. The .NET compiler further precompresses a static Blazor WebAssembly app for a smaller app payload. -Blazor WebAssembly includes support for trimming unused code from .NET Core framework libraries. For more information, see . The .NET compiler further precompresses a Blazor WebAssembly app for a smaller app payload. - -Blazor WebAssembly apps can use [native dependencies](xref:blazor/webassembly-native-dependencies) built to run on WebAssembly. +WebAssembly-rendered Razor components can use [native dependencies](xref:blazor/webassembly-native-dependencies) built to run on WebAssembly. :::moniker-end @@ -153,8 +183,18 @@ For more information on Microsoft native client frameworks, see the following re ## Which Blazor hosting model should I choose? +:::moniker range=">= aspnetcore-8.0" + +A component's hosting model is set by its *render mode*, either at compile time or runtime, which is described with examples in . The following table shows the primary considerations for setting the render mode to determine a component's hosting model. For standalone Blazor WebAssembly apps, all of the app's components are rendered on the client with the Blazor WebAssembly hosting model. + +:::moniker-end + +:::moniker range="< aspnetcore-8.0" + Select the Blazor hosting model based on the app's feature requirements. The following table shows the primary considerations for selecting the hosting model. +:::moniker-end + :::moniker range=">= aspnetcore-6.0" Blazor Hybrid apps include .NET MAUI, WPF, and Windows Forms framework apps. @@ -203,7 +243,13 @@ To create a Blazor Hybrid app, see the articles under article. We don't recommend that you jump from this article directly to the *Render modes* article without reading the content in the articles between these two articles. For example, render modes are more easily understood by looking at Razor component examples, but basic Razor component structure and function isn't covered until the article is reached. It's also helpful to learn about Blazor's project templates and tooling before working with the component examples in the *Render modes* article. + +:::moniker-end + ## Additional resources :::moniker range=">= aspnetcore-6.0" diff --git a/aspnetcore/mvc/views/razor.md b/aspnetcore/mvc/views/razor.md index bfd3878039fa..5c92d5ffce6c 100644 --- a/aspnetcore/mvc/views/razor.md +++ b/aspnetcore/mvc/views/razor.md @@ -728,6 +728,47 @@ When set to `false` (default), whitespace in the rendered markup from Razor comp :::moniker-end +:::moniker range=">= aspnetcore-8.0" + +### `@rendermode` + +*This scenario only applies to Razor components (`.razor`).* + + + +Sets the render mode of a Razor component: + +* `Server`: Applies interactive server rendering using Blazor Server. +* `WebAssembly`: Applies interactive client rendering using Blazor WebAssembly. +* `Auto`: Initially applies interactive client rendering using Blazor Server, and then applies interactive client rendering using WebAssembly on subsequent visits after the Blazor bundle is downloaded. + +The following example sets the Server render mode to a `Dialog` component: + +```razor + +``` + +To disable prerendering, pass the `prerender` flag with a value of `false`: + +```razor + +``` + +> [!NOTE] +> During .NET 8 *Release Candidate 1*, use the following values: +> +> Render mode | Value +> ----------- | ----- +> Server | `@RenderMode.Server` or `@(new ServerRenderMode(prerender: false))` +> WebAssembly | `@RenderMode.WebAssembly` or `@(new WebAssemblyRenderMode(prerender: false))` +> Auto | `@RenderMode.Auto` or `@(new AutoRenderMode(prerender: false))` +> +> The preceding syntax will be simplified in an upcoming preview release. + +For more information, see . + +:::moniker-end + ### `@section` *This scenario only applies to MVC views and Razor Pages (`.cshtml`).* diff --git a/aspnetcore/release-notes/aspnetcore-8.0.md b/aspnetcore/release-notes/aspnetcore-8.0.md index eef800ac57de..16fbfa3433d4 100644 --- a/aspnetcore/release-notes/aspnetcore-8.0.md +++ b/aspnetcore/release-notes/aspnetcore-8.0.md @@ -4,7 +4,7 @@ author: rick-anderson description: Learn about the new features in ASP.NET Core 8.0. ms.author: riande ms.custom: mvc -ms.date: 9/8/2023 +ms.date: 9/10/2023 uid: aspnetcore-8 --- # What's new in ASP.NET Core 8.0 @@ -20,16 +20,203 @@ This article is under development and not complete. More information may be foun * [What's new in .NET 8 Preview 4](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-4/) * [What's new in .NET 8 Preview 5](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-5/) * [What's new in .NET 8 Preview 6](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-6/) - [!INCLUDE [](~/includes/preview-notice.md)] - + +### Render Razor components outside of ASP.NET Core + +You can now render Razor components outside the context of an HTTP request. You can render Razor components as HTML directly to a string or stream independently of the ASP.NET Core hosting environment. This is convenient for scenarios where you want to generate HTML fragments, such as for a generating email or static site content. + +For more information, see . + +### Sections support + +The new `SectionOutlet` and `SectionContent` components in Blazor add support for specifying outlets for content that can be filled in later. Sections are often used to define placeholders in layouts that are then filled in by specific pages. Sections are referenced either by a unique name or using a unique object ID. + +For more information, see . + +### QuickGrid + +The Blazor QuickGrid component is no longer experimental and is now part of the Blazor framework in .NET 8. + +QuickGrid is a high performance grid component for displaying data in tabular form. QuickGrid is built to be a simple and convenient way to display your data, while still providing powerful features, such as sorting, filtering, paging, and virtualization. + +For more information, see . + +### Route to named elements + +Blazor now supports using client-side routing to navigate to a specific HTML element on a page using standard URL fragments. If you specify an identifier for an HTML element using the standard `id` attribute, Blazor correctly scrolls to that element when the URL fragment matches the element identifier. + +For more information, see . + +### Root-level cascading values + +Root-level cascading values can be registered for the entire component hierarchy. Named cascading values and subscriptions for update notifications are supported. + +For more information, see . + +### Virtualize empty content + +Use the new `EmptyContent` parameter on the `Virtualize` component to supply content when the component has loaded and either `Items` is empty or `ItemsProviderResult.TotalItemCount` is zero. + +For more information, see . + +### Monitor SignalR circuit activity + +You can now monitor inbound circuit activity in server-side apps using the new `CreateInboundActivityHandler` method on `CircuitHandler`. Inbound circuit activity is any activity sent from the browser to the server, such as UI events or JavaScript-to-.NET interop calls. + +For more information, see . + +### Faster runtime performance with the Jiterpreter + +The *Jiterpreter* is a new runtime feature in .NET 8 that enables partial Just-in-Time (JIT) compilation support when running on WebAssembly to achieve improved runtime performance. + +For more information, see . +### Ahead-of-time (AOT) SIMD and exception handling + +Blazor WebAssembly ahead-of-time (AOT) compilation now uses [WebAssembly Fixed-width SIMD](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md) and [WebAssembly Exception handling](https://github.com/WebAssembly/exception-handling/blob/master/proposals/exception-handling/Exceptions.md) by default to improve runtime performance. + +For more information, see the following: + +[AOT: Single Instruction, Multiple Data (SIMD)](xref:blazor/tooling?view=aspnetcore-8.0&pivots=windows&preserve-view=true#single-instruction-multiple-data-simd) +[AOT: Exception handling](xref:blazor/tooling?view=aspnetcore-8.0&pivots=windows&preserve-view=true#exception-handling) + +### Web-friendly Webcil packaging + +Webcil is web-friendly packaging of .NET assemblies that removes content specific to native Windows execution to avoid issues when deploying to environments that block the download or use of `.dll` files. Webcil is enabled by default for Blazor WebAssembly apps. + +For more information, see . + +### Blazor WebAssembly debugging improvements + +When debugging .NET on WebAssembly, the debugger now downloads symbol data from symbol locations that are configured in Visual Studio preferences. This improves the debugging experience for apps that use NuGet packages. + +You can now debug Blazor WebAssembly apps using Firefox. Debugging Blazor WebAssembly apps requires configuring the browser for remote debugging and then connecting to the browser using the browser developer tools through the .NET WebAssembly debugging proxy. Debugging Firefox from Visual Studio isn't supported at this time. + +For more information, see . + +### Content Security Policy (CSP) compatibility + +Blazor WebAssembly no longer requires enabling the `unsafe-eval` script source when specifying a Content Security Policy (CSP). + +For more information, see . + +### Handle caught exceptions outside of a Razor component's lifecycle + +Use `ComponentBase.DispatchExceptionAsync` in a Razor component to process exceptions thrown outside of the component's lifecycle call stack. This permits the component's code to treat exceptions as though they're lifecycle method exceptions. Thereafter, Blazor's error handling mechanisms, such as error boundaries, can process exceptions. + +For more information, see . + + + + +### Configuration of connection timeouts in `HubConnectionBuilder` + +Prior workarounds for configuring hub connection timeouts can be replaced with formal SignalR hub connection builder timeout configuration. + +For more information, see the following: + +* +* +* + +### Project templates shed Open Iconic + +[Open Iconic](https://github.com/iconic/open-iconic) on GitHub has been abandoned by its maintainers, so project templates for .NET 8 or later adopt Bootstrap for app icons. + ## SignalR ### New approach to set the server timeout and Keep-Alive interval diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index d8a6ef4f61ac..131511d280b4 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -447,6 +447,8 @@ items: items: - name: Overview uid: blazor/components/index + - name: Render modes + uid: blazor/components/render-modes - name: Generic type support uid: blazor/components/generic-type-support - name: Synchronization context