diff --git a/aspnetcore/blazor/components/index.md b/aspnetcore/blazor/components/index.md index 358b4b4e77d4..c6b71fc9bd7c 100644 --- a/aspnetcore/blazor/components/index.md +++ b/aspnetcore/blazor/components/index.md @@ -35,6 +35,42 @@ Developers typically create Razor components from Razor component files (`.razor Components use [Razor syntax](xref:mvc/views/razor). Two Razor features are extensively used by components, *directives* and *directive attributes*. These are reserved keywords prefixed with `@` that appear in Razor markup: * [Directives](xref:mvc/views/razor#directives): Change the way component markup is parsed or functions. For example, the [`@page`][9] directive specifies a routable component with a route template and can be reached directly by a user's request in the browser at a specific URL. + + By convention, a component's directives at the top of a component definition (`.razor` file) are placed in a consistent order. For repeated directives, directives are placed alphabetically by namespace or type, except `@using` directives, which have special second-level ordering. + + The following order is adopted by Blazor sample apps and documentation. Components provided by a Blazor project template may differ from the following order and use a different format. For example, Blazor framework Identity components include blank lines between blocks of `@using` directives and blocks of `@inject` directives. You're free to use a custom ordering scheme and format in your own apps. + + Documentation and sample app Razor directive order: + + * `@page` + * `@rendermode` (.NET 8 or later) + * `@using` + * `System` namespaces + * `Microsoft` namespaces + * App namespaces + * Other directives + + No blank lines appear among the directives. One blank line appears between the directives and the fist line of Razor markup. + + Example: + + ```razor + @page "/doctor-who-episodes/{season:int}" + @rendermode InteractiveWebAssembly + @using System.Globalization + @using System.Text.Json + @using Microsoft.AspNetCore.Localization + @using DoctorWhoTemplates.Layout + @attribute [Authorize] + @implements IAsyncDisposable + @inject IJSRuntime JS + @inject ILogger Logger + + Doctor Who Episode List + + ... + ``` + * [Directive attributes](xref:mvc/views/razor#directive-attributes): Change the way a component element is parsed or functions. For example, the [`@bind`][10] directive attribute for an `` element binds data to the element's value. Directives and directive attributes used in components are explained further in this article and other articles of the Blazor documentation set. For general information on Razor syntax, see . diff --git a/aspnetcore/blazor/components/prerendering-and-integration.md b/aspnetcore/blazor/components/prerendering-and-integration.md index 367292bff484..7d6b37922593 100644 --- a/aspnetcore/blazor/components/prerendering-and-integration.md +++ b/aspnetcore/blazor/components/prerendering-and-integration.md @@ -843,8 +843,8 @@ The following example is an updated version of the `FetchData` component in a ho ```razor @page "/weather-forecast-preserve-state" -@implements IDisposable @using BlazorSample.Shared +@implements IDisposable @inject IWeatherForecastService WeatherForecastService @inject PersistentComponentState ApplicationState diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index 33eb3d47a5c6..f90226984684 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -56,8 +56,8 @@ For example, add the following component to render a grid. ```razor @page "/quickgrid-example" -@using Microsoft.AspNetCore.Components.QuickGrid @rendermode InteractiveServer +@using Microsoft.AspNetCore.Components.QuickGrid diff --git a/aspnetcore/blazor/fundamentals/dependency-injection.md b/aspnetcore/blazor/fundamentals/dependency-injection.md index 05451ebf80ad..fe2d0589df52 100644 --- a/aspnetcore/blazor/fundamentals/dependency-injection.md +++ b/aspnetcore/blazor/fundamentals/dependency-injection.md @@ -408,8 +408,8 @@ In spite of the scoped service registration in the `Program` file and the longev ```razor @page "/users" -@attribute [Authorize] @rendermode InteractiveServer +@attribute [Authorize] @inherits OwningComponentBase

Users (@Service.Users.Count())

diff --git a/aspnetcore/blazor/fundamentals/index.md b/aspnetcore/blazor/fundamentals/index.md index fad79c11b02d..5b9e9202993a 100644 --- a/aspnetcore/blazor/fundamentals/index.md +++ b/aspnetcore/blazor/fundamentals/index.md @@ -58,6 +58,7 @@ Blazor documentation adopts several conventions for showing and discussing compo * Usually, a component's C# class name is the same as its file name. * Routable components usually set their relative URLs to the component's class name in kebab-case. For example, a `FileUpload` component includes routing configuration to reach the rendered component at the relative URL `/file-upload`. Routing and navigation is covered in . * When multiple versions of a component are used, they're numbered sequentially. For example, the `FileUpload3` component is reached at `/file-upload-3`. +* [Razor directives](xref:mvc/views/razor#directives) at the top of a component definition (`.razor file`) are placed in the following order: `@page`, `@rendermode` (.NET 8 or later), `@using` statements, other directives in alphabetical order. Additional information on Razor directive ordering is found in the *Razor syntax* section of . * Access modifiers are used in article examples. For example, fields are `private` by default but are explicitly present in component code. For example, `private` is stated for declaring a field named `maxAllowedFiles` as `private int maxAllowedFiles = 3;`. * Generally, examples adhere to ASP.NET Core/C# coding conventions and engineering guidelines. For more information see the following resources: * [Engineering guidelines (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/wiki/Engineering-guidelines) diff --git a/aspnetcore/blazor/fundamentals/routing.md b/aspnetcore/blazor/fundamentals/routing.md index 6a6e5b44c84f..d1124aee3436 100644 --- a/aspnetcore/blazor/fundamentals/routing.md +++ b/aspnetcore/blazor/fundamentals/routing.md @@ -359,7 +359,7 @@ Route constraints also work with [optional parameters](#route-parameters). In th `User.razor`: ```razor -@page "/user/{Id:int}/{Option:bool?}" +@page "/user/{id:int}/{option:bool?}"

Id: @Id @@ -1425,8 +1425,8 @@ In the following example, a location changing handler is registered for navigati ```razor @page "/nav-handler" -@inject NavigationManager Navigation @implements IDisposable +@inject NavigationManager Navigation

@@ -923,8 +923,8 @@ In the following `GenericsExample` component: ```razor @page "/generics-example" @using System.Runtime.InteropServices -@inject IJSRuntime JS @implements IDisposable +@inject IJSRuntime JS

diff --git a/aspnetcore/blazor/performance.md b/aspnetcore/blazor/performance.md index eaeb42613f14..396199d7199c 100644 --- a/aspnetcore/blazor/performance.md +++ b/aspnetcore/blazor/performance.md @@ -345,8 +345,8 @@ Some browser events fire extremely frequently. For example, `onmousemove` and `o Rather than use native events that rapidly fire, consider the use of JS interop to register a callback that fires less frequently. For example, the following component displays the position of the mouse but only updates at most once every 500 ms: ```razor -@inject IJSRuntime JS @implements IDisposable +@inject IJSRuntime JS

@message

diff --git a/aspnetcore/blazor/security/server/index.md b/aspnetcore/blazor/security/server/index.md index 3199a2e20ccd..bafa68f34ddf 100644 --- a/aspnetcore/blazor/security/server/index.md +++ b/aspnetcore/blazor/security/server/index.md @@ -675,8 +675,8 @@ In the following `InjectAuthStateProvider` component: ```razor @page "/inject-auth-state-provider" @rendermode InteractiveServer -@inject AuthenticationStateProvider AuthenticationStateProvider @inherits OwningComponentBase +@inject AuthenticationStateProvider AuthenticationStateProvider

Inject AuthenticationStateProvider Example

diff --git a/aspnetcore/blazor/security/webassembly/additional-scenarios.md b/aspnetcore/blazor/security/webassembly/additional-scenarios.md index c6a811c3bdc2..f26add5b576e 100644 --- a/aspnetcore/blazor/security/webassembly/additional-scenarios.md +++ b/aspnetcore/blazor/security/webassembly/additional-scenarios.md @@ -897,9 +897,9 @@ The `Authentication` component (`Authentication.razor`) saves and restores the a ```razor @page "/authentication/{action}" +@using Microsoft.AspNetCore.Components.WebAssembly.Authentication @inject IJSRuntime JS @inject StateContainer State -@using Microsoft.AspNetCore.Components.WebAssembly.Authentication User Claims @@ -674,8 +674,8 @@ You can use the following `UserClaims` component to study the user's claims afte @page "/user-claims" @using System.Security.Claims @using Microsoft.AspNetCore.Authorization -@inject AuthenticationStateProvider AuthenticationStateProvider @attribute [Authorize] +@inject AuthenticationStateProvider AuthenticationStateProvider

User Claims

@@ -806,9 +806,10 @@ In the following `GraphExample` component, an @page "/graph-example" @using Microsoft.AspNetCore.Authorization @using Microsoft.AspNetCore.Components.WebAssembly.Authentication +@attribute [Authorize] @inject IConfiguration Config @inject IHttpClientFactory ClientFactory -@attribute [Authorize] +

Microsoft Graph Component Example

@@ -958,8 +959,8 @@ You can use the following `UserClaims` component to study the user's claims afte @page "/user-claims" @using System.Security.Claims @using Microsoft.AspNetCore.Authorization -@inject AuthenticationStateProvider AuthenticationStateProvider @attribute [Authorize] +@inject AuthenticationStateProvider AuthenticationStateProvider

User Claims

diff --git a/aspnetcore/blazor/webassembly-lazy-load-assemblies.md b/aspnetcore/blazor/webassembly-lazy-load-assemblies.md index 1db2b3f61788..eb7e7f6b05f9 100644 --- a/aspnetcore/blazor/webassembly-lazy-load-assemblies.md +++ b/aspnetcore/blazor/webassembly-lazy-load-assemblies.md @@ -178,8 +178,8 @@ In the following example: @using Microsoft.AspNetCore.Components.Routing @using Microsoft.AspNetCore.Components.WebAssembly.Services @using Microsoft.Extensions.Logging -@inject LazyAssemblyLoader AssemblyLoader @inject ILogger Logger +@inject LazyAssemblyLoader AssemblyLoader Logger +@inject LazyAssemblyLoader AssemblyLoader Logger +@inject LazyAssemblyLoader AssemblyLoader Logger +@inject LazyAssemblyLoader AssemblyLoader