Introduction
Embarking on a journey through the robust landscape of Blazor Server introduces developers to a world where interactive and dynamic web applications can be crafted using C# instead of JavaScript. This powerful server-side framework, a gem from the ASP.NET Core family, has been steadily gaining traction for its ability to simplify the construction of modern web apps, single-page applications (SPAs), and real-time UI updates.
Whether you're a seasoned developer pivoting towards new technologies, or an enthusiast navigating the .NET ecosystem, understanding the core elements of Blazor Server provides a solid foundation to build upon. It's not merely about writing code but understanding the anatomy that binds together the client and server, ensuring an optimized, fluid user experience.
In the context of Blazor Server applications, pivotal elements ranging from routing, component anatomy, to handling user authentication are paramount. Let's dive into one such cornerstone element: the App.razor file, an unassuming yet crucial participant in the Blazor Server dialogue.
The role of App.razor
In Blazor Server applications, the App.razor file plays a crucial role as it defines the application's routing behavior and serves as the root component of the app. It is one of the first files that is utilized when the app starts and it essentially acts as a directive to the app on how to handle routing and layouts.
Here’s a breakdown of the roles of App.razor in a Blazor Server application:
1. Routing
App.razor includes a Router component that tells the application how to set up client-side routing. This component decides which Razor component should be displayed based on the current URL. The Router component can handle failed route navigation and can redirect users when a particular route is not found, providing a smooth user experience.
Example:
<Router AppAssembly="@typeof(Program).Assembly">
<Found Context="routeData">
<RouteView RouteData="@routeData" DefaultLayout="typeof(MainLayout)" />
</Found>
<NotFound>
<LayoutView Layout="typeof(MainLayout)">
<p>Sorry, there's nothing at this address.</p>
</LayoutView>
</NotFound>
</Router>
2. Layout Specification
App.razor can specify a default layout to be used throughout the application by providing a DefaultLayout parameter to the RouteView component. This layout typically contains common UI components that should be visible across different pages, such as headers, footers, or navigation menus.
If you would like some assistance with Azure | Azure DevOps Services | Blazor Development then please get in touch, we would be glad to help.
3. Handling Not Found Pages
In the case where a route is not found (a user navigates to a URL that doesn't correspond to any component), the Router component can define a "not found" template which will be displayed. This is often utilized to give a user-friendly error message and possibly redirect them to existing pages.
4. Cascading Authentication State
In applications utilizing authentication, App.razor often contains a CascadingAuthenticationState component that provides authentication state information to the components being rendered by the Router. This allows other components to easily obtain the authentication state and user information.
Example:
<CascadingAuthenticationState>
<Router AppAssembly="@typeof(Program).Assembly">
...
</Router>
</CascadingAuthenticationState>
Routing Across Multiple Assemblies
One further capability of the Router defined in App.razor deserves a mention, because it becomes important as soon as an application grows beyond a single project. By default, the router only scans the assembly supplied via AppAssembly for routable components, meaning components decorated with an @page directive. If some of your pages live in a Razor Class Library, perhaps because you share UI across several applications, they will be invisible to the router until their assemblies are listed via the AdditionalAssemblies parameter.
Example:
<Router AppAssembly="@typeof(Program).Assembly"
AdditionalAssemblies="new[] { typeof(SharedPages.Dashboard).Assembly }">
...
</Router>
Under the hood, the @page directive compiles down to a RouteAttribute on the generated component class, and the router builds its route table by reflecting over these attributes in the assemblies it has been told about. Knowing this explains a whole class of "my page returns not found" issues that have nothing to do with the URL itself: the component simply lives in an assembly the router never scanned.
Structuring pages into class libraries in this way is a pattern we use regularly in larger Blazor application development projects, as it keeps feature areas independently testable and allows the same pages to be shared between a Blazor Server app and its WebAssembly or Hybrid siblings.
Summary
App.razor is pivotal for defining routing logic, handling unmatched URLs, specifying a default layout, and cascading the authentication state in a Blazor Server application. It acts as a central setup point for these primary functionalities, making it a crucial part of the app structure.
A 2026 note on the unified Blazor template
Updated August 2026. This article, like the rest of our Blazor Server Byte by Byte series, describes the .NET 7-era Blazor Server project template. In the unified Blazor Web App template introduced with .NET 8 (and current in .NET 10), the same responsibilities are split across two files: App.razor is now the root HTML document — hosting the <head>, the Blazor script and the render-mode configuration — while the Router component shown above lives in Routes.razor.
The concepts here still apply directly: routing, layout selection, not-found handling and cascading authentication state all work the same way, just from their new home. If you are maintaining a classic Blazor Server app, everything above remains accurate; if you are starting fresh on .NET 10, look for these pieces in App.razor and Routes.razor. Our Blazor development team can help with either — including moving an existing Blazor Server app onto the unified template.
At Assemblysoft we specialise in Custom Software Development tailored to your requirements. We can onboard and add value to your business rapidly. We are an experienced Full-stack development team able to provide specific technical expertise or manage your project requirements end to end. We specialise in the Microsoft cloud and .NET Solutions and Services. Our developers are Microsoft Certified. We have real-world experience developing .NET applications and Azure Services for a large array of business domains. If you would like some assistance with Azure | Azure DevOps Services | Blazor Development or in need of custom software development, from an experienced development team in the United Kingdom, then please get in touch, we would love to add immediate value to your business.
Assemblysoft - Your Safe Pair of Hands
