ABP框架系列之八：(Introduction-介紹)

Introduction

We are creating different applications based on different needs. But implementing common and similar structures over and over again, at least in some level. Authorization, Validation, Exception Handling, Logging,Localization, Database Connection Management, Setting Management, Audit Logging are some of these common structures. Also, we are building architectural structures and best practices like Layered andModular Architecture, Domain Driven Design, Dependency Injection and so on. And trying to develop applications based on some conventions.

Since all of these are very time-consuming and hard to build seperately for every project, many companies create private frameworks. They're developing new applications faster with less bugs using these frameworks. Surely, not all companies that lucky. Most of them have no time, budget and team to develop such frameworks. Even they have possibility to create a framework, it's hard to document, train developers and maintain it.

ASP.NET Boilerplate (ABP) is an open source and well documented application framework started idea of "developing a common framework for all companies and all developers!" It's not just a framework but also provides a strong architectural model based on Domain Driven Design and best practices in mind.

咱們正在根據不一樣的需求建立不一樣的應用程序。可是，至少在某種程度上一次又一次地執行通用和相似的結構。受權、驗證、異常處理、日誌記錄、本地化、數據庫鏈接管理、設置管理、審計日誌記錄是這些常見結構中的一些結構。同時，咱們正在建設的建築結構和最佳實踐，如分層和模塊化結構，領域驅動設計，依賴注入等。並嘗試基於一些約定開發應用程序。

由於全部這些都是很是耗時和難以創建單獨爲每個項目，許多公司建立私有的框架。他們正在開發新的應用程序，使用這些框架的bug更少。固然，並非全部的公司都那麼幸運。他們大多沒有時間、預算和團隊來開發這樣的框架。即便他們有建立一個框架的可能性，也很難編寫文檔，培訓開發人員並維護它。

ASP.NET Boilerplate（ABP）是一個開放源代碼的，有據可查的應用框架開始發展爲全部公司和開發商共同框架的主意！」它不只僅是一個框架，並且還提供了一個基於領域驅動設計和最佳實踐的強大的架構模型。

A Quick Sample

Let's investigate a simple class to see ABP's benefits:

讓咱們調查一個簡單的類，看看ABP的好處：

public class TaskAppService : ApplicationService, ITaskAppService
{
    private readonly IRepository<Task> _taskRepository;

    public TaskAppService(IRepository<Task> taskRepository)
    {
        _taskRepository = taskRepository;
    }

    [AbpAuthorize(MyPermissions.UpdatingTasks)]
    public async Task UpdateTask(UpdateTaskInput input)
    {
        Logger.Info("Updating a task for input: " + input);

        var task = await _taskRepository.FirstOrDefaultAsync(input.TaskId);
        if (task == null)
        {
            throw new UserFriendlyException(L("CouldNotFoundTheTaskMessage"));
        }

        input.MapTo(task);
    }
}

Here, we see a sample Application Service method. An application service, in DDD, is directly used by presentation layer to perform use cases of the application. We can think that UpdateTask method is called by javascript via AJAX. Let's see ABP's some benefits here:

