Razor Pages are the recommended way to build traditional web apps using ASP.NET. If you are familiar with MVC (model view controller), then Razor pages are 99% the same, with the main differences bein organizational. In Razor pages, the view and the controller are blended into one. Routing follows a simple folder structure; it directly maps to the folder and file hierarchy, making it easier to understand and debug.

Razor remains a popular choice for building web applications despite the rise of Single Page Applications (SPAs) because sometimes its best to build with what you know.

Overview

The RazorApp project is a .NET web application which uses the same domain, infrastructure, and application code as the WebAPI. RazorApp is largely identical to WebAPI and it’s recommended to read about the WebAPI and .NET solution first.

This guide will only cover the differences between using Razor Pages versus a single page app UI configuration (which generates WebAPI as the presentation layer).

In the dependencies list for RazorApp, a notification will indicate there are missing libraries. These are development dependencies and are not needed to run the app. They are required to customize the styles. Read the next section to learn about customizing the styles.

Differences from WebAPI

There are two major differences between a single page application (WebAPI) project and a Razor project, the first being the use of pages, and the second being that cookies are used as the primary authentication mechanism. 

Map Razor Pages

When working with Razor pages, a mapRazorPages directive is included in the top level program. The framework will follow convention and check in the Pages folder to build routes to page resources.

Cookie Authorization

Since we are working with a server-side rendered, multi-page environment, authorization is handled in a fundamentally different manner as cookies are more suitable than JWT tokens. Three major changes are needed to make this happen.

In Service Collection Extensions, in the RazorApp project, the last section, Cookie Settings replaces JWT Settings and contain the necessary configuration for Cookies.

Next, the Current Tenant User Service reads claims from a cookie instead a JWT token.

Lastly, a new Login Service uses ASP Identity Sign In Manager to sign the user in. Once a user is signed in, every page sent back to the user will include a cookie. This Login Service replaces the function of the Token Service, found in Infrastructure/Auth.

Pages Structure

Razor pages are views with a code-behind file, similar to controllers in MVC. Routes are based on the names of the folders, with the exception of the Shared folder, which contain the global layout and navigation elements.

Layout

The Layout view is the global layout structure with side navigation, footer, and top navigation bar. It also contains all the linked references to CSS and JS resources that control the style / functionality of the theme.

All of the third party vendor components like charts, range slider, data tables, etc. need their own CSS and JS to function. These resources can be found within wwwroot/assets/vendor. Anytime a new package or tool is added, create a folder for its’ CSS / JS within /vendor and provide a reference link in Layout.

There’s also a Guest Layout view, for all non-application views like login and forgot password.

Pages

The rest of the application pages are found in the following folders:

• Authentication
• Profile
• Products
• Users
• Tenants

Razor pages contain a code-behind file, which you can access by expanding the .cshtml file in the solution explorer. Anything that’s needed by the initial page load should be defined as part of the page model in the code-behind. DTOs will facilitate jQuery unobtrusive validation functionality if named by convention. Even though this is a page-based UI, much of the CRUD operations are handled with AJAX requests to API controllers to avoid page reloads and provide a better UX.

All pages have a Scripts section which links to static files in wwwroot/assets/js/pages.

Template Resources

Template Resources contains all of the component samples. These are divided into Base UI and Extended UI:

• Base UI elements are basic Bootstrap elements like form input, modals, buttons, etc.
• Extended UI elements use third-party packages to function like charts, ranger slider, etc. The script code is kept in-page for sample UI elements.

Next Steps

The next guide will explore static assets in wwwroot, which contains the styling and theme.