The RazorApp project is a .NET web application which uses the same domain, infrastructure, and application code as the WebAPI if you generated a project with the single page app (spa) -ui option. 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 (WebAPI).

In dependencies for the RazorApp, NPM will be shown with a notification that some libraries are not installed. These are development dependencies and do not need to be present for the app to run. 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, we must include a mapRazorPages directive in the top level program. With that, 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-rendered multi-page environment, authorization needs to be approached in a fundamentally different manner. Cookies are more suitable than JWT tokens for multi-page authorization. There are three major changes needed to make this happen.

In Service Collection Extensions, in the RazorApp project, the last section, Cookie Settings replaces JWT Settings. These changes reflect the necessary configuration for using Cookies within the project.

Next, the Current Tenant User Service contains one change: reading claims from a Cookie instead a JWT token.

Finally, there is a new Login Service, which uses the built in 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 you add a new package or tool, you should create a folder for its’ CSS / JS within /vendor and provide a link reference to it in the Layout.

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

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 defined here will facilitate jQuery unobtrusive validation functionality if named by convention. Even though this is a pages based UI, much of the CRUD operations are handled via API controllers behind the scenes to avoid page reloads and provide a better UX.

All pages have a Scripts section towards the bottom. These page scripts can be found as static files in wwwroot/assets/js/pages. Most functionality has been delegated these JS scripts; table data and CRUD operations are typically handled using ajax calls.

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. Script 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.