Razor directive ordering

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<DoctorWhoEpisodes> Logger
+
+  <PageTitle>Doctor Who Episode List</PageTitle>
+
+  ...
+  ```
+
 * [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 `<input>` 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 <xref:mvc/views/razor>.

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
 

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
 
 <QuickGrid Items="@people">
     <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />

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<AppDbContext>
 
 <h1>Users (@Service.Users.Count())</h1>

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 <xref:blazor/fundamentals/routing>.
 * 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 <xref:blazor/components/index#razor-syntax>.
 * 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)

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?}"
 
 <p>
     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
 
 <p>
     <button @onclick="@(() => Navigation.NavigateTo("/"))">

aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md

@@ -875,8 +875,8 @@ In the following `GenericsExample` component:
 @page "/generics-example"
 @rendermode InteractiveServer
 @using System.Runtime.InteropServices
-@inject IJSRuntime JS
 @implements IDisposable
+@inject IJSRuntime JS
 
 <p>
     <button @onclick="InvokeInterop">Invoke Interop</button>
@@ -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
 
 <p>
     <button @onclick="InvokeInterop">Invoke Interop</button>

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
 
 <h1>@message</h1>
 

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
 
 <h1>Inject <code>AuthenticationStateProvider</code> Example</h1>
 

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
 
 <RemoteAuthenticatorViewCore Action="@Action"
                              TAuthenticationState="ApplicationAuthenticationState"
@@ -951,9 +951,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
 
 <RemoteAuthenticatorViewCore Action="@Action"
                              TAuthenticationState="ApplicationAuthenticationState"

aspnetcore/blazor/security/webassembly/graph-api.md

@@ -324,8 +324,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
 
 <h1>User Claims</h1>
 
@@ -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
 
 <h1>User Claims</h1>
 
@@ -806,9 +806,10 @@ In the following `GraphExample` component, an <xref:System.Net.Http.HttpClient>
 @page "/graph-example"
 @using Microsoft.AspNetCore.Authorization
 @using Microsoft.AspNetCore.Components.WebAssembly.Authentication
+@attribute [Authorize]
 @inject IConfiguration Config
 @inject IHttpClientFactory ClientFactory
-@attribute [Authorize]
+
 
 <h1>Microsoft Graph Component Example</h1>
 
@@ -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
 
 <h1>User Claims</h1>
 

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<App> Logger
+@inject LazyAssemblyLoader AssemblyLoader
 
 <Router AppAssembly="@typeof(App).Assembly" 
     AdditionalAssemblies="@lazyLoadedAssemblies" 
@@ -218,8 +218,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<App> Logger
+@inject LazyAssemblyLoader AssemblyLoader
 
 <Router AppAssembly="@typeof(Program).Assembly" 
     AdditionalAssemblies="@lazyLoadedAssemblies" 
@@ -524,8 +524,8 @@ The assembly is assigned to <xref:Microsoft.AspNetCore.Components.Routing.Router
 @using Microsoft.AspNetCore.Components.Routing
 @using Microsoft.AspNetCore.Components.WebAssembly.Services
 @using Microsoft.Extensions.Logging
-@inject LazyAssemblyLoader AssemblyLoader
 @inject ILogger<App> Logger
+@inject LazyAssemblyLoader AssemblyLoader
 
 <Router AppAssembly="@typeof(App).Assembly"
         AdditionalAssemblies="@lazyLoadedAssemblies" 
@@ -576,8 +576,8 @@ The assembly is assigned to <xref:Microsoft.AspNetCore.Components.Routing.Router
 @using Microsoft.AspNetCore.Components.Routing
 @using Microsoft.AspNetCore.Components.WebAssembly.Services
 @using Microsoft.Extensions.Logging
-@inject LazyAssemblyLoader AssemblyLoader
 @inject ILogger<App> Logger
+@inject LazyAssemblyLoader AssemblyLoader
 
 <Router AppAssembly="@typeof(Program).Assembly"
         AdditionalAssemblies="@lazyLoadedAssemblies"