ASP.NET Core 2.0 Razor Page Handlers

I have been using Razor page handlers recently in our web application to handle the interaction between client-side code and server-side code. There have previously been several ways of achieving this using AJAX. And this is still possible using ASP.NET Core 2.0 as I will demonstrate later in this article. There is also a TagHelper that allows you to invoke a page handler from within your Razor page. I will demonstrate both of these within this article.

The purpose of this article is not to give a detailed, step-by-step account of both of these methods. Instead, I will give an overview of them so you can see how they both work, then investigate them further if you want to implement them in your own application.

By way of introduction, a page handler is a page method that responds to a particular HTTP method e.g. Get, Post, Delete, Put etc. Page handler names are preceded by On. So the default page handlers include OnGet, OnPost etc. The name of the handler is appended to the default page handler name e.g. OnGetCustomer would be a page handler that is invoked to retrieve a specific customer. OnPostOrder would be used to post an order.

It is definitely worth looking at page handlers in more depth. I will assume the reader is familiar with page handlers. If this is not the case, please read up on them first. Okay, with that out of the way, let’s dive into the detail of the article and describe how Razorpage handlers can be used within an application.

I will start by firstly looking at the ASP.NET Core TagHelper method. This is the most straight-forward. This allows you to bind a client-side event such as a button-click to a server-side page handler. Here is a very simple page handler that you would define in the .cshtml page.

Hide Copy Code

<form asp-page-handler="Customers" method="GET">
    <button class="btn btn-default">List Customers</button>
</form>

In the example above I have created a simple Razor page handler that fetches a list of customers. The name of the page handler given in the TagHelper syntax would therefore be OnGetCustomers. Here is the definition of the page handler in the .cshtml.cs file.

Hide Copy Code

public void OnGetCustomers()
{
    //fetch a list of customer here!
}

ASP.NET Core 2.0 allows you to add multiple page handlers to the same page. You could therefore add page handlers for adding, editing, deleting and viewing customers all on the same page.

You can also pass parameters to page handlers. So if you wanted to fetch a specific customer you could achieve this using the following code example.

Hide Copy Code

<form asp-page-handler="Customer" method="GET">
    <button class="btn btn-default">Get Customer</button>
    <input id="handler_parameter" type="hidden" name="selectedCustomerID" value="0"/>
</form>
public void OnGetCustomer(int selectedCustomerID)
{
    //fetch a specific customer here!
}

Obviously you would need to set the value of the input control to some meaningful value. In my particular case, I am setting the value when the click event of a Kendo UI TreeView is raised. In the event click for the Kendo control I am using JQuery to set the value to the ID of the currently selected item in the TreeView. Then when the user wants to perform an action on the item (edit, delete, view etc), the ID is passed to the page handler.

Here is the Keno UI TreeView click event when an item is selected.

Hide Copy Code

function onDocumentViewNode(data) {
    $("#handler_parameter")[0].value = data.id;
}

It is worth noting that the name of the input control must be the same as the name of the parameter on the page handler. In the above example they are set to “selectedCustomerID”. If they do not match, then nothing is passed to the page handler.

Another way to use Razor page handlers is by using AJAX. With AJAX you are able to invoke requests using GET, POST etc. These can be RESTful requests for example. With ASP.NET Core 2.0 they can also be Razor page handlers.

Here is a simple example of invoking a Razor page handler using AJAX.

Hide Copy Code

$.ajax({
    type: "GET",
    url: "/Customer?handler=customer&selectedCustomerID="+ data.id,
    contentType: "application/json",
    dataType: "json",
    success: function (response) {
      //do something here
    },
    failure: function (response) {
      console.log(JSON.stringify(response));
    }
});

Razor page handlers open up massive opportunities for creating highly flexible applications. The interaction between the client-code and server-code is baked into the very fabric of the .NET Core Framework. To achieve such seamless interaction previously would have involved writing a lot of custom code, much of it probably spagetti-like or very clunky. With ASP.NET Core, interaction between the client and server is now totally seamless and extremely easy to achieve. Razor page handlers are highly flexible (you can respond to any HTTP verb) and very performant. They also lead to more cleaner code (there is far less code to write), and can be unit-tested (by separatng out the code into further layers of separation). Using them is really a no-brainer.

I use both of these methods in my web applications, and they allow me to write very flexible code. I have recently used both of them to interact with Kendo UI controls which give the application a much higher degree of responsiveness and flexibility.