Get started with Razor Components

By Daniel Roth and Luke Latham

Prerequisites:

To create your first Razor Components project in Visual Studio:

  1. Select File > New Project > Web > ASP.NET Core Web Application.

  2. Make sure .NET Core and ASP.NET Core 3.0 are selected at the top.

  3. Choose the Razor Components template and select OK.

    New app dialog

  4. Press F5 to run the app.

Congratulations! You just ran your first Razor Components app!

Razor Components project

The solution created by the Razor Components template contains two projects:

  • WebApplication1.Server – The server project is an ASP.NET Core project set up to host the Razor Components app.
  • WebApplication1.App – The client-side web UI project that uses Razor Components.

The UI logic in the WebApplication1.App project is separated from the rest of the app due to a technical limitation in ASP.NET Core 3.0 Preview 2. The Razor file extension (.cshtml) used for Razor Components is also used for Razor Pages and MVC views. Currently, Razor Components and Razor Pages/MVC have different compilation models, so the Razor Components Razor files are kept separate. In a future preview, we plan to introduce a new file extension for Razor Components (.razor). Components, pages, and views will be hosted in the same project.

When the app is run, multiple pages are available from tabs in the sidebar:

  • Home
  • Counter
  • Fetch data

On the Counter page, select the Click me button to increment the counter without a page refresh. Incrementing a counter in a webpage normally requires writing JavaScript, but Razor Components provides a better approach using C#.

WebApplication1.App/Pages/Counter.cshtml:

@page "/counter"

<h1>Counter</h1>

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

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

@functions {
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

A request for /counter in the browser, as specified by the @page directive at the top, causes the Counter component to render its content. Components render into an in-memory representation of the render tree that can then be used to update the UI in a flexible and efficient way.

Each time the Click me button is selected:

  • The onclick event is fired.
  • The IncrementCount method is called.
  • The currentCount is incremented.
  • The component is rendered again.

The runtime compares the new content to the previous content and only applies the changed content to the Document Object Model (DOM).

Add a component to another component using an HTML-like syntax. Component parameters are specified using attributes or child content. For example, a Counter component can be added to the app's homepage by adding a <Counter /> element to the Index component.

WebApplication1.App/Pages/Index.cshtml:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter />

Run the app. The homepage has its own counter.

To add a parameter to the Counter component, update the component's @functions block:

  • Add a property for IncrementAmount decorated with the [Parameter] attribute.
  • Change the IncrementCount method to use the IncrementAmount when increasing the value of currentCount.

WebApplication1.App/Pages/Counter.cshtml:

@functions {
    int currentCount = 0;

    [Parameter] int IncrementAmount { get; set; } = 1;

    void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

Specify an IncrementAmount parameter in the Home component's <Counter> element using an attribute.

WebApplication1.App/Pages/Index.cshtml:

<Counter IncrementAmount="10" />

Run the app. The homepage has its own counter that increments by ten each time the Click me button is selected.

Next steps

Build your first Razor Components app