动态Web APID层

创建动态Web API控制器

  这个文档是针对ASP.NET Web API的。如果你对ASP.NET Core感兴趣,请参见ASP.NET Core文档。

  ABP可以为应用层自动生成ASP.NET Web API层。也就是说,如果我们有一个应用服务,如下所示:

public interface ITaskAppService : IApplicationService
{
GetTasksOutput GetTasks(GetTasksInput input);
void UpdateTask(UpdateTaskInput input);
void CreateTask(CreateTaskInput input);
}

  我们想将这个服务作为一个Web API Controller提供给客户端。ABP可以使用一行配置自动动态的为这个应用服务创建一个Web API Controller:

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

  就这样!一个地址为'/api/services/tasksystem/task'的api controller就创建了,并且所有的方法在客户端都是可用的。这个配置需要在模块的Initialize方法中使用。

  ITaskAppService是我们想要包装成api controller的应用服务。并不限制为应用服务,但是这是我们约定和推荐的方式。

  'tasksystem/task'是api controller的名字,名字随意。你应该至少定义一级命名空间,但是你可以定义更深的命名空间如“myCompany/myApplication/myNamespace1/myNamespace2/myServiceName”。'/api/services/'是所有动态web api controller的前缀。所以,api controller的地址将为'/api/services/tasksystem/task',GetTasks方法地址为'/api/services/tasksystem/task/getTasks'。方法名称转换为camelCase,因为这是在javascript世界的约定。

ForAll方法

  在应用中,我们会有许多的应用服务,一个一个的创建api controllers是乏味且易忘记的。DynamicApiControllerBuilper提供了一个方法只需调用一次就能为所有应用服务创建web api controllers。示例:

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
.Build();

  ForAll方法是泛型方法,接收一个接口。第一个参数是包含继承指定接口类的程序集。第二个参数是服务的命名前缀。也就是说在程序集中我们有ITaskAppService和IPersonAppService接口。对于这个配置,服务地址将为'/api/services/tasksystem/task'和'/api/services/tasksystem/person'。计算服务名称:Service和AppService后缀,I前缀移除(对于接口)。服务名称也会转换为camel方式。如果你不喜欢这种约定,使用'WithServiceName'方法可以改变名称。还有一个Where方法用来过滤服务,当你想为除了一部分服务之外的其他所有服务创建时会非常有用。

重写ForAll

  在ForAll方法之后我们可以重写配置。示例:

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
.Build(); Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.For<ITaskAppService>("tasksystem/task")
.ForMethod("CreateTask").DontCreateAction().Build();

  在这段代码中,我们动态为程序集中所有的应用服务创建web api controller。然后为一个单独的应用服务(ITaskAppService)重写配置忽略CreateTask方法。

ForMethods

  当使用ForAll方法时,我们可以使用ForMethods方法更好的调整每一个方法。示例:

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.ForAll<IApplicationService>(Assembly.GetExecutingAssembly(), "app")
.ForMethods(builder =>
{
if (builder.Method.IsDefined(typeof(MyIgnoreApiAttribute)))
{
builder.DontCreate = true;
}
})
.Build();

  在这个示例中,使用了一个自定义特性(MyIgnoreApiAttribute)来检查所有的方法,标记了此特性的方法将不会动态创建web api controller action。

Http动词

  默认,所有的方法以POST的形式创建。所以,为了使用创建的web api actions,客户端应该发送post请求。我们可以使用不同的方式改变这种行为:

WithVerb方法

  我们可以为方法使用WithVerb,如下:

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.For<ITaskAppService>("tasksystem/task")
.ForMethod("GetTasks").WithVerb(HttpVerb.Get)
.Build();

HTTP特性

  我们可以在服务接口方法上添加HttpGet、HttepPost...等特性:

public interface ITaskAppService : IApplicationService
{
[HttpGet]
GetTasksOutput GetTasks(GetTasksInput input); [HttpPut]
void UpdateTask(UpdateTaskInput input); [HttpPost]
void CreateTask(CreateTaskInput input);
}

  为了使用这些特性,我们应该在工程中添加Microsoft.AspNet.WebApi.Core nuget包引用。

命名约定

  你可以使用WithConventionalVerbs方法取代为每一个方法声明HTTP动词,如下所示:

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
.ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
.WithConventionalVerbs()
.Build();

  在这种情况下,HTTP动词由方法名前缀决定:

  • Get:如果方法名以'Get'开头时使用。
  • Put:如果方法名以'Put'或'Update'时使用。
  • Delete:如果方法名称以'Delete'或'Remove'开头时使用。
  • Post:如果方法名以'Post','Create'或'Insert'开头时使用。
  • Patch:如果方法名以'Patch'开头时使用。
  • 否则,POST为默认的HTTP动词。

  我们可以为一个特定方法重写它,如之前所描述的那样。  

