Are handler methods technically optional in a Razor Pages PageModel?

[vaporizersreborn]

I recently had to add some makeshift API endpoints to a Razor Pages app that I could call from any other page on the site using client-side JS. I found an article that achieved this by adding a new empty Razor content page with no HTML, and a backing PageModel with some handler methods to serve as API endpoints. I went with this approach for now to quickly get a working MVP until I can learn more about .NET Core's Web APIs.

While it has turned out great for my MVP, it has kinda gone against my existing understanding of how Razor Pages works. I thought that a Razor Page needed to have an OnGet() or OnGetAsync() default handler method at minimum to work, either with a void return type to implicitly return the associated Razor content page or to explicitly return a PageResult object.

I also thought that a Razor Page must have some HTML associated with it in the associated .cshtml file, but it looks like that's not the case, given that my handler API endpoints work just fine returning JsonResult objects and in the routing system. It makes me curious if I could technically implement a front-facing REST API in this way (I wouldn't actually do this, but would it work?).

I tested out adding some basic HTML to a random Razor content page and having a PageModel without any handler methods defined (a completely empty class), and when I navigated to the URL for that page the HTML for it still loaded. So it looks like by default, an OnGet() handler method is defined for you that implicitly returns the associated Razor content page? Unless I override it with a definition of my own, it uses this default? Is that accurate?

My code looks something like this for reference:

My Razor content page:

@page  
@model TestRazorPagesApp.Pages.Test

My backing PageModel class:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace TestRazorPagesApp.Pages;

[Authorize]
public class Test : PageModel
{
    public IActionResult OnGetXDataObj() 
    {
        return new JsonResult(data);
    }

    public IActionResult OnGetYDataObj() 
    {
        return new JsonResult(data);
    }
}

Appreciate anyone who is able to provide clarity on this.

[MentalOfCrow]

Yes—handler methods are optional, but the precise behavior is not that ASP.NET Core generates a hidden OnGet method.

The Razor Pages invoker does two relevant things:

1. It selects and invokes a matching handler when one exists.
2. If no handler produced a result, it creates a PageResult.

You can see that directly in PageActionInvoker; the source even describes it as an implicit return Page() when there is no handler:
https://github.com/dotnet/aspnetcore/blob/main/src/Mvc/Mvc.RazorPages/src/Infrastructure/PageActionInvoker.cs#L250-L299

So a GET request to a Razor Page whose PageModel has no OnGet can render its .cshtml normally. If that file contains only @page and @model, the response can simply have an empty rendered body. The important distinction is that the .cshtml file with @page creates the endpoint; a PageModel class by itself does not.

Your named handlers are also valid Razor Pages handlers. For example:

GET /Test?handler=XDataObj -> OnGetXDataObj()
GET /Test?handler=YDataObj -> OnGetYDataObj()

Returning JsonResult from either handler means that result is executed instead of rendering the page.

That can be reasonable for a small page-specific read operation, but I would not use it as the general REST API architecture. Page handlers are selected after the page itself has been routed, so they cannot each define an independent route or use HTTP method route attributes. ASP.NET Core documents that limitation here:
https://learn.microsoft.com/en-us/aspnet/core/diagnostics/mvc1002

Minimal APIs or API controllers give each operation an explicit route and HTTP method and fit status codes, content negotiation, authorization policies, and OpenAPI much more naturally. They also keep the API contract independent from the UI page lifecycle.

In short:

• no handler is required merely to render a Razor Page;
• there is no generated OnGet; the invoker supplies an implicit PageResult;
• named handlers returning JSON work technically;
• for a real REST surface, prefer Minimal APIs or API controllers.

Also avoid using GET handlers for state-changing operations; use the appropriate non-GET verb and apply antiforgery protection where browser cookie authentication is involved.