• Dependency Injection : ABP uses and provides a strong and conventional DI infrastructure. Since this class is an application service, it's conventionally registered to DI container as transient (created per request). It can simply inject all dependencies (as IRepository<Task> in this sample).
• Repository : ABP can create a default repository for each entity (as IRepository<Task> in this example). Default repository has many useful methods as FirstOrDefault used in this example. We can easily extend default repository upon our needs. Repositories abstracts DBMS and ORMs and simplifies data access logic.
• Authorization : ABP can check permissions. It prevents access to UpdateTask method if current user has no "updating task" permission or not logged in. It simplifies authorization using declarative attributes but also has additional ways of authorization.
• Validation : ABP automatically checks if input is null. It also validates all properties of an input based on standard data annotation attributes and custom validation rules. If request is not valid, it throws a proper validation exception.
• Audit Logging : User, browser, IP address, calling service, method, parameters, calling time, execution duration and some other informations are automatically saved for each request based on conventions and configurations.
• Unit Of Work : In ABP, each application service method is assumed as a unit of work as default. It automatically creates a connection and begins a transaction at the beggining of the method. If the method successfully completed without exception, then the transaction is commited and connection is disposed. Even this method uses different repositories or methods, all of them will be atomic (transactional). And all changes on entities are automatically saved when transaction is commited. Thus, we don't even need to call _repository.Update(task) method as shown here.
• Exception Handling : We almost never handle exceptions in ABP in a web application. All exceptions are automatically handled by default. If an exception occurs, ABP automatically logs it and returns a proper result to the client. For example, if this is an AJAX request, the it returns a JSON to client indicates that an error occured. If hides actual exception from client unless the exception is a UserFriendlyException as used in this sample. It also understands and handles errors on client side and show appropriate messages to users.
• Logging : As you see, we can write logs using the Logger object defined in base class. Log4Net is used as default but it's changable or configurable.
• Localization : Notice that we used L method while throwing exception. Thus, it's automatically localized based on current user's culture. Surely, we're defining CouldNotFoundTheTaskMessage in somewhere (seelocalization document for more).
• Auto Mapping : In the last line, we're using ABP's MapTo extension method to map input properties to entity properties. It uses AutoMapper library to perform mapping. Thus, we can easily map properties from one object to another based on naming conventions.
• Dynamic Web API Layer : TaskAppService is a simple class actually (even no need to deliver from ApplicationService). We generally write a wrapper Web API Controller to expose methods to javascript clients. ABP automatically does that on runtime. Thus, we can use application service methods directly from clients.
• Dynamic Javascript AJAX Proxy : ABP creates javascript proxy methods those make calling application service methods just as simple as calling javascript methods on the client.

We can see benefit of ABP in such a simple class. All these tasks normally take significiant time, but all they are automatically handled by ABP.

這裏，咱們看到了一個示例應用程序服務方法。一個應用程序服務，在DDD中，由表示層直接使用來執行應用程序的用例。咱們能夠認爲updatetask方法被JavaScript經過AJAX。讓咱們看看ABP在這裏的一些好處：