API管理器

  所有的动态web api controllers默认对API管理器是可见的(例如他们都在Swagger中可用)。你可以使用DynamicApiControllerBuilder API或RemoteService特性来控制。

RemoteService特性

  你可以为任何接口方法定义使用RemoteService特性来enable/disable(IsEnabled)动态API或API管理器设置(IsMetadataEnabled)。

动态Javascript代理

  你可以在javascript通过ajax使用动态创建的web api controller。ABP通过为动态web api controllers创建javascript代理来简化了这个操作。所以,你可以在javascript中像一个function一样调用动态web api controller的action。如下所示:

abp.services.tasksystem.task.getTasks({
state:
}).done(function (result) {
//use result.tasks here...
});

  Javascript代理是动态创建的。你应该在页面中包含动态script在使用它之前:

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

  服务方法返回promise(参见jQuery.Deferred)。你可以注册done,fail,then...回调。服务方法内部使用abp.ajax。如果需要,他们处理错误并显示错误信息。

AJAX参数

  你可能会想传递自定义ajax参数给代理方法。可以作为第二个参数传递,如下所示:

abp.services.tasksystem.task.createTask({
assignedPersonId: ,
description: 'a new task description...'
},{ //override jQuery's ajax parameters
async: false,
timeout:
}).done(function () {
abp.notify.success('successfully created a task!');
});

  这里,jQuery.ajax所有的参数都是有效的。

单一服务脚本

  '/api/AbpServiceProxies/GetAll'在一个文件里生成所有服务代理。你可以使用'/api/AbpServiceProxies/Get?name=serviceName'并包含在page中生成一个单独的服务代理,如下所示:

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

Anaular集成

  ABP可以以angularjs services的方式暴露动态api controllers。考虑下面的示例:

(function() {
angular.module('app').controller('TaskListController', [
'$scope', 'abp.services.tasksystem.task',
function($scope, taskService) {
var vm = this;
vm.tasks = [];
taskService.getTasks({
state:
}).success(function(result) {
vm.tasks = result.tasks;
});
}
]);
})();

  我们可以使用服务的名称(和命名空间)注入它。然后,我们可以作为常见的javascript函数调用它的函数。注意,我们注册了success处理方法(而不是done),因为在augular$http服务中也是如此定义的。ABP使用AngularJs的$http服务。如果你想传递$http配置,你可以传递一个配置对象作为服务方法的最后一个参数。

  为了使用自动生成的服务,你应该在page中包含需要的scripts:

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

启用/禁用

  如果你使用如上定义的ForAll方法,你可以为服务或方法使用RemoteService特性来禁用它。在服务接口中使用,而不是在服务类中。

包装结果

  ABP使用AjaxResponse对象包装动态web API actions的返回值。参见ajax documentation了解包装的更多信息。你可以enalbe/disable包装每个方法或每个应用服务。参见应用服务的示例:

public interface ITestAppService : IApplicationService
{
[DontWrapResult]
DoItOutput DoIt(DoItInput input);
}

  我们禁用为DoIt方法包装。这个特性应该在接口中声明,不要在实现类中。

  如果你想更加精确的控制返回结果给客户端时,取消包装会很有用。尤其是,当使用第三方客户端类且它不能处理ABP标注AjaxResponse时会需要。在这种情况下,你应该自己处理异常,因为异常处理将会被禁用(DontWrapResult特性有WrapOnError属性,可以用来启用处理和包装异常)。

  注意:不论何种情况下,动态javascript代理可以知道结果是否被包装和正确运行。

关于参数绑定

  ABP在运行时创建Apic Controllers。所以,ABP Web API的model and parameter binding用来绑定模型和参数。你可以阅读它的文档了解更多信息。

FormUrl和FormBody特性

  FromUriFromBody特性可以用在应用服务接口来更高级的控制绑定。

DTOs对比原始类型

  我们强烈建议使用DTOs作为应用服务和web api controllers方法的参数。但是,你可以使用基元类型(如string,int,bool...or nullable 类型如int?,bool?...)作为服务参数。可以使用多个参数,但是只有一个参数允许为复杂类型(因为ASP.NET Web API 的限制)。

返回主目录

