Razor Project Overview

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

WebAPI and RazorApp are both top-level projects in the solution and each contain their own appsettings.json. Before you run the application, set the default project to RazorApp and ensure the appsettings.json is configured as needed.

This guide will only cover the differences between RazorApp versus WebAPI. The following sections go into more detail on each difference in the Razor project.

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 the Web API project and the Razor project, the first being the use of pages, and the second being that cookies are used as the primary authentication mechanism.  In a multi-page environment, cookies are easier to work with.

Map Razor Pages

The most obvious difference is that we’re working with Razor pages instead of serving a static JS single-page-application. To accommodate Razor pages, in the top level program, we include the mapRazorPages directive. 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. JWT tokens will simply not suffice for multi-page authorization. Cookies are more suitable when dealing with pages and there are three major changes needed to make this happen.

In Service Collection Extensions, in the Razor 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 the Infrastructure project. If you plan to use Razor exclusively, you can remove the Token Service.

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 dictate the style and functionality of the theme.

All of the third party vendor components like charts, range slider, data tables, etc. need their 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 reference to it in the Layout.

There’s also a Guest Layout view, for all non-application views like the login screens.

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 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 with ajax.

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.