---
title: Introduction to Razor Pages in ASP.NET Core
author: tdykstra
description: Explains how Razor Pages in ASP.NET Core makes coding page-focused scenarios easier and more productive than using MVC.
monikerRange: '>= aspnetcore-3.1'
ms.author: tdykstra
ms.date: 08/28/2023
uid: razor-pages/index
---
# Introduction to Razor Pages in ASP.NET Core
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Dave Brock](https://twitter.com/daveabrock), and [Kirk Larkin](https://twitter.com/serpent5)
[!INCLUDE[](~/includes/not-latest-version.md)]
Razor Pages can make coding page-focused scenarios easier and more productive than using controllers and views.
If you're looking for a tutorial that uses the Model-View-Controller approach, see [Get started with ASP.NET Core MVC](xref:tutorials/first-mvc-app/start-mvc).
This document provides an introduction to Razor Pages. It's not a step by step tutorial. If you find some of the sections too advanced, see [Get started with Razor Pages](xref:tutorials/razor-pages/razor-pages-start). For an overview of ASP.NET Core, see the [Introduction to ASP.NET Core](xref:index).
## Prerequisites
:::moniker range=">= aspnetcore-6.0"
# [Visual Studio](#tab/visual-studio)
[!INCLUDE[](~/includes/net-prereqs-vs-6.0.md)]
# [Visual Studio Code](#tab/visual-studio-code)
[!INCLUDE[](~/includes/net-prereqs-vsc-6.0.md)]
# [Visual Studio for Mac](#tab/visual-studio-mac)
[!INCLUDE[](~/includes/net-prereqs-mac-6.0.md)]
---
adds services for Razor Pages to the app.
* adds endpoints for Razor Pages to the .
Consider a basic page:
Model` and is in the same namespace as the page.
The `PageModel` class allows separation of the logic of a page from its presentation. It defines page handlers for requests sent to the page and the data used to render the page. This separation allows:
* Managing of page dependencies through [dependency injection](xref:fundamentals/dependency-injection).
* [Unit testing](xref:test/razor-pages-tests)
The page has an `OnPostAsync` *handler method*, which runs on `POST` requests (when a user posts the form). Handler methods for any HTTP verb can be added. The most common handlers are:
* `OnGet` to initialize state needed for the page. In the preceding code, the `OnGet` method displays the `CreateModel.cshtml` Razor Page.
* `OnPost` to handle form submissions.
The `Async` naming suffix is optional but is often used by convention for asynchronous functions. The preceding code is typical for Razor Pages.
If you're familiar with ASP.NET apps using controllers and views:
* The `OnPostAsync` code in the preceding example looks similar to typical controller code.
* Most of the MVC primitives like [model binding](xref:mvc/models/model-binding), [validation](xref:mvc/models/validation), and action results work the same with Controllers and Razor Pages.
The previous `OnPostAsync` method:
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create.cshtml.cs?name=snippet_OnPostAsync)]
The basic flow of `OnPostAsync`:
Check for validation errors.
* If there are no errors, save the data and redirect.
* If there are errors, show the page again with validation messages. In many cases, validation errors would be detected on the client, and never submitted to the server.
The `Pages/Customers/Create.cshtml` view file:
[!code-cshtml[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create.cshtml)]
The rendered HTML from `Pages/Customers/Create.cshtml`:
[!code-html[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create4.html)]
In the previous code, posting the form:
* With valid data:
* The `OnPostAsync` handler method calls the helper method. `RedirectToPage` returns an instance of . `RedirectToPage`:
* Is an action result.
* Is similar to `RedirectToAction` or `RedirectToRoute` (used in controllers and views).
* Is customized for pages. In the preceding sample, it redirects to the root Index page (`/Index`). `RedirectToPage` is detailed in the [URL generation for Pages](#url_gen) section.
* With validation errors that are passed to the server:
* The `OnPostAsync` handler method calls the helper method. `Page` returns an instance of . Returning `Page` is similar to how actions in controllers return `View`. `PageResult` is the default return type for a handler method. A handler method that returns `void` renders the page.
* In the preceding example, posting the form with no value results in [ModelState.IsValid](xref:Microsoft.AspNetCore.Mvc.ModelBinding.ModelStateDictionary.IsValid) returning false. In this sample, no validation errors are displayed on the client. Validation error handling is covered later in this document.
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create.cshtml.cs?name=snippet_OnPostAsync&highlight=6-9)]
* With validation errors detected by client side validation:
* Data is **not** posted to the server.
* Client-side validation is explained later in this document.
The `Customer` property uses [`[BindProperty]`](xref:Microsoft.AspNetCore.Mvc.BindPropertyAttribute) attribute to opt in to model binding:
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create.cshtml.cs?name=snippet_OnPostAsync&highlight=1-2)]
`[BindProperty]` should **not** be used on models containing properties that should not be changed by the client. For more information, see [Overposting](xref:data/ef-rp/crud#overposting).
Razor Pages, by default, bind properties only with non-`GET` verbs. Binding to properties removes the need to writing code to convert HTTP data to the model type. Binding reduces code by using the same property to render form fields (`` [Anchor Tag Helper](xref:mvc/views/tag-helpers/builtin-th/anchor-tag-helper) used the `asp-route-{value}` attribute to generate a link to the Edit page. The link contains route data with the contact ID. For example, `https://localhost:5001/Edit/1`. [Tag Helpers](xref:mvc/views/tag-helpers/intro) enable server-side code to participate in creating and rendering HTML elements in Razor files.
The `Index.cshtml` file contains markup to create a delete button for each customer contact:
[!code-cshtml[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Index.cshtml?name=snippet_Delete)]
The rendered HTML:
```html
delete
```
When the delete button is rendered in HTML, its [formaction](https://developer.mozilla.org/docs/Web/HTML/Element/button#attr-formaction) includes parameters for:
* The customer contact ID, specified by the `asp-route-id` attribute.
* The `handler`, specified by the `asp-page-handler` attribute.
When the button is selected, a form `POST` request is sent to the server. By convention, the name of the handler method is selected based on the value of the `handler` parameter according to the scheme `OnPost[handler]Async`.
Because the `handler` is `delete` in this example, the `OnPostDeleteAsync` handler method is used to process the `POST` request. If the `asp-page-handler` is set to a different value, such as `remove`, a handler method with the name `OnPostRemoveAsync` is selected.
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Index.cshtml.cs?name=snippet2)]
The `OnPostDeleteAsync` method:
* Gets the `id` from the query string.
* Queries the database for the customer contact with `FindAsync`.
* If the customer contact is found, it's removed and the database is updated.
* Calls to redirect to the root Index page (`/Index`).
### The Edit.cshtml file
[!code-cshtml[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Edit.cshtml?highlight=1)]
The first line contains the `@page "{id:int}"` directive. The routing constraint `"{id:int}"` tells the page to accept requests to the page that contain `int` route data. If a request to the page doesn't contain route data that can be converted to an `int`, the runtime returns an HTTP 404 (not found) error. To make the ID optional, append `?` to the route constraint:
```cshtml
@page "{id:int?}"
```
The `Edit.cshtml.cs` file:
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Edit.cshtml.cs?name=snippet)]
## Validation
Validation rules:
* Are declaratively specified in the model class.
* Are enforced everywhere in the app.
The namespace provides a set of built-in validation attributes that are applied declaratively to a class or property. DataAnnotations also contains formatting attributes like [`[DataType]`](xref:System.ComponentModel.DataAnnotations.DataTypeAttribute) that help with formatting and don't provide any validation.
Consider the `Customer` model:
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Models/Customer.cs)]
Using the following `Create.cshtml` view file:
[!code-cshtml[](~/razor-pages/index/6.0sample/RazorPagesContacts/Pages/Customers/Create3.cshtml?highlight=3,8-9,15-99)]
The preceding code:
* Includes jQuery and jQuery validation scripts.
* Uses the `
` and `.
Customers Index Page `
* `RedirectToPage("./Index")`
The absolute page name `/Index` is used to generate URLs to the `Pages/Index.cshtml` page. For example:
* `Url.Page("/Index", ...)`
* `Home Index Page `
* `RedirectToPage("/Index")`
The page name is the path to the page from the root */Pages* folder including a leading `/` (for example, `/Index`). The preceding URL generation samples offer enhanced options and functional capabilities over hard-coding a URL. URL generation uses [routing](xref:mvc/controllers/routing) and can generate and encode parameters according to how the route is defined in the destination path.
URL generation for pages supports relative names. The following table shows which Index page is selected using different `RedirectToPage` parameters in `Pages/Customers/Create.cshtml`.
| RedirectToPage(x)| Page |
| ----------------- | ------------ |
| RedirectToPage("/Index") | *Pages/Index* |
| RedirectToPage("./Index"); | *Pages/Customers/Index* |
| RedirectToPage("../Index") | *Pages/Index* |
| RedirectToPage("Index") | *Pages/Customers/Index* |
`RedirectToPage("Index")`, `RedirectToPage("./Index")`, and `RedirectToPage("../Index")` are *relative names*. The `RedirectToPage` parameter is *combined* with the path of the current page to compute the name of the destination page.
Relative name linking is useful when building sites with a complex structure. When relative names are used to link between pages in a folder:
* Renaming a folder doesn't break the relative links.
* Links are not broken because they don't include the folder name.
To redirect to a page in a different [Area](xref:mvc/controllers/areas), specify the area:
```csharp
RedirectToPage("/Index", new { area = "Services" });
```
For more information, see and .
## ViewData attribute
Data can be passed to a page with . Properties with the `[ViewData]` attribute have their values stored and loaded from the .
In the following example, the `AboutModel` applies the `[ViewData]` attribute to the `Title` property:
```csharp
public class AboutModel : PageModel
{
[ViewData]
public string Title { get; } = "About";
public void OnGet()
{
}
}
```
In the About page, access the `Title` property as a model property:
```cshtml
@Model.Title
```
In the layout, the title is read from the ViewData dictionary:
```cshtml
@ViewData["Title"] - WebApplication
...
```
## TempData
ASP.NET Core exposes the . This property stores data until it's read. The and methods can be used to examine the data without deletion. `TempData` is useful for redirection, when data is needed for more than a single request.
The following code sets the value of `Message` using `TempData`:
[!code-csharp[](~/razor-pages/index/sample/RazorPagesContacts2/Pages/Customers/CreateDot.cshtml.cs?highlight=10-11,25&name=snippet_Temp)]
The following markup in the `Pages/Customers/Index.cshtml` file displays the value of `Message` using `TempData`.
```cshtml
Msg: @Model.Message
```
The `Pages/Customers/Index.cshtml.cs` page model applies the `[TempData]` attribute to the `Message` property.
```csharp
[TempData]
public string Message { get; set; }
```
For more information, see [TempData](xref:fundamentals/app-state#tempdata).
` and before `Async` (if present). In the preceding example, the page methods are OnPost**JoinList**Async and OnPost**JoinListUC**Async. With *OnPost* and *Async* removed, the handler names are `JoinList` and `JoinListUC`.
[!code-cshtml[](~/razor-pages/index/sample/RazorPagesContacts2/Pages/Customers/CreateFATH.cshtml?name=snippet_Handlers)]
Using the preceding code, the URL path that submits to `OnPostJoinListAsync` is `https://localhost:5001/Customers/CreateFATH?handler=JoinList`. The URL path that submits to `OnPostJoinListUCAsync` is `https://localhost:5001/Customers/CreateFATH?handler=JoinListUC`.
## Custom routes
Use the `@page` directive to:
* Specify a custom route to a page. For example, the route to the About page can be set to `/Some/Other/Path` with `@page "/Some/Other/Path"`.
* Append segments to a page's default route. For example, an "item" segment can be added to a page's default route with `@page "item"`.
* Append parameters to a page's default route. For example, an ID parameter, `id`, can be required for a page with `@page "{id}"`.
A root-relative path designated by a tilde (`~`) at the beginning of the path is supported. For example, `@page "~/Some/Other/Path"` is the same as `@page "/Some/Other/Path"`.
If you don't like the query string `?handler=JoinList` in the URL, change the route to put the handler name in the path portion of the URL. The route can be customized by adding a route template enclosed in double quotes after the `@page` directive.
[!code-cshtml[](~/razor-pages/index/sample/RazorPagesContacts2/Pages/Customers/CreateRoute.cshtml?highlight=1)]
Using the preceding code, the URL path that submits to `OnPostJoinListAsync` is `https://localhost:5001/Customers/CreateFATH/JoinList`. The URL path that submits to `OnPostJoinListUCAsync` is `https://localhost:5001/Customers/CreateFATH/JoinListUC`.
The `?` following `handler` means the route parameter is optional.
## Collocation of JavaScript (JS) files
[!INCLUDE[](~/includes/js-collocation.md)]
## Advanced configuration and settings
The configuration and settings in following sections is not required by most apps.
To configure advanced options, use the overload that configures :
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Program.cs?name=snippet_ac&highlight=5-9)]
Use the to set the root directory for pages, or add application model conventions for pages. For more information on conventions, see [Razor Pages authorization conventions](xref:security/authorization/razor-pages-authorization).
To precompile views, see [Razor view compilation](xref:mvc/views/view-compilation).
### Specify that Razor Pages are at the content root
By default, Razor Pages are rooted in the */Pages* directory. Add to specify that your Razor Pages are at the [content root](xref:fundamentals/index#content-root) () of the app:
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Program.cs?name=snippet_cr&highlight=5-9)]
### Specify that Razor Pages are at a custom root directory
Add to specify that Razor Pages are at a custom root directory in the app (provide a relative path):
[!code-csharp[](~/razor-pages/index/6.0sample/RazorPagesContacts/Program.cs?name=snippet_crd&highlight=5-9)]
## Additional resources
* See [Get started with Razor Pages](xref:tutorials/razor-pages/razor-pages-start), which builds on this introduction.
* [Authorize attribute and Razor Pages](xref:security/authorization/simple#aarp)
* [Download or view sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/razor-pages/index/6.0sample)
*
*
*
*
*
*
*
*
:::moniker-end
[!INCLUDE[](~/razor-pages/index/includes/index35.md)]