ASP.NET Core Blazor fundamentals

Fundamentals articles provide guidance on foundational Blazor concepts. Some of the concepts are connected to a basic understanding of Razor components, which are described further in the next section of this article and covered in detail in the Components articles.

Client and server rendering concepts

Throughout the Blazor documentation, activity that takes place on the user's system is said to occur on the client or client-side. Activity that takes place on a server is said to occur on the server or server-side.

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 .NET 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:

  • 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) 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.

Razor components

Blazor apps are based on Razor components, often referred to as just components. A component is an element of UI, such as a page, dialog, or data entry form. Components are .NET C# classes built into .NET assemblies.

Razor refers to how components are usually written in the form of a Razor markup page for client-side UI logic and composition. Razor is a syntax for combining HTML markup with C# code designed for developer productivity. Razor files use the .razor file extension.

Although some Blazor developers and online resources use the term "Blazor components," the documentation avoids that term and universally uses "Razor components" or "components."

Blazor documentation adopts several conventions for showing and discussing components:

• Generally, examples adhere to ASP.NET Core/C# coding conventions and engineering guidelines. For more information see the following resources:
  • ASP.NET Core framework engineering guidelines (dotnet/aspnetcore GitHub repository)
  • C# Coding Conventions (C# guide)
• Project code, file paths and names, project template names, and other specialized terms are in United States English and usually code-fenced.
• Components are usually referred to by their C# class name (Pascal case) followed by the word "component." For example, a typical file upload component is referred to as the "FileUpload component."
• 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 ASP.NET Core Blazor routing and navigation.
• 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 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.
• Although not required for private members, access modifiers are used in article examples and sample apps. For example, private is stated for declaring a field named maxAllowedFiles as private int maxAllowedFiles = 3;.
• Component parameter values lead with a Razor reserved @ symbol, but it isn't required. Literals (for example, boolean values), keywords (for example, this), and null as component parameter values aren't prefixed with @, but this is also merely a documentation convention. Your own code can prefix literals with @ if you wish.
• C# classes use the this keyword and avoid prefixing fields with an underscore (_) that are assigned to in constructors, which differs from the ASP.NET Core framework engineering guidelines.
• In examples that use primary constructors (C# 12 or later), primary constructor parameters are typically used directly by class members. In article examples, code lines are split to reduce horizontal scrolling. These breaks don't affect execution but can be removed when pasting into your project.

Additional information on Razor component syntax is provided in the Razor syntax section of ASP.NET Core Razor components.

The following is an example counter component and part of an app created from a Blazor project template. Detailed components coverage is found in the Components articles later in the documentation. The following example demonstrates component concepts seen in the Fundamentals articles before reaching the Components articles later in the documentation.

Counter.razor:

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

The preceding Counter component:

• Sets its route with the @page directive in the first line.
• Sets its page title and heading.
• Renders the current count with @currentCount. currentCount is an integer variable defined in the C# code of the @code block.
• Displays a button to trigger the IncrementCount method, which is also found in the @code block and increases the value of the currentCount variable.

Document Object Model (DOM)

References to the Document Object Model use the abbreviation DOM.

For more information, see the following resources:

• Introduction to the DOM (MDN documentation)
• Level 1 Document Object Model Specification (W3C)

Subset of .NET APIs for Blazor WebAssembly apps

A curated list of specific .NET APIs that are supported on the browser for Blazor WebAssembly isn't available. However, you can manually search for a list of .NET APIs annotated with [UnsupportedOSPlatform("browser")] to discover .NET APIs that aren't supported in WebAssembly.

For more information, see the following resources:

• Class libraries: Client-side browser compatibility analyzer
• Annotating APIs as unsupported on specific platforms (dotnet/designs GitHub repository

Sample apps

Documentation sample apps are available for inspection and download:

Blazor samples GitHub repository (dotnet/blazor-samples)

Locate a sample app by first selecting the version folder that matches the version of .NET that you're working with.

For more information, a list of the samples in the repository, and download instructions, see the Blazor samples GitHub repository README file.

The ASP.NET Core repository's Basic Test App is also a helpful set of samples for various Blazor scenarios:

BasicTestApp in ASP.NET Core reference source (dotnet/aspnetcore)

Byte multiples

.NET byte sizes use metric prefixes for non-decimal multiples of bytes based on powers of 1024.

Support requests

Only documentation-related issues are appropriate for the dotnet/AspNetCore.Docs repository. For product support, don't open a documentation issue. Seek assistance through one or more of the following support channels:

• Stack Overflow (tagged: blazor)
• General ASP.NET Core Slack Team
• Blazor Gitter

For a potential bug in the framework or product feedback, open an issue for the ASP.NET Core product unit at dotnet/aspnetcore issues. Bug reports usually require the following:

• Clear explanation of the problem: Follow the instructions in the GitHub issue template provided by the product unit when opening the issue.
• Minimal repro project: Place a project on GitHub for the product unit engineers to download and run. Cross-link the project into the issue's opening comment.

For a potential problem with a Blazor article, open a documentation issue. To open a documentation issue, use the Open a documentation issue feedback link at the bottom of the article. Metadata added to your issue provides tracking data and automatically pings the author of the article. If the subject was discussed with the product unit prior to opening the documentation issue, place a cross-link to the engineering issue in the documentation issue's opening comment.

For problems or feedback on Visual Studio, use the Report a Problem or Suggest a Feature gestures from within Visual Studio, which open internal issues for Visual Studio. For more information, see Visual Studio Feedback.

For problems with Visual Studio Code, ask for support on community support forums. For bug reports and product feedback, open an issue on the microsoft/vscode GitHub repo.

GitHub issues for Blazor documentation are automatically marked for triage on the Blazor.Docs project (dotnet/AspNetCore.Docs GitHub repository). Please wait a short while for a response, especially over weekends and holidays. Usually, documentation authors respond within 24 hours on weekdays.

Community links to Blazor resources

For a collection of links to Blazor resources maintained by the community, visit Awesome Blazor.