依賴注入：ABP使用並提供強大且常規的DI基礎設施。由於這個類是一個應用程序服務，因此它一般註冊爲DI容器做爲臨時（根據請求建立）。它能夠簡單地將全部的依賴性（如IRepository的<<task>>這樣）。
庫：ABP能夠爲每一個實體的默認庫（IRepository <task>這個例子）。默認存儲庫中有許多有用的方法，本例中使用FirstOrDefault。咱們能夠輕鬆地根據須要擴展默認存儲庫。文摘數據庫和ORMs庫簡化了數據訪問邏輯。
受權：ABP能夠檢查權限。它能夠防止訪問updatetask方法若是當前用戶沒有「更新任務」的權限或沒有登陸。它使用聲明屬性簡化了受權，但也有額外的受權方式。
驗證：ABP自動檢查輸入是否爲空。它還基於標準數據註釋屬性和自定義驗證規則驗證輸入的全部屬性。若是請求無效，則拋出正確的驗證異常。
審計日誌：根據約定和配置，爲每一個請求自動保存用戶、瀏覽器、IP地址、調用服務、方法、參數、調用時間、執行時間和其餘信息。
工做單元：在ABP中，每一個應用服務方法都假定爲缺省工做單元。它會自動建立一個鏈接和交易的方法，在開始的開始。若是方法成功地完成了沒有例外，那麼交易的承諾和鏈接設置。即便此方法使用不一樣的存儲庫或方法，它們都是原子（事務）。在實體全部的改變都是自動保存在事務提交。所以，咱們甚至不須要打電話_repository。更新（任務）的方法以下所示。
異常處理：咱們幾乎從不處理Web應用程序中ABP中的異常。默認狀況下，全部異常都會自動處理。若是出現異常，ABP會自動記錄並將正確的結果返回給客戶機。例如，若是這是一個Ajax請求，它將一個JSON返回給客戶機，代表發生了一個錯誤。若是隱藏從客戶實際異常除非例外狀況是userfriendlyexception用於此示例。它還理解並處理客戶機上的錯誤，並向用戶顯示適當的消息。
日誌：如您所見，咱們可使用基類中定義的日誌記錄器對象編寫日誌。log4net做爲默認的但它的可變或可配置。
本地化：注意咱們在拋出異常時使用了L方法。所以，它基於當前用戶的文化自動本地化。固然，咱們在某個地方定義couldnotfoundthetaskmessage（更多seelocalization文件）。
自動映射：在最後一行，咱們使用ABP的信息以可拓方法地圖輸入屬性的實體屬性。它使用AutoMapper庫執行映射。所以，咱們能夠根據命名規則輕鬆地將屬性從一個對象映射到另外一個對象。
動態Web API層：taskappservice其實是一個簡單的類（甚至不須要提供的應用服務）。咱們一般編寫一個包裝Web API控制器來向JavaScript客戶端公開方法。ABP在運行時自動執行。所以，咱們能夠直接從客戶機中使用應用程序服務方法。
動態JavaScript Ajax代理：ABP建立JavaScript代理方法，這些方法使調用應用程序服務方法和調用客戶機上的JavaScript方法同樣簡單。
在這樣一個簡單的類中，咱們能夠看到ABP的好處。全部這些任務一般須要顯著的時間，但他們都是由總部自動處理。

What Else（其餘）

Beside this simple example, ABP provides a strong infrastructure and application model. Here, some other features of ABP:

除了這個簡單的示例以外，ABP提供了強大的基礎設施和應用程序模型。這裏，ABP的一些其餘特性：

• Modularity : Provides a strong infrastructure to build reusable modules.
• Data Filters : Provides automatic data filtering to implement some patterns like soft-delete and multi-tenancy.
• Multi Tenancy: It fully supports multi-tenancy, including single database or database per tenant architectures.
• Setting Management : Provides a strong infrastructure to get/change application, tenant and user level settings.
• Unit & Integration Testing: It's built testability in mind. Also provides base classes to simplify unit & integration tests. See this article for more information.

• 模塊化：爲構建可重用模塊提供強大的基礎設施。
  數據過濾器：提供自動數據過濾來實現像軟刪除和多租戶這樣的模式。
  多租戶：它徹底支持多租戶，包括每一個租戶架構的單個數據庫或數據庫。
  設置管理：提供一個強大的基礎設施來獲取/更改應用程序、租戶和用戶級設置。
  單元和集成測試：它構建了可測試性。還提供基類來簡化單元和集成測試。有關更多信息，請參見本文。

For all features, see documentation.

Startup Templates（啓動模板）

Starting a new solution, creating layers, installing nuget packages, creating a simple layout and a menu... all these are also time consuming stuff.

ABP provides pre-built startup templates that makes starting a new solution is much more easier. Templates support SPA (Single-Page Application) and MPA (Multi-Page MVC Applications) architectures. Also, allows us to use different ORMs.

開始一個新的解決方案，建立層，安裝NuGet包，建立一個簡單的佈局和菜單…全部這些都是耗費時間的東西。

ABP提供預構建的啓動模板，使得啓動一個新的解決方案變得容易得多。模板支持spa（單頁應用程序）和MPA（多頁MVC應用程序）體系結構。同時，咱們能夠用不一樣的形式。

How To Use

ABP is developed on Github and distributed on Nuget . Easiest way of starting with ABP is creating a startup template and following the documentation.

公司開發的在GitHub上，分佈在NuGet。從ABP開始最簡單的方法是建立一個啓動模板並遵循文檔。