From 342e82fc2a8012621a19f42bf527dca074b25f84 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 1 Dec 2023 10:22:25 -0500 Subject: [PATCH 1/2] Terminology consistency updates --- aspnetcore/blazor/call-web-api.md | 6 +- .../cascading-values-and-parameters.md | 8 +-- ...raries-and-static-server-side-rendering.md | 2 +- aspnetcore/blazor/components/index.md | 2 +- aspnetcore/blazor/components/integration.md | 57 +++++++++---------- aspnetcore/blazor/components/quickgrid.md | 2 +- aspnetcore/blazor/components/render-modes.md | 56 +++++++++--------- aspnetcore/blazor/components/rendering.md | 4 +- aspnetcore/blazor/forms/index.md | 10 ++-- .../blazor/fundamentals/handle-errors.md | 2 +- aspnetcore/blazor/fundamentals/index.md | 19 ++++--- aspnetcore/blazor/fundamentals/routing.md | 6 +- aspnetcore/blazor/fundamentals/signalr.md | 8 +-- aspnetcore/blazor/fundamentals/startup.md | 2 +- .../blazor/globalization-localization.md | 8 +-- .../blazor/host-and-deploy/webassembly.md | 6 +- aspnetcore/blazor/hosting-models.md | 2 +- ...cation-client-and-server-net31-or-later.md | 4 +- ...ocation-client-and-server-net6-or-later.md | 4 +- ...ocation-client-and-server-net7-or-later.md | 4 +- ...ocation-client-and-server-net8-or-later.md | 4 +- aspnetcore/blazor/index.md | 4 +- .../static-server-rendering.md | 8 +-- aspnetcore/blazor/project-structure.md | 6 +- aspnetcore/blazor/security/index.md | 4 +- aspnetcore/blazor/security/server/index.md | 2 +- .../server/static-server-side-rendering.md | 2 +- aspnetcore/blazor/tooling.md | 41 ++++++++----- 28 files changed, 148 insertions(+), 135 deletions(-) diff --git a/aspnetcore/blazor/call-web-api.md b/aspnetcore/blazor/call-web-api.md index d5dd5629f61a..1509658666d4 100644 --- a/aspnetcore/blazor/call-web-api.md +++ b/aspnetcore/blazor/call-web-api.md @@ -23,7 +23,7 @@ This article describes how to call a web API from a Blazor app. :::zone pivot="webassembly" > [!NOTE] -> This article has loaded **WebAssembly** render mode coverage for calling web APIs. The [Server render mode coverage](?pivots=server) addresses the following subjects: +> This article has loaded **WebAssembly** client-side rendering (CSR) coverage for calling web APIs. The [coverage for **Server** interactive server-side rendering (interactive SSR)](?pivots=server) addresses the following subjects: > > * Use of the `HttpClient` factory infrastructure to provide an `HttpClient` to the app. > * Cross-Origin Resource Sharing (CORS) pertaining to server-side components. @@ -61,7 +61,7 @@ The Blazor examples that demonstrate obtaining weather data from a server API ar :::moniker range=">= aspnetcore-8.0" -For server-side components in Blazor Web Apps that require interactivity, add Interactive Server rendering to the component: +For server-side components in Blazor Web Apps that require interactivity, add interactive server-side rendering (interactive SSR) to the component: ```razor @rendermode InteractiveServer @@ -750,7 +750,7 @@ For more information, see . :::zone pivot="server" > [!NOTE] -> This article has loaded **Server** render mode coverage for calling web APIs. The [WebAssembly render mode coverage](?pivots=webassembly) addresses the following subjects: +> This article has loaded **Server** interactive server-side rendering (interactive SSR) coverage for calling web APIs. The [**WebAssembly** client-side rendering (CSR) coverage](?pivots=webassembly) addresses the following subjects: > > * Client-side examples that call a web API to create, read, update, and delete todo list items. > * `System.Net.Http.Json` package. diff --git a/aspnetcore/blazor/components/cascading-values-and-parameters.md b/aspnetcore/blazor/components/cascading-values-and-parameters.md index 8b07a4d9fbca..26ad49f72027 100644 --- a/aspnetcore/blazor/components/cascading-values-and-parameters.md +++ b/aspnetcore/blazor/components/cascading-values-and-parameters.md @@ -151,7 +151,7 @@ Wrap the markup of the `Routes` component in a [`CascadingValue`](xref:Microsoft } ``` -In the `App` component (`Components/App.razor`), adopt an interactive render mode for the entire app. The following example adopts Interactive Server rendering: +In the `App` component (`Components/App.razor`), adopt an interactive render mode for the entire app. The following example adopts interactive server-side rendering (interactive SSR): ```razor @@ -317,10 +317,10 @@ Similar to a regular component parameter, components accepting a cascading param Cascading parameters don't pass data across render mode boundaries: -* Interactive sessions run in a different context than the Static Server-rendered pages. There's no requirement that the server producing the page is even the same machine that hosts some later Interactive Server session, including for WebAssembly components where the server is a different machine to the client. The benefit of Static Server rendering is to gain the full performance of pure stateless HTML rendering. +* Interactive sessions run in a different context than the pages that use static server-side rendering (static SSR). There's no requirement that the server producing the page is even the same machine that hosts some later Interactive Server session, including for WebAssembly components where the server is a different machine to the client. The benefit of static server-side rendering (static SSR) is to gain the full performance of pure stateless HTML rendering. -* State crossing the boundary between static and interactive rendering must be serializable. Components are arbitrary objects that reference a vast chain of other objects, including the renderer, the DI container, and every DI service instance. You must explicitly cause state to be serialized from Static Server rendering to make it available in subsequent interactively-rendered components. Two approaches are adopted: - * Via the Blazor framework, parameters passed across a Static Server rendering to interactive boundary are serialized automatically if they're JSON-serializable, or an error is thrown. +* State crossing the boundary between static and interactive rendering must be serializable. Components are arbitrary objects that reference a vast chain of other objects, including the renderer, the DI container, and every DI service instance. You must explicitly cause state to be serialized from static SSR to make it available in subsequent interactively-rendered components. Two approaches are adopted: + * Via the Blazor framework, parameters passed across a static SSR to interactive rendering boundary are serialized automatically if they're JSON-serializable, or an error is thrown. * State stored in [`PersistentComponentState`](xref:blazor/components/prerendering-and-integration#persist-prerendered-state) is serialized and recovered automatically if it's JSON-serializable, or an error is thrown. Cascading parameters aren't JSON-serialize because the typical usage patterns for cascading parameters are somewhat like DI services. There are often platform-specific variants of cascading parameters, so it would be unhelpful to developers if the framework stopped developers from having server-interactive-specific versions or WebAssembly-specific versions. Also, many cascading parameter values in general aren't serializable, so it would be impractical to update existing apps if you had to stop using all nonserializable cascading parameter values. diff --git a/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md b/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md index c0ebebaf08cc..9a90c98f8a6d 100644 --- a/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md +++ b/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md @@ -20,7 +20,7 @@ This article provides guidance for component library authors considering support Blazor encourages the development of an ecosystem of open-source and commercial component libraries, formally called *Razor class libraries (RCLs)*. Developers might also create reusable components for sharing components privately across apps within their own companies. Ideally, components are developed for compatibility with as many hosting models and rendering modes as possible. Static SSR introduces additional restrictions that can be more challenging to support than interactive rendering modes. -## Understand the capabilities and restrictions of Static SSR +## Understand the capabilities and restrictions of static SSR Static SSR is a mode in which components run when the server handles an incoming HTTP request. Blazor renders the component as HTML, which is included in the response. Once the response is sent, the server-side component and renderer state is discarded, so all that remains is HTML in the browser. diff --git a/aspnetcore/blazor/components/index.md b/aspnetcore/blazor/components/index.md index 71a4c2888000..358b4b4e77d4 100644 --- a/aspnetcore/blazor/components/index.md +++ b/aspnetcore/blazor/components/index.md @@ -907,7 +907,7 @@ Quote ©2005 [Universal Pictures](https://www.uphe.com): [Serenity](https:// ## Route parameters -Components can specify route parameters in the route template of the [`@page`][9] directive. The [Blazor Router](xref:blazor/fundamentals/routing) uses route parameters to populate corresponding component parameters. +Components can specify route parameters in the route template of the [`@page`][9] directive. The [Blazor router](xref:blazor/fundamentals/routing) uses route parameters to populate corresponding component parameters. :::moniker range=">= aspnetcore-5.0" diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index 3885ddb61378..08cbe3810d97 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -30,14 +30,14 @@ Use the guidance in the following sections depending on the project's requiremen This section covers adding Blazor support to an ASP.NET Core app: -* [Add Static Server Razor component rendering](#add-static-server-razor-component-rendering) -* [Enable Interactive Server rendering](#enable-interactive-server-rendering) -* [Enable interactive Auto or WebAssembly rendering](#enable-interactive-auto-and-webassembly-rendering) +* [Add static server-side rendering (static SSR)](#add-static-server-side-rendering-static-ssr) +* [Enable interactive server-side rendering (interactive SSR)](#enable-interactive-server-side-rendering-interactive-ssr) +* [Enable interactive automatic (Auto) or client-side rendering (CSR)](#enable-interactive-automatic-auto-or-client-side-rendering-csr) > [!NOTE] > For the examples in this section, the example app's name and namespace is `BlazorSample`. -### Add Static Server Razor component rendering +### Add static server-side rendering (static SSR) Add a `Components` folder to the app. @@ -60,7 +60,7 @@ Add the following `_Imports` file for namespaces used by Razor components. Change the namespace `BlazorSample` in the preceding example to match the app. -Add the Blazor Router (``, ) to the app in a `Routes` component, which is placed in the app's `Components` folder. +Add the Blazor router (``, ) to the app in a `Routes` component, which is placed in the app's `Components` folder. `Components/Routes.razor`: @@ -113,7 +113,7 @@ For the `` element in the preceding example, change `BlazorSample` in the Add a `Pages` folder to the `Components` folder to hold routable Razor components. -Add the following `Welcome` component to demonstrate Static Server rendering. +Add the following `Welcome` component to demonstrate static SSR. `Components/Pages/Welcome.razor`: @@ -162,27 +162,25 @@ In the ASP.NET Core project's `Program` file: When the app is run, the `Welcome` component is accessed at the `/welcome` endpoint. -### Enable Interactive Server rendering +### Enable interactive server-side rendering (interactive SSR) -Follow the guidance in the [Add Static Server Razor component rendering](#add-static-server-razor-component-rendering) section. +Follow the guidance in the [Add static server-side rendering (static SSR)](#add-static-server-side-rendering-static-ssr) section. -Make the following changes in the app's `Program` file: +In the app's `Program` file, add a call to where Razor component services are added with : -* Add a call to where Razor component services are added with : - - ```csharp - builder.Services.AddRazorComponents() - .AddInteractiveServerComponents(); - ``` +```csharp +builder.Services.AddRazorComponents() + .AddInteractiveServerComponents(); +``` -* Add a call to where Razor components are mapped with : +Also in the `Program` file, add a call to where Razor components are mapped with : - ```csharp - app.MapRazorComponents() - .AddInteractiveServerRenderMode(); - ``` +```csharp +app.MapRazorComponents() + .AddInteractiveServerRenderMode(); +``` -Add the following `Counter` component to the app that adopts the Interactive Server render mode. +Add the following `Counter` component to the app that adopts interactive server-side rendering (interactive SSR). `Components/Pages/Counter.razor`: @@ -210,16 +208,16 @@ Add the following `Counter` component to the app that adopts the Interactive Ser When the app is run, the `Counter` component is accessed at `/counter`. -### Enable interactive Auto and WebAssembly rendering +### Enable interactive automatic (Auto) or client-side rendering (CSR) -Follow the guidance in the [Add Static Server Razor component rendering](#add-static-server-razor-component-rendering) section. +Follow the guidance in the [Add static server-side rendering (static SSR)](#add-static-server-side-rendering-static-ssr) section. -Components using the Auto render mode initially use Interactive Server rendering, but then switch to render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Components using the WebAssembly render mode only render interactively on the client after the Blazor bundle is downloaded and the Blazor runtime activates. Keep in mind that when using the Auto or WebAssembly render modes, component code downloaded to the client is ***not*** private. For more information, see . +Components using the Interactive Auto render mode initially use interactive SSR, but then switch to render on the client after the Blazor bundle has been downloaded and the Blazor runtime activates. Components using the Interactive WebAssembly render mode only render interactively on the client after the Blazor bundle is downloaded and the Blazor runtime activates. Keep in mind that when using the Interactive Auto or Interactive WebAssembly render modes, component code downloaded to the client is ***not*** private. For more information, see . After deciding which render mode to adopt: -* If you plan to adopt the Auto render mode, follow the guidance in the [Enable Interactive Server rendering](#enable-interactive-server-rendering) section. -* If you plan to only adopt Interactive WebAssembly rendering, continue without adding Interactive Server rendering. +* If you plan to adopt the Interactive Auto render mode, follow the guidance in the [Enable interactive server-side rendering (interactive SSR)](#enable-interactive-server-side-rendering-interactive-ssr) section. +* If you plan to only adopt Interactive WebAssembly rendering, continue without adding interactive SSR. Add a package reference for the [`Microsoft.AspNetCore.Components.WebAssembly.Server`](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Server) NuGet package to the app. @@ -300,7 +298,7 @@ Make the following changes to the ASP.NET Core app's `Program` file: * Add the Interactive WebAssembly render mode () and additional assemblies for the `.Client` project where Razor components are mapped with . - For interactive Auto rendering: + For interactive automatic (Auto) rendering: ```csharp app.MapRazorComponents() @@ -430,7 +428,7 @@ builder.Services.AddRazorComponents() For more information on adding support for Interactive Server and WebAssembly components, see . -In the `Program` file immediately after the call to map Razor Pages (), call to discover available components and specify the app's root component (the first component loaded). By default, the app's root component is the `App` component (`App.razor`). Chain a call to `AddInteractiveInteractiveServerRenderMode` to configure the Server render mode for the app: +In the `Program` file immediately after the call to map Razor Pages (), call to discover available components and specify the app's root component (the first component loaded). By default, the app's root component is the `App` component (`App.razor`). Chain a call to `AddInteractiveInteractiveServerRenderMode` to configure interactive server-side rendering (interactive SSR) for the app: ```csharp app.MapRazorComponents() @@ -755,7 +753,7 @@ builder.Services.AddRazorComponents() For more information on adding support for Interactive Server and WebAssembly components, see . -In the `Program` file immediately after the call to map Razor Pages (), call to discover available components and specify the app's root component. By default, the app's root component is the `App` component (`App.razor`). Chain a call to to configure the Server render mode for the app: +In the `Program` file immediately after the call to map Razor Pages (), call to discover available components and specify the app's root component. By default, the app's root component is the `App` component (`App.razor`). Chain a call to to configure interactive server-side rendering (interactive SSR) for the app: ```csharp app.MapRazorComponents() @@ -851,4 +849,3 @@ For more information, see - diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index 610d42e92ec7..33eb3d47a5c6 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -80,7 +80,7 @@ For example, add the following component to render a grid. } ``` -The preceding example specifies server rendering (`@rendermode InteractiveServer`), which enables the `QuickGrid`'s interactive features. In this case, the only interactive feature is sortable columns. +The preceding example specifies interactive server-side rendering (interactive SSR) with `@rendermode InteractiveServer`, which enables the `QuickGrid`'s interactive features. In this case, the only interactive feature is sortable columns. For an example that uses an with Entity Framework Core as the queryable data source, see the [`SampleQuickGridComponent` component in the ASP.NET Core Basic Test App (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/src/Components/test/testassets/BasicTestApp/QuickGridTest/SampleQuickGridComponent.razor). diff --git a/aspnetcore/blazor/components/render-modes.md b/aspnetcore/blazor/components/render-modes.md index d6cca04b5ae1..b3800ded0275 100644 --- a/aspnetcore/blazor/components/render-modes.md +++ b/aspnetcore/blazor/components/render-modes.md @@ -29,10 +29,12 @@ The following table shows the available render modes for rendering Razor compone Name | Description | Render location | Interactive ---- | ----------- | :-------------: | :---------: -Static Server | Static server rendering | Server | -Interactive Server | Interactive server rendering using Blazor Server | Server | -Interactive WebAssembly | Interactive client rendering using Blazor WebAssembly | Client | -Interactive Auto | Interactive client rendering using Blazor Server initially and then WebAssembly on subsequent visits after the Blazor bundle is downloaded | Server, then client | +Static Server | Static server-side rendering (static SSR) | Server | +Interactive Server | Interactive server-side rendering (interactive SSR) using Blazor Server | Server | +Interactive WebAssembly | Client-side rendering (CSR) using Blazor WebAssembly† | Client | +Interactive Auto | Interactive SSR using Blazor Server initially and then CSR on subsequent visits after the Blazor bundle is downloaded | Server, then client | + +†Client-side rendering (CSR) is assumed to be interactive. "*Interactive* client-side rendering" and "*interactive* CSR" aren't used by the industry or in the Blazor documentation. Prerendering is enabled by default for interactive components. Guidance on controlling prerendering is provided later in this article. For general industry terminology on client and server rendering concepts, see . @@ -55,13 +57,13 @@ Component builder extensions: Endpoint convention builder extensions: -* configures the Server render mode for the app. -* configures the WebAssembly render mode for the app. +* configures interactive server-side rendering (interactive SSR) for the app. +* configures the Interactive 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: +Example 1: The following `Program` file API adds services and configuration for enabling interactive SSR: ```csharp builder.Services.AddRazorComponents() @@ -73,7 +75,7 @@ app.MapRazorComponents() .AddInteractiveServerRenderMode(); ``` -Example 2: The following `Program` file API adds services and configuration for enabling the WebAssembly render mode: +Example 2: The following `Program` file API adds services and configuration for enabling the Interactive WebAssembly render mode: ```csharp builder.Services.AddRazorComponents() @@ -85,7 +87,7 @@ app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` -Example 3: The following `Program` file API adds services and configuration for enabling the Interactive Server, WebAssembly, and Auto render modes: +Example 3: The following `Program` file API adds services and configuration for enabling the Interactive Server, Interactive WebAssembly, and Interactive Auto render modes: ```csharp builder.Services.AddRazorComponents() @@ -99,13 +101,13 @@ app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode(); ``` -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. +Blazor uses the Blazor WebAssembly hosting model to download and execute components that use the Interactive 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 Interactive 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#rendermode) where the component is used. -In the following example, the Server render mode is applied to the `Dialog` component instance: +In the following example, interactive server-side rendering (interactive SSR) is applied to the `Dialog` component instance: ```razor @@ -124,7 +126,7 @@ In the following example, the Server render mode is applied to the `Dialog` comp > > ``` -You can also reference static render mode instances instantiated directly with custom configuration. For more information, see the [Custom shorthand render modes](#custom-shorthand-render-modes) section later in this article. +You can also reference custom render mode instances instantiated directly with custom configuration. For more information, see the [Custom shorthand render modes](#custom-shorthand-render-modes) section later in this article. ## Apply a render mode to a component definition @@ -213,9 +215,9 @@ Also, disable prerendering for the [`HeadOutlet` component](xref:blazor/componen ``` -## Static render mode +## Static server-side rendering (static SSR) -By default, components use the Static render mode. The component renders to the response stream and interactivity isn't enabled. +By default, components use the static server-side rendering (static SSR). 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. @@ -238,13 +240,13 @@ In the following example, there's no designation for the component's render mode If using the preceding component locally in a Blazor Web App, place the component in the server project's `Components/Pages` folder. The server 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. -[Enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) with static rendering requires special attention when loading JavaScript. For more information, see . +[Enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling) with static SSR requires special attention when loading JavaScript. For more information, see . -## Server render mode +## Interactive server-side rendering (interactive SSR) -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. +Interactive server-side rendering (interactive SSR) 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 `@rendermode InteractiveServer` 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. +In the following example, the render mode is set interactive SSR by adding `@rendermode InteractiveServer` 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`: @@ -266,11 +268,11 @@ In the following example, the render mode is set to Server by adding `@rendermod If using the preceding component locally in a Blazor Web App, place the component in the server project's `Components/Pages` folder. The server 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 +## Client-side rendering (CSR) -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. +Client-side rendering (CSR) 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 CSR 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 `@rendermode InteractiveWebAssembly`. 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. +In the following example, the render mode is set to CSR with `@rendermode InteractiveWebAssembly`. 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`: @@ -292,9 +294,9 @@ In the following example, the render mode is set to WebAssembly with `@rendermod If using the preceding component locally in a Blazor Web App, place the component in the client project's `Pages` folder. The client 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 +## Automatic (Auto) rendering -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 automatic render mode must be built from a separate client project that sets up the Blazor WebAssembly host. +Automatic (Auto) rendering determines how to render the component at runtime. The component is initially rendered with interactive server-side rendering (interactive SSR) 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 automatic 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. @@ -390,7 +392,7 @@ Render modes propagate down the component hierarchy. Rules for applying render modes: * The default render mode is Static. -* The Interactive Server (), WebAssembly (), and automatic () render modes can be used from a Static component, including using different render modes for sibling components. +* The Interactive Server (), Interactive WebAssembly (), and Interactive Auto () render modes can be used from a 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. @@ -450,8 +452,8 @@ In the following example, the `SharedMessage` component is interactive over a Si 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. +* The first `SharedMessage` component with interactive server-side rendering (interactive SSR) is interactive after the SignalR circuit is established. +* The second `SharedMessage` component with client-side rendering (CSR) is interactive *after* the Blazor app bundle is downloaded and the .NET runtime is active on the client. `RenderMode7.razor`: @@ -550,7 +552,7 @@ Normally, a component uses the following `@attribute` directive to [disable prer @attribute [RenderModeInteractiveServer(prerender: false)] ``` -However, consider the following example that creates a shorthand Interactive Server render mode without prerendering via the app's `_Imports` file (`Components/_Imports.razor`): +However, consider the following example that creates a shorthand interactive server-side render mode without prerendering via the app's `_Imports` file (`Components/_Imports.razor`): ```csharp public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = diff --git a/aspnetcore/blazor/components/rendering.md b/aspnetcore/blazor/components/rendering.md index 6a3fd47e55af..6eb783f06389 100644 --- a/aspnetcore/blazor/components/rendering.md +++ b/aspnetcore/blazor/components/rendering.md @@ -45,13 +45,13 @@ For more information on the performance implications of the framework's conventi ## Streaming rendering -Use *streaming rendering* with [server rendering](xref:blazor/components/render-modes) to stream content updates on the response stream and improve the user experience for components that perform long-running asynchronous tasks to fully render. +Use *streaming rendering* with [interactive server-side rendering (interactive SSR)](xref:blazor/components/render-modes) to stream content updates on the response stream and improve the user experience for components that perform long-running asynchronous tasks to fully render. For example, consider a component that makes a long-running database query or web API call to render data when the page loads. Normally, asynchronous tasks executed as part of rendering a server-side component must complete before the rendered response is sent, which can delay loading the page. Any significant delay in rendering the page harms the user experience. To improve the user experience, streaming rendering initially renders the entire page quickly with placeholder content while asynchronous operations execute. After the operations are complete, the updated content is sent to the client on the same response connection and patched into the DOM. Streaming rendering requires the server to avoid buffering the output. The response data must to flow to the client as the data is generated. For hosts that enforce buffering, streaming rendering degrades gracefully, and the page loads without streaming rendering. -To stream content updates when using Static Server rendering, apply the `[StreamRendering(true)]` attribute to the component. Streaming rendering must be explicitly enabled because streamed updates may cause content on the page to shift. Components without the attribute automatically adopt streaming rendering if the parent component uses the feature. Pass `false` to the attribute in a child component to disable the feature at that point and further down the component subtree. The attribute is functional when applied to components supplied by a [Razor class library](xref:blazor/components/class-libraries). +To stream content updates when using static server-side rendering (static SSR), apply the `[StreamRendering(true)]` attribute to the component. Streaming rendering must be explicitly enabled because streamed updates may cause content on the page to shift. Components without the attribute automatically adopt streaming rendering if the parent component uses the feature. Pass `false` to the attribute in a child component to disable the feature at that point and further down the component subtree. The attribute is functional when applied to components supplied by a [Razor class library](xref:blazor/components/class-libraries). The following example is based on the `Weather` component in an app created from the [Blazor Web App project template](xref:blazor/project-structure#blazor-web-app). The call to simulates retrieving weather data asynchronously. The component initially renders placeholder content ("`Loading...`") without waiting for the asynchronous delay to complete. When the asynchronous delay completes and the weather data content is generated, the content is streamed to the response and patched into the weather forecast table. diff --git a/aspnetcore/blazor/forms/index.md b/aspnetcore/blazor/forms/index.md index ad0cfa79e28d..f0abcc293e6d 100644 --- a/aspnetcore/blazor/forms/index.md +++ b/aspnetcore/blazor/forms/index.md @@ -39,7 +39,7 @@ A project created from the Blazor project template includes the namespace by def :::moniker range=">= aspnetcore-8.0" -Standard interactive HTML forms with server rendering are supported. Create a form using the normal HTML `
` tag and specify an `@onsubmit` handler for handling the submitted form request. +Standard interactive HTML forms with interactive server-side rendering (`@rendermode InteractiveServer`) are supported. Create a form using the normal HTML `` tag and specify an `@onsubmit` handler for handling the submitted form request. `StarshipPlainForm.razor`: @@ -376,14 +376,14 @@ For guidance on using the `enhancedload` event to listen for enhanced page updat :::moniker range=">= aspnetcore-8.0" -Components are configured for interactivity with server rendering and enhanced navigation. For a client-side experience in a Blazor Web App, change the render mode in the `@rendermode` directive at the top of the component to either: +Components are configured for interactive server-side rendering (interactive SSR) and enhanced navigation. For a client-side experience in a Blazor Web App, change the render mode in the `@rendermode` directive at the top of the component to either: -* for only interactive client rendering after prerendering. -* for interactive client rendering after Interactive Server rendering, which operates while the Blazor app bundle downloads in the background and the .NET WebAssembly runtime starts on the client. +* for only client-side rendering (CSR) after prerendering. +* for CSR after interactive SSR, which operates while the Blazor app bundle downloads in the background and the .NET WebAssembly runtime starts on the client. If working with a standalone Blazor WebAssembly app, render modes aren't used. Blazor WebAssembly apps always run interactively on WebAssembly. The example interactive forms in this article function in a standalone Blazor WebAssembly app as long as the code doesn't make assumptions about running on the server instead of the client. You can remove the `@rendermode` directive from the component when using the example forms in a Blazor WebAssembly app. -When using the WebAssembly or Auto render modes, keep in mind that all of the component code is compiled and sent to the client, where users can decompile and inspect it. Don't place private code, app secrets, or other sensitive information in client-rendered components. +When using the Interactive WebAssembly or Interactive Auto render modes, keep in mind that all of the component code is compiled and sent to the client, where users can decompile and inspect it. Don't place private code, app secrets, or other sensitive information in client-rendered components. Examples don't adopt enhanced form handling for form POST requests, but all of the examples can be updated to adopt the enhanced features by following the guidance in the [Enhanced form handling](#enhanced-form-handling) section. diff --git a/aspnetcore/blazor/fundamentals/handle-errors.md b/aspnetcore/blazor/fundamentals/handle-errors.md index 9a2c267b7e2d..8361286b6b3e 100644 --- a/aspnetcore/blazor/fundamentals/handle-errors.md +++ b/aspnetcore/blazor/fundamentals/handle-errors.md @@ -387,7 +387,7 @@ In `MainLayout.razor`: :::moniker range=">= aspnetcore-8.0" -In Blazor Web Apps with the error boundary only applied to a noninteractive `MainLayout` component, the boundary is only active during the Static Server rendering phase. The boundary doesn't activate just because a component further down the component hierarchy is interactive. To enable interactivity broadly for the `MainLayout` component and the rest of the components further down the component hierarchy, enable interactivity with server rendering at the top of the `Routes` component (`Components/Routes.razor`): +In Blazor Web Apps with the error boundary only applied to a static `MainLayout` component, the boundary is only active during the static server-side rendering (static SSR) phase. The boundary doesn't activate just because a component further down the component hierarchy is interactive. To enable interactivity broadly for the `MainLayout` component and the rest of the components further down the component hierarchy, enable interactive server-side rendering (interactive SSR) at the top of the `Routes` component (`Components/Routes.razor`): ```razor @rendermode InteractiveServer diff --git a/aspnetcore/blazor/fundamentals/index.md b/aspnetcore/blazor/fundamentals/index.md index edfd39722374..c046939dd97c 100644 --- a/aspnetcore/blazor/fundamentals/index.md +++ b/aspnetcore/blazor/fundamentals/index.md @@ -20,11 +20,14 @@ Throughout the Blazor documentation, activity that takes place on the user's sys The term *rendering* means to produce the HTML markup that browsers display. -*Client-side rendering (CSR)* means that the final HTML markup is generated by the Blazor WebAssembly runtime on the client. No HTML for the app's client-generated UI is sent from a server to the client for this type of rendering. User interactivity with the page is assumed. There's no such concept as *static* client-side rendering. +* **Client-side rendering (CSR)** means that the final HTML markup is generated by the Blazor WebAssembly runtime on the client. No HTML for the app's client-generated UI is sent from a server to the client for this type of rendering. User interactivity with the page is assumed. There's no such concept as *static* client-side rendering. CSR is assumed to be interactive, so "*interactive* client-side rendering" and "*interactive* CSR" aren't used by the industry or the Blazor documentation. -*Server-side rendering (SSR)* means that the final HTML markup is generated by the ASP.NET Core runtime on the server. The HTML is sent to the client over a network for display by the client's browser. No HTML for the app's server-generated UI is created by the client for this type of rendering. SSR can be of two varieties: *static SSR*, where the server produces static HTML that doesn't provide for user interactivity or component state with Blazor, and *interactive SSR*, where Blazor events permit user interactivity and component state is maintained by the Blazor framework. +* **Server-side rendering (SSR)** means that the final HTML markup is generated by the ASP.NET Core runtime on the server. The HTML is sent to the client over a network for display by the client's browser. No HTML for the app's server-generated UI is created by the client for this type of rendering. SSR can be of two varieties: -*Prerendering* is the process of initially rendering page content on the server without enabling event handlers for rendered controls. The server outputs the HTML UI of the page as soon as possible in response to the initial request, which makes the app feel more responsive to users. Prerendering can also improve [Search Engine Optimization (SEO)](https://developer.mozilla.org/docs/Glossary/SEO) by rendering content for the initial HTTP response that search engines use to calculate page rank. Prerendering is always followed by final rendering, either on the server or the client. + * **Static SSR**: The server produces static HTML that doesn't provide for user interactivity or maintaining Razor component state. + * **Interactive SSR**: Blazor events permit user interactivity and Razor component state is maintained by the Blazor framework. + +* **Prerendering** is the process of initially rendering page content on the server without enabling event handlers for rendered controls. The server outputs the HTML UI of the page as soon as possible in response to the initial request, which makes the app feel more responsive to users. Prerendering can also improve [Search Engine Optimization (SEO)](https://developer.mozilla.org/docs/Glossary/SEO) by rendering content for the initial HTTP response that search engines use to calculate page rank. Prerendering is always followed by final rendering, either on the server or the client. :::moniker range=">= aspnetcore-8.0" @@ -137,10 +140,12 @@ The following table shows the available render modes for rendering Razor compone Name | Description | Render location | Interactive ---- | ----------- | :-------------: | :---------: -Static | Static server rendering | Server | -Interactive Server | Interactive server rendering using Blazor Server | Server | -Interactive WebAssembly | Interactive client rendering using Blazor WebAssembly | Client | -Interactive Auto | Interactive client rendering using Blazor Server initially and then WebAssembly on subsequent visits after the Blazor bundle is downloaded | Server, then client | +Static Server | Static server-side rendering (static SSR) | Server | +Interactive Server | Interactive server-side rendering (interactive SSR) using Blazor Server | Server | +Interactive WebAssembly | Client-side rendering (CSR) using Blazor WebAssembly† | Client | +Interactive Auto | Interactive SSR using Blazor Server initially and then CSR on subsequent visits after the Blazor bundle is downloaded | Server, then client | + +†Client-side rendering (CSR) is assumed to be interactive. "*Interactive* client-side rendering" and "*interactive* CSR" aren't used by the industry or in the Blazor documentation. The preceding information on render modes is all that you need to know to understand the *Fundamentals* node articles. If you're new to Blazor and reading Blazor articles in order down the table of contents, you can delay consuming in-depth information on render modes until you reach the article in the *Components* node. diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 9c2e16ebd057..6a6e5b44c84f 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -171,7 +171,7 @@ app.MapRazorComponents() ### Interactive routing -An interactive render mode can be assigned to the `Routes` component (`Routes.razor`) that makes the Blazor router become interactive after static SSR and static routing on the server. For example, `` assigns the Interactive Server render mode to the `Routes` component. The `Router` component inherits the Interactive Server render mode from the `Routes` component. The router becomes interactive after static routing on the server. +An interactive render mode can be assigned to the `Routes` component (`Routes.razor`) that makes the Blazor router become interactive after static SSR and static routing on the server. For example, `` assigns interactive server-side rendering (interactive SSR) to the `Routes` component. The `Router` component inherits interactive server-side rendering (interactive SSR) from the `Routes` component. The router becomes interactive after static routing on the server. If the `Routes` component is defined in the server project, the parameter of the `Router` component should include the `.Client` project's assembly. This allows the router to work correctly when rendered interactively. @@ -190,7 +190,7 @@ Additional assemblies are scanned in addition to the assembly specified to [!NOTE] > The preceding guidance also applies in [component class library](xref:blazor/components/class-libraries) scenarios. -Alterntively, routable components only exist in the `.Client` project with global Interactive WebAssembly or Auto rendering applied, and the `Routes` component is defined in the `.Client` project, not the server project. In this case, there aren't external assemblies with routable components, so it isn't necessary to specify a value for . +Alternatively, routable components only exist in the `.Client` project with global Interactive WebAssembly or Auto rendering applied, and the `Routes` component is defined in the `.Client` project, not the server project. In this case, there aren't external assemblies with routable components, so it isn't necessary to specify a value for . :::moniker-end @@ -717,7 +717,7 @@ Blazor.addEventListener('enhancedload', () => console.log('Enhanced update!')); To disable enhanced navigation and form handling globally, see . -Enhanced navigation with [Static Server rendering](xref:blazor/components/render-modes) requires special attention when loading JavaScript. For more information, see . +Enhanced navigation with [static server-side rendering (static SSR)](xref:blazor/components/render-modes#static-server-side-rendering-static-ssr) requires special attention when loading JavaScript. For more information, see . :::moniker-end diff --git a/aspnetcore/blazor/fundamentals/signalr.md b/aspnetcore/blazor/fundamentals/signalr.md index 4c89bce17462..572f9a24f275 100644 --- a/aspnetcore/blazor/fundamentals/signalr.md +++ b/aspnetcore/blazor/fundamentals/signalr.md @@ -79,9 +79,9 @@ The preceding example configures the hub connection URL to the absolute URI addr For more information, see . -:::moniker range=">= aspnetcore-8.0" +## Client-side rendering -## Client-side render mode +:::moniker range=">= aspnetcore-8.0" If prerendering is configured, prerendering occurs before the client connection to the server is established. For more information, see . @@ -89,8 +89,6 @@ If prerendering is configured, prerendering occurs before the client connection :::moniker range=">= aspnetcore-5.0 < aspnetcore-8.0" -## Client-side render mode - If prerendering is configured, prerendering occurs before the client connection to the server is established. For more information, see the following articles: * @@ -586,7 +584,7 @@ There was a problem with the connection! (Current reconnect attempt: 3 / 8) :::moniker-end -## Server-side render mode +## Server-side rendering -This article explains how to load JavaScript (JS) in a Blazor Web App with Static Server rendering and [enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling). +This article explains how to load JavaScript (JS) in a Blazor Web App with static server-side rendering (static SSR) and [enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling). Some apps depend on JS to perform initialization tasks that are specific to each page. When using Blazor's enhanced navigation feature, which allows the user to avoid reloading the entire page, page-specific JS may not be executed again as expected each time an enhanced page navigation occurs. diff --git a/aspnetcore/blazor/project-structure.md b/aspnetcore/blazor/project-structure.md index c26d0103fdc3..d3553d9b4f9a 100644 --- a/aspnetcore/blazor/project-structure.md +++ b/aspnetcore/blazor/project-structure.md @@ -22,9 +22,9 @@ Blazor Web App project template: `blazor` The Blazor Web App project template provides a single starting point for using Razor components to build any style of web UI, both server-side rendered and client-side rendered. It combines the strengths of the existing Blazor Server and Blazor WebAssembly hosting models with server-side rendering, streaming rendering, enhanced navigation and form handling, and the ability to add interactivity using either Blazor Server or Blazor WebAssembly on a per-component basis. -If both the WebAssembly and Server render modes are selected on app creation, the project template uses the Auto render mode. The automatic rendering mode initially uses the Server render mode while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, automatic render mode (Auto) switches to the WebAssembly render mode. +If both client-side rendering (CSR) and interactive server-side rendering (interactive SSR) are selected on app creation, the project template uses the Interactive Auto render mode. The automatic rendering mode initially uses interactive SSR while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, rendering switches to CSR. -By default, the Blazor Web App template enables both Static and Interactive Server rendering using a single project. If you also enable Interactive WebAssembly rendering, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the WebAssembly or Auto render modes must be built from the client project. +By default, the Blazor Web App template enables both static and interactive server-side rendering using a single project. If you also enable Interactive WebAssembly rendering, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the Interactive WebAssembly or Interactive Auto render modes must be built from the client project. For more information, see . @@ -59,7 +59,7 @@ For more information, see . * `Program.cs` file: The server project's entry point that sets up the ASP.NET Core web application [host](xref:fundamentals/host/generic-host#host-definition) and contains the app's startup logic, including service registrations, configuration, logging, and request processing pipeline. * Services for Razor components are added by calling . adds services to support rendering Interactive Server components. adds services to support rendering Interactive WebAssembly components. - * discovers available components and specifies the root component for the app (the first component loaded), which by default is the `App` component (`App.razor`). configures the Server render mode for the app. configures the WebAssembly render mode for the app. + * discovers available components and specifies the root component for the app (the first component loaded), which by default is the `App` component (`App.razor`). configures interactive server-side rendering (interactive SSR) for the app. configures the Interactive WebAssembly render mode for the app. * App settings files (`appsettings.Development.json`, `appsettings.json`): Provide [configuration settings](xref:blazor/fundamentals/configuration) for the server project. diff --git a/aspnetcore/blazor/security/index.md b/aspnetcore/blazor/security/index.md index 0d87f455c8da..356487a3b51e 100644 --- a/aspnetcore/blazor/security/index.md +++ b/aspnetcore/blazor/security/index.md @@ -513,7 +513,7 @@ You can only see this if you're signed in. ``` > [!IMPORTANT] -> Only use [`[Authorize]`](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) on `@page` components reached via the Blazor Router. Authorization is only performed as an aspect of routing and *not* for child components rendered within a page. To authorize the display of specific parts within a page, use instead. +> Only use [`[Authorize]`](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) on `@page` components reached via the Blazor router. Authorization is only performed as an aspect of routing and *not* for child components rendered within a page. To authorize the display of specific parts within a page, use instead. The [`[Authorize]` attribute](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) also supports role-based or policy-based authorization. For role-based authorization, use the parameter: @@ -834,7 +834,7 @@ Common errors: It's likely that the project wasn't created using a server-side Blazor template with authentication enabled. -In .NET 7 or earlier, wrap a `` around some part of the UI tree, for example around the Blazor Router: +In .NET 7 or earlier, wrap a `` around some part of the UI tree, for example around the Blazor router: ```razor diff --git a/aspnetcore/blazor/security/server/index.md b/aspnetcore/blazor/security/server/index.md index 6ae3d427b31b..3199a2e20ccd 100644 --- a/aspnetcore/blazor/security/server/index.md +++ b/aspnetcore/blazor/security/server/index.md @@ -151,7 +151,7 @@ The template handles the following: * Adds Identity Razor components and related logic for routine authentication tasks, such as signing users in and out. * The Identity components also support advanced Identity features, such as [account confirmation and password recovery](xref:security/authentication/accconfirm) and [multifactor authentication](xref:security/authentication/mfa) using a third-party app. - * Interactive server and interactive client rendering scenarios are supported. + * Interactive server-side rendering (interactive SSR) and client-side rendering (CSR) scenarios are supported. * Adds the Identity-related packages and dependencies. * References the Identity packages in `_Imports.razor`. * Creates a custom user Identity class (`ApplicationUser`). diff --git a/aspnetcore/blazor/security/server/static-server-side-rendering.md b/aspnetcore/blazor/security/server/static-server-side-rendering.md index 2de287ad3c78..f82f8894d1b3 100644 --- a/aspnetcore/blazor/security/server/static-server-side-rendering.md +++ b/aspnetcore/blazor/security/server/static-server-side-rendering.md @@ -83,7 +83,7 @@ The framework offers mechanisms for protecting sensitive information for a given * Making sure that a user can't inspect or modify the private information of another user. * Making sure that a user can't modify user data of another user, such as an internal identifier. -With regard to data protection, you must clearly understand where the code is executing. For the Static Server and Interactive Server render modes, code is stored on the server and never reaches the client. For the Interactive WebAssembly render mode, the app code *always reaches the client*, which means that any sensitive information stored in the app code is available to anyone with access to the app. Obfuscation and other similar technique to "protect" the code isn't effective. Once the code reaches the client, it can be reverse-engineered to extract the sensitive information. +With regard to data protection, you must clearly understand where the code is executing. For the static server-side rendering (static SSR) and interactive server-side rendering (interactive SSR), code is stored on the server and never reaches the client. For the Interactive WebAssembly render mode, the app code *always reaches the client*, which means that any sensitive information stored in the app code is available to anyone with access to the app. Obfuscation and other similar technique to "protect" the code isn't effective. Once the code reaches the client, it can be reverse-engineered to extract the sensitive information. ## Denial of service diff --git a/aspnetcore/blazor/tooling.md b/aspnetcore/blazor/tooling.md index 54c683f50fc3..1bbf8365b7b6 100644 --- a/aspnetcore/blazor/tooling.md +++ b/aspnetcore/blazor/tooling.md @@ -25,7 +25,7 @@ To create a Blazor app on Windows, use the following guidance: * Create a new project using one of the available Blazor templates: - * **Blazor Web App** (*recommended*): Creates a Blazor web app that supports Interactive Server and interactive client rendering. + * **Blazor Web App** (*recommended*): Creates a Blazor web app that supports interactive server-side rendering (interactive SSR) and client-side rendering (CSR). * **Blazor WebAssembly Standalone App**: Creates a standalone client web app that can be deployed as a static site. Select **Next**. @@ -56,21 +56,32 @@ Select **Next**. :::moniker range=">= aspnetcore-8.0" +> [!NOTE] +> Rendering terms and concepts used in the following guidance are introduced in the following sections of the *Fundamentals* overview article: +> +> * [Client and server rendering concepts](xref:blazor/fundamentals/index#client-and-server-rendering-concepts) +> * [Static and interactive rendering concepts](xref:blazor/fundamentals/index#static-and-interactive-rendering-concepts) +> * [Render modes](xref:blazor/fundamentals/index#render-modes) +> +> Detailed guidance on render modes is provided by the article. + * For a Blazor Web App in the **Additional information** dialog: - * **Interactive render mode** dropdown list: - * Interactive server rendering is enabled by default with the **Server** option. - * To only enable interactivity with client rendering, select the **WebAssembly** option. - * To enable both Interactive Server and client rendering and the ability to automatically switch between them at runtime, select the **Auto (Server and WebAssembly)** (automatic) render mode option. - * If interactivity is set to `None`, the generated app has no interactivity (Static Server rendering only). + * **Interactive render mode** dropdown list + + * Interactive server-side rendering (interactive SSR) is enabled by default with the **Server** option. + * To only enable interactivity with client-side rendering (CSR), select the **WebAssembly** option. + * To enable both interactive rendering modes and the ability to automatically switch between them at runtime, select the **Auto (Server and WebAssembly)** (automatic) render mode option. + * If interactivity is set to `None`, the generated app has no interactivity. The app is only configured for static server-side rendering. - The Auto render mode initially uses Interactive Server rendering while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, the render mode switches to Interactive WebAssembly rendering. + The Interactive Auto render mode initially uses interactive SSR while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, the render mode switches to Interactive WebAssembly rendering. - By default, the Blazor Web App template enables both Static and Interactive Server rendering using a single project. If you also enable Interactive WebAssembly rendering, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the WebAssembly or automatic render modes must be built from the client project. + By default, the Blazor Web App template enables both static and interactive SSR using a single project. If you also enable CSR, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the WebAssembly or automatic render modes must be built from the client project. For more information, see . - * **Interactivity location** dropdown list: + * **Interactivity location** dropdown list + * **Per page/component**: The default sets up interactivity per page or per component. * **Global**: Selecting this option sets up interactivity globally for the entire app. @@ -131,33 +142,33 @@ Install the latest [C# for Visual Studio Code extension](https://marketplace.vis Create a new project: -* For a Blazor Web App experience with default server interactivity, execute the following command in a command shell that uses the `blazor` project template: +* For a Blazor Web App experience with default interactive server-side rendering, execute the following command in a command shell that uses the `blazor` project template: ```dotnetcli dotnet new blazor -o BlazorApp ``` - To only enable Interactive WebAssembly rendering, use the `-int|--interactivity` option set to `WebAssembly`: + To only enable client-side rendering, use the `-int|--interactivity` option set to `WebAssembly`: ```dotnetcli dotnet new blazor -o BlazorApp -int WebAssembly ``` - To enable Interactive Server rendering followed by Interactive WebAssembly rendering, use the `-int|--interactivity` option set to `Auto`: + To enable interactive server-side rendering followed by client-side rendering, use the `-int|--interactivity` option set to `Auto`: ```dotnetcli dotnet new blazor -o BlazorApp -int Auto ``` - If interactivity is disabled by setting the `-int|--interactivity` option to `None`, the generated app has no interactivity (Static Server rendering only): + If interactivity is disabled by setting the `-int|--interactivity` option to `None`, the generated app has no interactivity. The app is only configured for static server-side rendering: ```dotnetcli dotnet new blazor -o BlazorApp -int None ``` - The Auto render mode initially uses the Server render mode while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, the render mode switches to the WebAssembly render mode. + The Interactive Auto render mode initially uses the interactive server-side rendering (interactive SSR) while the .NET app bundle and runtime are download to the browser. After the .NET WebAssembly runtime is activated, the render mode switches to the Interactive WebAssembly render mode. - By default, the Blazor Web App template enables both Static and Interactive Server rendering using a single project. If you also enable the WebAssembly render mode, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the WebAssembly or Auto render modes must be built from the client project. + By default, the Blazor Web App template enables both static and interactive server-side rendering using a single project. If you also enable the Interactive WebAssembly render mode, the project includes an additional client project (`.Client`) for your WebAssembly-based components. The built output from the client project is downloaded to the browser and executed on the client. Any components using the Interactive WebAssembly or Interactive Auto render modes must be built from the client project. For more information, see . From 35a88f39e4c08fbd36ee599a9e9d64215a32b91d Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 1 Dec 2023 10:32:51 -0500 Subject: [PATCH 2/2] Updates --- aspnetcore/blazor/fundamentals/index.md | 2 +- aspnetcore/blazor/globalization-localization.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/aspnetcore/blazor/fundamentals/index.md b/aspnetcore/blazor/fundamentals/index.md index c046939dd97c..fad79c11b02d 100644 --- a/aspnetcore/blazor/fundamentals/index.md +++ b/aspnetcore/blazor/fundamentals/index.md @@ -20,7 +20,7 @@ Throughout the Blazor documentation, activity that takes place on the user's sys The term *rendering* means to produce the HTML markup that browsers display. -* **Client-side rendering (CSR)** means that the final HTML markup is generated by the Blazor WebAssembly runtime on the client. No HTML for the app's client-generated UI is sent from a server to the client for this type of rendering. User interactivity with the page is assumed. There's no such concept as *static* client-side rendering. CSR is assumed to be interactive, so "*interactive* client-side rendering" and "*interactive* CSR" aren't used by the industry or the Blazor documentation. +* **Client-side rendering (CSR)** means that the final HTML markup is generated by the Blazor WebAssembly runtime on the client. No HTML for the app's client-generated UI is sent from a server to the client for this type of rendering. User interactivity with the page is assumed. There's no such concept as *static* client-side rendering. CSR is assumed to be interactive, so "*interactive* client-side rendering" and "*interactive* CSR" aren't used by the industry or in the Blazor documentation. * **Server-side rendering (SSR)** means that the final HTML markup is generated by the ASP.NET Core runtime on the server. The HTML is sent to the client over a network for display by the client's browser. No HTML for the app's server-generated UI is created by the client for this type of rendering. SSR can be of two varieties: diff --git a/aspnetcore/blazor/globalization-localization.md b/aspnetcore/blazor/globalization-localization.md index 29d441105606..f304092aaae7 100644 --- a/aspnetcore/blazor/globalization-localization.md +++ b/aspnetcore/blazor/globalization-localization.md @@ -753,7 +753,7 @@ Use the `CultureExample1` component shown in the [Demonstration component](#demo :::moniker range=">= aspnetcore-8.0" -The preceding example assumes that the app adopts ***global*** interactivity by specifying the interactive server-side rendering (interactive SSR) on the `Routes` component in the `App` component (`Components/App.razor`): +The preceding example assumes that the app adopts ***global*** interactivity by specifying the Interactive Server render mode on the `Routes` component in the `App` component (`Components/App.razor`): ```razor @@ -761,13 +761,13 @@ The preceding example assumes that the app adopts ***global*** interactivity by If the app adopts ***per-page/component*** interactivity, make the following changes: -* Add interactive SSR to the top of the `CultureExample1` component file (`Components/Pages/CultureExample1.razor`): +* Add the Interactive Server render mode to the top of the `CultureExample1` component file (`Components/Pages/CultureExample1.razor`): ```razor @rendermode InteractiveServer ``` -* In the app's main layout (`Components/Layout/MainLayout.razor`), enable interactive server-side rendering for the `CultureSelector` component: +* In the app's main layout (`Components/Layout/MainLayout.razor`), apply the Interactive Server render mode to the `CultureSelector` component: ```razor