abp.ajax,aspnetboilerplate

Problems of AJAX Operations

Performing AJAX calls is frequently used by modern applications.

Especially in SPAs (Single Page Applications), it's almost the only way

of communicating with the server. An AJAX call consists of some

repeating steps:

On the client-side, the JavaScript code should supply an URL,

optionally some data, and it should select a method (POST, GET...) to perfom an AJAX

call. It must wait and handle the return value. There may be an error

(network error generally) while performing a call to the server. Or there

may be some error on the server-side and server may send a failed response

with an error message. The client-side code must handle these and optionally

notify a user (like show an error dialog). If there is no error and the server

returns data, the client must also handle it. In addition to this, you generally want

to block some part or a whole area of the screen and show a busy indicator

until an AJAX operation completes.

Server-code should get the request, perform some server-side code, catch

exceptions and return a valid response to the client. If an error

occurs, it may optionally send an error message to the client. If

it's a validation error, the server may want to the add descriptions to validation problems.

In the case of a successful request, it may send return values to the client.

The ASP.NET Boilerplate Way

ASP.NET Boilerplate automates some of these steps by wrapping AJAX calls

with the abp.ajax function. An example ajax call:

var newPerson = {

name: 'Dougles Adams',

age: 42

};

abp.ajax({

url: '/People/SavePerson',

data: JSON.stringify(newPerson)

}).done(function(data) {

abp.notify.success('Created new person with id = ' + data.personId);

});

abp.ajax gets options as an object. You can pass any valid parameter

into jQuery's $.ajax method.

There are some defaults here: the dataType is 'json', the type

is 'POST', and the contentType is 'application/json' (We're

calling JSON.stringify to convert a JavaScript object into a JSON string

before sending it to the server). You can override these defaults by passing

options to abp.ajax.

abp.ajax returns a PeopleController's SavePerson action.

In the done handler, we fetched the database id for the newly created

person and showed a success notification (See notification

API). Let's see the MVC

controller for this AJAX call:

public class PeopleController : AbpController

{

[HttpPost]

public JsonResult SavePerson(SavePersonModel person)

{

//TODO: save new person to database and return new person's id

return Json(new {PersonId = 42});

}

}

The SavePersonModel contains the Name and Age properties.

The SavePerson action is marked with HttpPost, since abp.ajax's default method

is POST. We simplified the method implementation by returning an anonymous

object.

This seams pretty straightforward, but there are some important things behind

the scenes that are handled by ASP.NET Boilerplate. Let's dive into those

details...

AJAX Return Messages

When we directly return an object with PersonId = 2, ASP.NET Boilerplate

wraps it with an MvcAjaxResponse object. The actual AJAX response is

something like this:

{

"success": true,

"result": {

"personId": 42

},

"error": null,

"targetUrl": null,

"unAuthorizedRequest": false,

"__abp": true

}

Here all the properties are camelCase (since it's conventional in

JavaScript) even if they are PascalCase on the server-side's code. Here's

an explanation of all the fields:

success: A boolean value (true or false) that indicates the success

status of the operation. If this is true, abp.ajax resolves the

promise and calls the done handler. If it's false (if there is

an exception thrown in the method call), it calls the fail handler and

shows the error message using the

abp.message.error

function.

result: The actual return value of the controller action. It's valid

if the request was a success and if the server sent a return value.

error: If success is false, this field is an object that

contains the message and details fields.

targetUrl: This provides a way for the server to

redirect the client to another url if needed.

unAuthorizedRequest: This provides a method for the server

to inform the client that this operation is not authorized or the user is

not authenticated. abp.ajax reloads the current page if this is

true.

__abp: A special signature that is returned by an ABP wrapped

responses. You don't use this yourself, but abp.ajax handles it.

This return format is recognized and handled by the abp.ajax function.

The done handler in abp.ajax gets the actual return value of the

controller (An object with a personId property) if there is no error.

Handling Errors

As described above, ASP.NET Boilerplate handles exceptions on the server and

returns an object with an error message like this:

{

"targetUrl": null,

"result": null,

"success": false,

"error": {

"message": "An internal error occurred during your request!",

"details": "..."

},

"unAuthorizedRequest": false,

"__abp": true

}

As you can see, success is false and result is null. abp.ajax

handles this object and shows an error message to the user using the

abp.message.error function.

If your server-side code throws an exception type of

UserFriendlyException, it directly shows the exception's message to the

user. Otherwise, it hides the actual error (writes error to logs) and

shows a standard ''An internal error occurred..." message to the user.

All these are automatically done by ASP.NET Boilerplate.

You may want to disable displaying the message for a particular AJAX call.

If so, add abpHandleError: false into the abp.ajax options.

HTTP Status Codes

ABP returns the following HTTP status codes when exceptions occur:

401 for unauthenticated requests (Used has not logged in and the

server action needs authentication).

403 for unauthorized requests.

500 for all other exception types.

WrapResult and DontWrapResult Attributes

You can control the wrapping using WrapResult and the DontWrapResult

attributes for an action or all actions in a controller.

ASP.NET MVC Controllers

ASP.NET Boilerplate wraps (as described above) ASP.NET MVC

action results by default if the return type is a JsonResult (or

Task for async actions). You can change this by using the

WrapResult attribute as shown below:

public class PeopleController : AbpController

{

[HttpPost]

[WrapResult(WrapOnSuccess = false, WrapOnError = false)]

public JsonResult SavePerson(SavePersonModel person)

{

//TODO: save new person to database and return new person's id

return Json(new {PersonId = 42});

}

}

As a shortcut, we can simply use the [DontWrapResult] attribute which is identical

for this example.

You can change this default behaviour from the startup

configuration (using

Configuration.Modules.AbpMvc()...).

ASP.NET Web API Controllers

ASP.NET Boilerplate does not wrap Web API actions by default if

an action has successfully executed. You can add WrapResult to actions or

controllers if you need to, but by default it wraps exceptions.

You can change this default behavior from the startup

configuration (using

Configuration.Modules.AbpWebApi()...).

Dynamic Web API Layer

ASP.NET Boilerplate wraps dynamic web api layer methods by

default. You can change this behavior using the WrapResult and

DontWrapResult attributes in the interface of your application

service.

You can change this default behaviour from the startup

configuration (using

Configuration.Modules.AbpWebApi()...).

ASP.NET Core Controllers

ABP automatically wraps results for a JsonResult, ObjectResult and any

object which does not implement IActionResult.  See the ASP.NET Core

documentation for more info.

You can change this default behavior from the startup

configuration (using

Configuration.Modules.AbpAspNetCore()...).

Dynamic Web API Layer

While ASP.NET Boilerplate provides a mechanism to make AJAX calls easy,

in a real-world application it's typical to write a JavaScript function

for every AJAX call. For example:

//Create a function to abstract AJAX call

var savePerson = function(person) {

return abp.ajax({

url: '/People/SavePerson',

data: JSON.stringify(person)

});

};

//Create a new person

var newPerson = {

name: 'Dougles Adams',

age: 42

};

//Save the person

savePerson(newPerson).done(function(data) {

abp.notify.success('created new person with id = ' + data.personId);

});

This is good practice, but time-consuming and tedious, because you have to write a

function for every ajax call. ASP.NET can automatically generate these

type of functions for application

services and controllers.

Read the dynamic web api layer

documentation for the Web API and ASP.NET Core documentation for the ASP.NET

Core integration.