Tutorial: Get started with Razor Pages in ASP.NET Core

By Rick Anderson

We recommend you follow the ASP.NET Core 2.1 version of this tutorial. It's much easier to follow and covers more features. Select ASP.NET Core 2.1 in the version selector.

Version selector in TOC

This tutorial teaches the basics of building an ASP.NET Core Razor Pages web app. Razor Pages is the recommended way to build UI for web apps in ASP.NET Core.

There are three versions of this tutorial:

View or download sample code (how to download)

Prerequisites

Visual Studio 2017 version 15.7.3 or later with the following workloads:

  • ASP.NET and web development
  • .NET Core cross-platform development

Create a Razor web app

  • From the Visual Studio File menu, select New > Project.
  • Create a new ASP.NET Core Web Application. Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the namespaces will match when you copy/paste code. new ASP.NET Core Web Application
  • Select ASP.NET Core 2.1 in the dropdown, and then select Web Application.

new ASP.NET Core Web Application

The Visual Studio template creates a starter project:

Solution Explorer

Press F5 to run the app in debug mode or Ctrl-F5 to run without attaching the debugger. Select Accept to consent to tracking. This app doesn't track personal information. The template generated code includes assets to help meet General Data Protection Regulation (GDPR).

Home or Index page

The following image shows the app after accepting tracking:

Home or Index page

  • Visual Studio starts IIS Express and runs the app. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for your local computer. Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a random port is used for the web server. In the preceding image, the port number is 5001. When you run the app, you'll see a different port number.
  • Launching the app with Ctrl+F5 (non-debug mode) allows you to make code changes, save the file, refresh the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch the app and view changes.

The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on the size of your browser window, you might need to click the navigation icon to show the links.

Home or Index page

Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links go to the About and Contact pages, respectively.

Project files and folders

The following table lists the files and folders in the project. For this tutorial, the Startup.cs file is the most important to understand. You don't need to review each link provided below. The links are provided as a reference when you need more information on a file or folder in the project.

File or folder Purpose
wwwroot Contains static assets. See Static files.
Pages Folder for Razor Pages.
appsettings.json Configuration
Program.cs Configures the host of the ASP.NET Core app.
Startup.cs Configures services and the request pipeline. See Startup.

The Pages/Shared folder

The _Layout.cshtml file contains common HTML elements (script and stylesheet links) and sets the layout for the app. For example when you select RazorPagesMovie, Home, About or Contact, a common set of elements appears in the webpage. The common elements include the navigation menu at the top and the header at the bottom of the window. For more information, see Layout.

The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When the Create and Edit pages are added later in the tutorial, the _ValidationScriptsPartial.cshtml file is used.

The _CookieConsentPartial.cshtml file provides a navigation bar and content to summarize the privacy and cookie use policy. For more information on the GDPR assets included in the project, see EU General Data Protection Regulation (GDPR) support in ASP.NET Core).

The Pages folder

The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for more information.

The _ViewImports.cshtml file contains Razor directives that are imported into each Razor Page. See Importing Shared Directives for more information.

The About, Contact and Index pages are basic pages you can use to start an app. The Error page is used to display error information.

Use F7 to toggle between a Razor Page and the PageModel

To enable F7 toggling between a Razor Page (*.cshtml file) and the C# file (*.cshtml.cs):

  • Select Tools > Options > Environment > Keyboard
  • Enter ToggleRazorView in Show commands containing.
  • Select EditorContextMenus.CodeWindow.ToggleRazorView
  • In the Press shortcut keys entry box, press F7.
  • Select Assign > OK

tutorials

Prerequisites

Visual Studio 2017 version 15.7.3 or later with the following workloads:

  • ASP.NET and web development
  • .NET Core cross-platform development

Create a Razor web app

  • From the Visual Studio File menu, select New > Project.

  • Create a new ASP.NET Core Web Application. Name the project RazorPagesMovie. It's important to name the project RazorPagesMovie so the namespaces will match when you copy/paste code. new ASP.NET Core Web Application

  • Select ASP.NET Core 2.0 in the dropdown, and then select Web Application.

    Note

    To use ASP.NET Core with .NET Framework, you must first select .NET Framework from the leftmost drop-down in the dialog, then you can select the desired ASP.NET Core version.

    Web Application (Razor Pages)

The Visual Studio template creates a starter project:

Solution Explorer

Press F5 to run the app in debug mode or Ctrl-F5 to run without attaching the debugger

Home or Index page

  • Visual Studio starts IIS Express and runs your app. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for your local computer. Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a random port is used for the web server. In the preceding image, the port number is 5000. When you run the app, you'll see a different port number.
  • Launching the app with Ctrl+F5 (non-debug mode) allows you to make code changes, save the file, refresh the browser, and see the code changes. Many developers prefer to use non-debug mode to quickly launch the app and view changes.

The default template creates RazorPagesMovie, Home, About and Contact links and pages. Depending on the size of your browser window, you might need to click the navigation icon to show the links.

Home or Index page

Test the links. The RazorPagesMovie and Home links go to the Index page. The About and Contact links go to the About and Contact pages, respectively.

Project files and folders

The following table lists the files and folders in the project. For this tutorial, the Startup.cs file is the most important to understand. You don't need to review each link provided below. The links are provided as a reference when you need more information on a file or folder in the project.

File or folder Purpose
wwwroot Contains static files. See Static files.
Pages Folder for Razor Pages.
appsettings.json Configuration
Program.cs Hosts the ASP.NET Core app.
Startup.cs Configures services and the request pipeline. See Startup.

The Pages folder

The _Layout.cshtml file contains common HTML elements (scripts and stylesheets) and sets the layout for the application. For example, when you click on RazorPagesMovie, Home, About or Contact, you see the same elements. The common elements include the navigation menu on the top and the header on the bottom of the window. See Layout for more information.

The _ViewImports.cshtml file contains Razor directives that are imported into each Razor Page. See Importing Shared Directives for more information.

The _ViewStart.cshtml sets the Razor Pages Layout property to use the _Layout.cshtml file. See Layout for more information.

The _ValidationScriptsPartial.cshtml file provides a reference to jQuery validation scripts. When we add Create and Edit pages later in the tutorial, the _ValidationScriptsPartial.cshtml file will be used.

The About, Contact and Index pages are basic pages you can use to start an app. The Error page is used to display error information. The Privacy page allows you to specify details about your site's privacy policy.