ASP.NET ABP 之動態Web API層

標籤：

建立動態Web API 控制器

    ASP.NET Boilerplate 能夠自動為您的應用程式層產生Web API層。比如說我們有如下的一個應用服務：

1 public interface ITaskAppService : IApplicationService2 {3     GetTasksOutput GetTasks(GetTasksInput input);4     void UpdateTask(UpdateTaskInput input);5     void CreateTask(CreateTaskInput input);6 }

    我們想要這個服務暴露成一個Web API控制器，以方便用戶端調用。ASP.NET Boilerplate能夠自動且動態地為這個應用服務建立Web API 控制器，只需要一行配置代碼即可完成。

DynamicApiControllerBuilder.For<ITaskAppService>("tasksystem/task").Build();

    這幾乎是全部代碼！一個API控制器被建立，其地址是“/api/services/tasksystem/task”，同時所有的方法在用戶端都是可用的。這個配置通常是在模型初始化的時候執行。

    ITaskAppService 是我們想要封裝成API控制器的應用服務，這是沒有嚴格限制的，但是一種通用且推薦的做法。“tasksystem/task”是API控制器的命名空間的名稱，名稱可以是任意的。你可以定義至少一個層級的命名空間，也可以定義更多層級的命名空間，比如： “myCompany/myApplication/myNamespace1/myNamespace2/myServiceName”。“/api/services/”是所有動態Web API控制器的首碼。因此，API控制器的地址就會是： “/api/services/tasksystem/task”，同時 GetTasks方法的地址就是“/api/services/tasksystem/task/getTasks”。其中方法名稱會被自動轉換成camel規則（首字母小寫），這是Javascript代碼的傳統慣例。
    你也可以將應用服務的某些方法從API方法中排除，比如你可以向下面這樣定義：

1 DynamicApiControllerBuilder2 .For<ITaskAppService>("tasksystem/taskService")3 .ForMethod("CreateTask").DontCreateAction()4 .Build();

ForAll 方法

    在一個應用系統中，我們可能有很多個應用服務，那麼一個接一個地建立API將是一件冗長無聊且容易遺忘的工作。
    DynamicApiControllerBuilder提供了一個方法只要一次調用就能為所有應用服務建立Web API控制器：

1 DynamicApiControllerBuilder2 .ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")3 .Build();

    ForAll 是個泛型方法，泛型型別是一個介面. 第一個參數是程式集，裡面有一些實現了給定介面的類。最後一個介面是服務的命名空間首碼。比如說，在程式集裡我們有ITaskAppService 和IPersonAppService 兩個介面。根據配置，服務將會是“/api/services/tasksystem/task” 和“/api/services/tasksystem/person”。為了產生服務名稱，架構會將介面名稱中的Service 和AppService 尾碼以及I首碼自動去除。同時服務名稱也會自動被轉換成符合camel大小寫規則。如果你不喜歡這樣的轉換，可以使用“WithServiceName”方法，這樣你可以自行決定名稱。 這對於為絕大部分應用服務建立API控制器是非常有協助的。

使用動態Javascript代理

    你可以在Javascript的 Ajax方法中使用這些動態建立的Web API。ASP.NET Boilerplate也提供的更簡單的方式：為動態Web API控制器建立了動態Javascript代理。因此，你能夠在Javascript中像調用函數一樣調用一個動態Web API方法：

1 abp.services.tasksystem.task.getTasks({2     state: 13 }).done(function (data) {4     //use data.tasks here...5 });

    Javascript代理都是動態建立，使用前你需要在頁面中包含動態指令碼：

<script src="/api/AbpServiceProxies/GetAll" type="text/javascript"></script>

    服務方法返回承諾（查看 jQuery.Deferred)。你能夠通過註冊實現“完成”，“失敗”以及“回調”等等。服務方法裡麵包含了abp.ajax，它們處理錯誤並在需要時顯示錯誤資訊。

AJAX參數

    你可能想要傳輸自訂的ajax參數到代理方法中。你能夠傳輸第二參數來實現如下：

1 abp.services.tasksystem.task.createTask({2     assignedPersonId: 3,3     description: ‘a new task description...‘4 },{ // 覆蓋jQuery的ajax參數5     async: false,6     timeout: 300007 }).done(function () {8     abp.notify.success(‘successfully created a task!‘);9 });

 

    所有 jQuery.ajax 參數在這裡都是有效。

單獨服務指令碼

    “/api/AbpServiceProxies/GetAll”在一個檔案中產生所有的服務代理。你也可以使用“/api/AbpServiceProxies/Get?name=serviceName”來產生單獨的服務代理，只需要在頁面中包含下面的指令碼代碼：

<script src="/api/AbpServiceProxies/Get?name=tasksystem/task" type="text/javascript"></script>

Angular 支援

    ASP.NET Boilerplate 能夠將動態API控制器暴露成AngularJs服務。如下面的例子：

 1 (function() { 2     angular.module(‘app‘).controller(‘TaskListController‘, [ 3         ‘$scope‘, ‘abp.services.tasksystem.task‘, 4         function($scope, taskService) { 5            var vm = this; 6            vm.tasks = []; 7            taskService.getTasks({ 8            state: 0 9        }).success(function(data) {10        vm.tasks = data.tasks;11      });12     }13    ]);14 })();

    我們能夠用名稱（帶命名空間）注入一個服務。然後我們能夠像調用普通Javascript方法一樣調用它的方法。需要注意，由於這像是在Angular的$http服務中，所以我們註冊了一個success處理常式（代替done）。 ASP.NET Boilerplate 使用了AngularJs的 $http 服務。如果你想要傳遞$http配置，你可以把一個設定物件作為服務方法的最後一個參數傳遞。

    為了能夠使用自動產生的服務，你需要在頁面中包含必須的指令碼：

1 <script src="~/Abp/Framework/scripts/libs/angularjs/abp.ng.js"></script>2 <script src="~/api/AbpServiceProxies/GetAll?type=angular"></script>

Durandal 支援

    ASP.NET Boilerplate支援在Durandal 應用程式中注入服務代理。看一個視圖模型的例子：

1 define([‘service!tasksystem/task‘],2     function (taskService) {3       //taskService 可以在這兒使用4 });

    ASP.NET Boilerplate 通過配置 Durandal (實際上是Require.js ) 來解析“service!”首碼，並且注入適當的Javascript 服務代理。

    本文翻譯自ASP.NET Boilerplate官網，原文地址:  http://www.aspnetboilerplate.com/Pages/Documents/Dynamic-Web-API

ASP.NET ABP 之動態Web API層