@ -4,7 +4,7 @@ ABP Framework offers an **opinionated architecture** to build enterprise softwar
## Getting Started
* [Quick Start](Tutorials/Todo/Index.md) is a single-part, quick-start tutorial to build a simple application with the ABP Framework. Start with this tutorial if you want to quickly understand how ABP works.
* [Quick Start](Tutorials/Todo/Overall.md) is a single-part, quick-start tutorial to build a simple application with the ABP Framework. Start with this tutorial if you want to quickly understand how ABP works.
* [Getting Started](Getting-Started.md) guide can be used to create and run ABP based solutions with different options and details.
* [Web Application Development Tutorial](Tutorials/Part-1.md) is a complete tutorial to develop a full stack web application with all aspects of a real-life solution.
This template provides a single-layered application for a quick start with ABP Framework.
This template provides a simple solution structure with a single project. This document explains that solution structure in details.
This document explains the **solution structure** and project in detail.
### The Difference Between the Application Startup Templates
### What is the Difference Between the Application Startup Templates?
ABP's [Application Startup Template](Application.md) provides a well-organized and layered solution to create maintainable business applications based on the [Domain Driven Design](../Domain-Driven-Design.md) (DDD) practices. However, some developers find this template a little bit complex (or unnecessary) for simple and short-time applications.
At this point, a single-layer application template has been created for such applications. This template has the same functionality, features and modules on runtime with the [Application Startup Template](Application.md) but the development model is minimal and everything is in a single project (`.csproj`).
ABP's [Application Startup Template](Application.md) provides a well-organized and layered solution to create maintainable business applications based on the [Domain Driven Design](../Domain-Driven-Design.md) (DDD) practices. However, some developers find this template a little bit complex for simple and short-term applications. The single-layer application template has been created to provide a simpler development model for such applications. This template has the same functionality, features and modules on runtime with the [Application Startup Template](Application.md) but the development model is minimal and everything is in a single project (`.csproj`).
## How to Start with It?
You can use the [ABP CLI](../CLI.md) to create a new project using this startup template. Alternatively, you can directly create & download this startup template from the [Get Started](https://abp.io/get-started) page. How to download via CLI is explained in this section.
You can use the [ABP CLI](../CLI.md) to create a new project using this startup template. Alternatively, you can directly create & download this startup template from the [Get Started](https://abp.io/get-started) page. In this section, we will use the ABP CLI.
Firstly, install the ABP CLI if you haven't installed it before:
@ -29,8 +25,8 @@ abp new Acme.BookStore -t app-nolayers
```
* `Acme.BookStore` is the solution name, like *YourCompany.YourProduct*. You can use single-level, two-level or three-level naming.
* In this example, the `-t`option (or `--template` option) specifies the template name.
* In this example, the `-t` (or `--template`) option specifies the template name.
### Specify the UI Framework
This template provides multiple UI frameworks:
@ -38,17 +34,17 @@ This template provides multiple UI frameworks:
* `mvc`: ASP.NET Core MVC UI with Razor Pages (default)
* `blazor-server`: Blazor Server UI
* `angular`: Angular UI
* `none`: Without UI
* `none`: Without UI (for HTTP API development)
> Currently, this template doesn't have Blazor WASM UI, because it requires 3 projects at least (server-side, UI and shared library between these two projects).
> This template doesn't have Blazor WebAssembly UI, because it requires 3 projects at least (server-side, UI and shared library between these two projects). We are recommending to use the layered [application startup template](Application.md) for Blazor WebAssembly projects.
Use the `-u` or `--ui` option to specify the UI framework while creating the solution:
Use the `-u`(or `--ui`) option to specify the UI framework while creating the solution:
```bash
abp new Acme.BookStore -t app-nolayers -u angular
```
* This example specifies the UI type (`-u` option) as `angular`, you can also specify `mvc` or `blazor-server` for UI type.
This example specifies the UI type (the `-u` option) as `angular`. You can also specify `mvc`, `blazor-server` or `none` for the UI type.
### Specify the Database Provider
@ -69,37 +65,42 @@ If you don't specify any additional options while creating an `app-nolayers` tem
It's a single-layer template rather than a layered-architecture solution (like the `Application Startup Template`). It's helpful to create a running application quickly without considering the layered architecture.
In the next sections, we will explain the structure based on this example. Your startup solution can be slightly different based on your preferences.
### Folder Structure
Since this template provides a single-layer solution, we've separated concerns into folders instead of layers and you can see the pre-defined folders as shown below:
Since this template provides a single-project solution, we've separated concerns into folders instead of projects. You can see the pre-defined folders as shown below:
* You can define your `entities`, `application services`, `DTOs`, etc. in this single project (in the related folders).
* For example, you can define your `application services` and `DTOs` under the **Services** folder.
* Define your database mappings (for [EF Core](../Entity-Framework-Core.md) or [MongoDB](../MongoDB.md)) and [repositories](../Repositories.md) in the `Data` folder.
* Define your [entities](../Entities.md) in the `Entities` folder.
* Define your UI localization keys/values in the `Localization` folder.
* Define your UI menu items in the `Menus` folder.
* Define your [object-to-object mapping](../Object-To-Object-Mapping.md) classes in the `ObjectMapping` folder.
* Define your UI pages (Razor Pages) in the `Pages` folder (create `Controllers` and `Views` folder yourself if you prefer the MVC pattern).
* Define your [application services](../Application-Services.md) in the `Services` folder.
### How to Run?
Before running the application, you need to create the database and seed the initial data. To do that, you can run the following command in the directory of your project:
Before running the application, you need to create the database and seed the initial data. To do that, you can run the following command in the directory of your project (in the same folder of the `.csproj` file):
```bash
dotnet run --migrate-database
```
* This command will create the database and seed the initial data for you. Then you can run the application with any IDE that supports .NET or by running the `dotnet run` CLI command in the directory of your project. The default username is `admin` and the password is `1q2w3E*`.
This command will create the database and seed the initial data for you. Then you can run the application with any IDE that supports .NET or by running the `dotnet run` command in the directory of your project. The default username is `admin` and the password is `1q2w3E*`.
> While creating a database & applying migrations seem only necessary for relational databases, this project comes even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application.
> While creating a database & applying migrations seem only necessary for relational databases, you should run this command even if you choose a NoSQL database provider (like MongoDB). In that case, it still seeds the initial data which is necessary for the application.
### Angular UI
### The Angular UI
If you choose `Angular` as the UI framework, the solution will be separated into two folders:
* An `angular` folder that contains the Angular UI application, the client-side code.
* An `aspnet-core` folder that contains the ASP.NET Core solution (a single project), the server-side code.
The server-side is similar to the solution described in the [Solution Structure](#solution-structure) section above. This project serves the API, so the `Angular` application can consume it.
The server-side is similar to the solution described in the *Solution Structure* section above. This project serves the API, so the Angular application can consume it.
The client-side application consumes the HTTP APIs as mentioned. You can see the folder structure of the Angular project shown below:
@ -17,6 +17,7 @@ You can find the source code of the completed application [here](https://github.
## Pre-Requirements
* An IDE (e.g. [Visual Studio](https://visualstudio.microsoft.com/vs/)) that supports [.NET 6.0+](https://dotnet.microsoft.com/download/dotnet) development.
* [Node v14.x](https://nodejs.org/)
{{if DB=="Mongo"}}
@ -24,12 +25,6 @@ You can find the source code of the completed application [here](https://github.
{{end}}
{{if UI=="NG"}}
* [Node v14.x](https://nodejs.org/)
{{end}}
## Creating a New Solution
We will use the [ABP CLI](../../CLI.md) to create new solutions with the ABP Framework. You can run the following command in a command-line terminal to install it:
**Welcome to the ABP Framework**. This is a single-part, quick-start tutorial to build a simple application. Start with this tutorial if you want to quickly understand how ABP Framework works.
## Select the Solution Architecture
This tutorial has multiple versions. Please select the one best fits for you:
* **[Single-Layer Solution](Single-Layer/Index.md)**: Creates a single-project solution. Recommended for building an application with a **simpler and easy to understand** architecture.
* **[Layered Solution Architecture](Index.md)**: A fully layered (multiple projects) solution based on [Domain Driven Design](../../Domain-Driven-Design.md) practices. Recommended for long-term projects that need a **maintainable and extensible** codebase.
## See Also
* Check the [Web Application Development Tutorial](../Part-1.md) to see a real-life web application development in a layered architecture.
@ -17,6 +17,7 @@ You can find the source code of the completed application [here](https://github.
## Pre-Requirements
* An IDE (e.g. [Visual Studio](https://visualstudio.microsoft.com/vs/)) that supports [.NET 6.0+](https://dotnet.microsoft.com/download/dotnet) development.
* [Node v14.x](https://nodejs.org/)
{{if DB=="Mongo"}}
@ -24,15 +25,9 @@ You can find the source code of the completed application [here](https://github.
{{end}}
{{if UI=="NG"}}
* [Node v14.x](https://nodejs.org/)
{{end}}
## Creating a New Solution
In this tutorial, we will use the [ABP CLI](../../CLI.md) to create the sample application with the ABP Framework. You can run the following command in a command-line terminal to install the **ABP CLI**, if you haven't installed it yet:
In this tutorial, we will use the [ABP CLI](../../../CLI.md) to create the sample application with the ABP Framework. You can run the following command in a command-line terminal to install the **ABP CLI**, if you haven't installed it yet:
This will create a new solution with a single project, named *TodoApp* with `angular` and `aspnet-core` folders. Once the solution is ready, open the solution in your favorite IDE.
This will create a new solution, named *TodoApp*, with `angular` and `aspnet-core` folders. Once the solution is ready, open the solution (in the `aspnet-core` folder) with your favorite IDE.
{{else}}
@ -56,7 +51,7 @@ This will create a new solution with a single project, named *TodoApp*. Once the
### Create the Database
You can run the following command in the directory of your project to create the database and seed the initial data:
You can run the following command in the root directory of your project (in the same folder of the `.csproj` file) to create the database and seed the initial data:
```bash
dotnet run --migrate-database
@ -99,9 +94,9 @@ You can click on the *Login* button and use `admin` as the username and `1q2w3E*
All right. We can start coding!
## Defining Entities
## Defining the Entity
This application will have a single [entity](../../../Entities.md) and we can start by creating it. So, create a new `TodoItem` class under the **Entities** folder of the project:
This application will have a single [entity](../../../Entities.md) and we can start by creating it. So, create a new `TodoItem` class under the `Entities` folder of the project:
````csharp
using Volo.Abp.Domain.Entities;
@ -124,7 +119,7 @@ Next step is to setup the [Entity Framework Core](../../../Entity-Framework-Core
### Mapping Configuration
Open the `TodoAppDbContext` class (under the **Data** folder) and add a new `DbSet` property to this class:
Open the `TodoAppDbContext` class (in the `Data` folder) and add a new `DbSet` property to this class:
````csharp
public DbSet<TodoItem> TodoItems { get; set; }
@ -156,13 +151,13 @@ We've mapped the `TodoItem` entity to the `TodoItems` table in the database. The
The startup solution is configured to use Entity Framework Core [Code First Migrations](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations). Since we've changed the database mapping configuration, we should create a new migration and apply changes to the database.
Open a command-line terminal in the directory of your project and type the following command:
Open a command-line terminal in the root directory of your project and type the following command:
````bash
dotnet ef migrations add Added_TodoItem
````
This will add a new migration class to the project. You should see the new migration in the **Migrations** folder.
This will add a new migration class to the project. You should see the new migration in the `Migrations` folder:
@ -197,17 +192,17 @@ After the database integrations, now we can start to create application service
## Creating the Application Service
An [Application Service](../../Application-Services.md) is used to perform the use cases of the application. We need to perform the following use cases in this application:
An [application service](../../../Application-Services.md) is used to perform the use cases of the application. We need to perform the following use cases in this application:
* Get the list of the todo items
* Create a new todo item
* Delete an existing todo item
Before starting to implement these use cases, first we need to create DTOs.
Before starting to implement these use cases, first we need to create a DTO class that will be used in the application service.
### Creating the Data Transfer Object (DTO)
`ApplicationService` typically gets and returns DTOs ([Data Transfer Objects](../../../Data-Transfer-Objects.md)) instead of entities. So, create a new `TodoItemDto` class under the **Dtos** folder (under the **Services** folder):
[Application services](../../../Application-Services.md) typically get and return DTOs ([Data Transfer Objects](../../../Data-Transfer-Objects.md)) instead of entities. So, create a new `TodoItemDto` class under the `Services/Dtos` folder:
```csharp
namespace TodoApp.Services.Dtos;
@ -219,11 +214,11 @@ public class TodoItemDto
}
```
* This is a very simple DTO class that has the same properties as the `TodoItem` entity. Now, we are ready to implement our use-cases.
This is a very simple DTO class that has the same properties as the `TodoItem` entity. Now, we are ready to implement our use-cases.
### Application Service Implementation
### The Application Service Implementation
Create a `TodoAppService` class under the **Services** folder of your project, as shown below:
Create a `TodoAppService` class under the `Services` folder of your project, as shown below:
```csharp
using TodoApp.Entities;
@ -245,11 +240,11 @@ public class TodoAppService : ApplicationService
}
```
This class inherits from the `ApplicationService` class of the ABP Framework and implements our use-cases. ABP provides default generic [repositories](../../../Repositories.md) for the entities. We can use them to perform the fundamental database operations. This class [injects](../../../Dependency-Injection.md) `IRepository<TodoItem, Guid>`, which is the default repository for the `TodoItem` entity. We will use it to implement the use cases (`GetListAsync`, `CreateAsync` and `DeleteAsync`) described before.
This class inherits from the `ApplicationService` class of the ABP Framework and implements our use-cases. ABP provides default generic [repositories](../../../Repositories.md) for the entities. We can use them to perform the fundamental database operations. This class [injects](../../../Dependency-Injection.md) `IRepository<TodoItem, Guid>`, which is the default repository for the `TodoItem` entity. We will use it to implement our use cases.
#### Getting the Todo Items
Let's start by implementing the `GetListAsync` method:
Let's start by implementing the `GetListAsync` method, which is used to get a list of todo items:
````csharp
public async Task<List<TodoItemDto>> GetListAsync()
@ -264,7 +259,7 @@ public async Task<List<TodoItemDto>> GetListAsync()
}
````
We are simply getting the `TodoItem` list from the database, mapping them to the `TodoItemDto` objects and returning as the result.
We are simply getting the `TodoItem` list from the repository, mapping them to the `TodoItemDto` objects and returning as the result.
#### Creating a New Todo Item
@ -387,7 +382,7 @@ Open the `Index.cshtml` file in the `Pages` folder and replace it with the follo
</div>
```
We are using ABP's [card tag helper](../../UI/AspNetCore/Tag-Helpers/Cards.md) to create a simple card view. You could directly use the standard bootstrap HTML structure, however the ABP [tag helpers](../../UI/AspNetCore/Tag-Helpers/Index.md) make it much easier and type safe.
We are using ABP's [card tag helper](../../../UI/AspNetCore/Tag-Helpers/Cards.md) to create a simple card view. You could directly use the standard bootstrap HTML structure, however the ABP [tag helpers](../../../UI/AspNetCore/Tag-Helpers/Index.md) make it much easier and type safe.
This page imports a CSS and a JavaScript file, so we should also create them.
@ -428,7 +423,7 @@ In the first part, we subscribed to the click events of the trash icons near the
In the second part, we created a new todo item on the server. If it succeeded, we would then manipulate the DOM to insert a new `<li>` element to the todo list. This way, we wouldn't need to refresh the whole page after creating a new todo item.
The interesting part here is how we communicate with the server. See the [*Dynamic JavaScript Proxies & Auto API Controllers*](#dynamic-javascript-proxies--auto-api-controllers) section to understand how it works. But now, let's continue and complete the application.
The interesting part here is how we communicate with the server. See the *Dynamic JavaScript Proxies & Auto API Controllers* section to understand how it works. But now, let's continue and complete the application.
### Index.cshtml.css
@ -469,7 +464,7 @@ Now, you can run the application again and see the result.
In the `Index.cshtml.js` file, we've used the `todoApp.services.todo.delete(...)` and `todoApp.services.todo.create(...)` functions to communicate with the server. These functions are dynamically created by the ABP Framework, thanks to the [Dynamic JavaScript Client Proxy](../../../UI/AspNetCore/Dynamic-JavaScript-Proxies.md) system. They perform HTTP API calls to the server and return a promise, so you can register a callback to the `then` function as we've done above.
> **services** keyword comes from the namespace (`namespace TodoApp.Services;`). It's a naming convention.
> `services` keyword comes from the namespace (`namespace TodoApp.Services;`). It's a naming convention.
However, you may notice that we haven't created any API Controllers, so how does the server handle these requests? This question brings us to the [Auto API Controller](../../../API/Auto-API-Controllers.md) feature of the ABP Framework. It automatically converts the application services to **API Controllers** by convention.
@ -757,4 +752,4 @@ You can find the source code of the completed application [here](https://github.
## See Also
* Check the [Web Application Development Tutorial](../Part-1.md) to see a real-life web application development in a layered architecture using the [Application Startup Template](../../../Startup-Templates/Application.md).
* Check the [Web Application Development Tutorial](../../Part-1.md) to see a real-life web application development in a layered architecture using the [Application Startup Template](../../../Startup-Templates/Application.md).
Halil İbrahim Kalkan
4 years ago