JavaScripts Clients¶

It is typical to consume your HTTP APIs from your JavaScript code. To do that, you normally deal with low level AJAX calls, like $.ajax, or abp.ajax. ABP framework provides a better way to call your HTTP APIs from your JavaScript code: JavaScript API Client Proxies!

Static vs Dynamic JavaScript Client Proxies¶

ABP provides two types of client proxy generation system:

• Dynamic JavaScript Client Proxy

• Static JavaScript Client Proxy

Development-time (static) client proxy generation has a slight performance advantage since it doesn't need to obtain the HTTP API definition on runtime. However, you should re-generate the client proxy code whenever you change your API endpoint definition.

On the other hand, dynamic client proxies are generated on runtime and provides an easier development experience.

Static Client Proxy¶

Server side must be up and running while generating the client proxy code. So, first run the application that hosts your HTTP APIs (can be the Web application or the HttpApi.Host application depending on your solution structure).

Open a command-line terminal in the root folder of your web project (.csproj) and type the following command:

abp generate-proxy -t js -u https://localhost:44372

If you haven't installed yet, you should install the ABP CLI.

This command should generate the following files under the ClientProxies folder

Dynamic Client Proxy¶

You can call any of the methods just like calling a JavaScript function. The JavaScript function has the identical function name, parameters and the return value with the C# method.

Disabling Dynamic JavaScript Proxies¶

When you create an application or module, the dynamic client proxy generation approach is used by default. If you want to use the statically generated client proxies for your application, you should explicitly disable it for your application or module in the ConfigureServices method of your module class as like in the following example:

Configure<DynamicJavaScriptProxyOptions>(options =>
{
    options.DisableModule("app");
});

app represents the main application in this example, which works if you are creating an application. If you are developing an application module, then use your module's name.

AJAX Details¶

JavaScript client proxy functions use the abp.ajax under the hood. So, you have the same benefits like automatic error handling. Also, you can fully control the AJAX call by providing the options.

The Return Value¶

Every function returns a Deferred object. That means you can chain with then to get the result, catch to handle the error, always to perform an action once the operation completes (success or failed).

AJAX Options¶

Every function gets an additional last parameter after your own parameters. The last parameter is called as ajaxParams. It is an object that overrides the AJAX options.

Example: Set type and dataType AJAX options

volo.abp.identity.identityUser
    .delete('7245a066-5457-4941-8aa7-3004778775f0', {
        type: 'POST',
        dataType: 'xml'
    })
    .then(function() {
        abp.notify.info('Successfully deleted!');
    });

See the jQuery.ajax documentation for all the available options.

Service Proxy Script Endpoint¶

The magic is done by the /Abp/ServiceProxyScript endpoint defined by the ABP and automatically added to the layout. You can visit this endpoint in your application to see the client proxy function definitions. This script file is automatically generated by the ABP based on the server side method definitions and the related HTTP endpoint details.