ABP官方文档翻译 5.2 动态We API层的更多相关文章

  1. 动态We API(ABP官方文档翻译)

    动态Web API层 创建动态Web API控制器 ForAll方法 重写ForAll ForMethods Http动词 WithVerb方法 HTTP特性 命名约定 API管理器 RemoteSe ...

  2. ABP框架 - 动态Web Api层

    文档目录 本节内容: 创建动态Web Api控制器 ForAll 方法 重写 ForAll ForMethods Http 动词 WithVerb 方法 HTTP 特性 命名约定 Api 浏览器 Re ...

  3. ABP官方文档翻译 0.0 ABP官方文档翻译目录

    一直想学习ABP,但囿于工作比较忙,没有合适的契机,当然最重要的还是自己懒.不知不觉从毕业到参加工作七年了,没留下点儿什么,总感觉很遗憾,所以今天终于卯足劲鼓起勇气开始写博客.有些事能做的很好,但要跟 ...

  4. 动态Web API层

    返回总目录 本篇目录 构建动态Web API控制器 ForAll 方法 重写ForAll 方法 Http动词 动态Javascript代理 Ajax参数 单一服务脚本 Angular支持 Durand ...

  5. DDD开发框架ABP之动态Web API层

    建立动态Web API 控制器 ASP.NET Boilerplate 能够自动为您的应用层产生Web API层.比如说我们有如下的一个应用服务: public interface ITaskAppS ...

  6. ABP官方文档翻译 6.2.1 ASP.NET Core集成

    ASP.NET Core 介绍 迁移到ASP.NET Core? 启动模板 配置 启动类 模块配置 控制器 应用服务作为控制器 过滤器 授权过滤器 审计Action过滤器 校验过滤器 工作单元Acti ...

  7. ABP官方文档翻译 5.4 SwaggerUI集成

    SwaggerUI集成 介绍 ASP.NET Core 安装Nuget包 配置 测试 ASP.NET 5.x 安装Nuget包 配置 测试 介绍 在它的网站上:“...使用Swagger可用的API, ...

  8. ABP官方文档翻译 3.6 工作单元

    工作单元 介绍 ABP中的连接和事务管理 传统的工作单元方法 控制工作单元 UnitOfWork特性 IUnitOfWorkManager 工作单元详情 禁用工作单元 无事务工作单元 一个工作单元方法 ...

  9. ABP官方文档翻译 6.7 CSRF/XSRF保护

    CSRF/XSRF保护 介绍 HTTP动词 非浏览器客户端 ASP.NET MVC 特征 集成 布局视图 配置 ASP.NET Web API 特征 集成 集成到ASP.NET MVC客户端 集成到其 ...

随机推荐

  1. 排序算法的实现(C/C++实现)

    存档: #include <iostream> #include <stdlib.h> #include <sort.h> #define maxsize 20 u ...

  2. bzoj:2423: [HAOI2010]最长公共子序列

    Description 字符序列的子序列是指从给定字符序列中随意地(不一定连续)去掉若干个字符(可能一个也不去掉)后所形成的字符序列.令给定的字符序列X=“x0,x1,…,xm-1”,序列Y=“y0, ...

  3. [国嵌攻略][119][Linux中断处理程序设计]

    裸机中断: 1.中断统一入口. 2.注册中断处理程序. 3.根据中断源编号,调用中断处理程序. Linux中断 1.在entry-armv.S中的_irq_svc是中断统一入口. 2.获取产生中断源的 ...

  4. 设置Sql server用户对表、视图、存储过程、架构的增删改查权限

    根据数据库Schema限制用户对数据库的操作行为 授予Shema dbo下对象的定义权限给某个用户(也就是说该用户可以修改架构dbo下所有表/视图/存储过程/函数的结构) use [Your DB N ...

  5. Lucene学习笔记1(V7.1)

    Lucene是一个搜索类库,solr.nutch和elasticsearch都是基于Lucene.个人感觉学习高级搜索引擎应用程序之前 有必要了解Lucene. 开发环境:idea maven spr ...

  6. WebClient.DownLoadString报错:连接被意外关闭

    调用WebClient的DownLoadString方法调用接口,当数据量比较小的时候(十几条数据)一切正常.后来对方突然放了一千多条数据,然后就报错了:连接被意外关闭. 先是以为是对方接口没有在输出 ...

  7. 字符串API

    string可以看成是多个字符组成的只读数组,也可以通过下标去访问某个字符 访问i位置的字符 :  str[i] 字符个数:  str.length 倒数第n个字符 : str[str.length- ...

  8. NSUserDefaults standardUserDefaults使用注意事项

    NSUserDefaults可以存储NSString,NSNumber, NSDate, NSArray, NSDictionary,自定义类可以通过NSData的方式进行存储,当然要实现NSCodi ...

  9. HTML <td> 标签的 rowspan 属性

    rowspan 属性规定单元格可横跨的行数. colspan  属性规定单元格可横跨的列数.

  10. 【jsp】MyEclipse10.7.1最新版+破解下载

    MyEclipse企业级工作平台[1](MyEclipse Enterprise Workbench ,简称MyEclipse)是对EclipseIDE的扩展,利用它我们可以在数据库和JavaEE的开 ...