diff --git a/docs/en/Startup-Templates/Mvc-Module.md b/docs/en/Startup-Templates/Mvc-Module.md index b641d78bac..d27c2d3d12 100644 --- a/docs/en/Startup-Templates/Mvc-Module.md +++ b/docs/en/Startup-Templates/Mvc-Module.md @@ -1,6 +1,92 @@ # MVC Module Startup Template -TODO +This template can be used to create a **reusable [application module](../Modules/Index.md)** based on the [module development best practices & conventions](../Best-Practices/Index.md). It is also suitable for creating **microservices** (with or without UI). +## How to Start With? +You can use the [ABP CLI](../CLI.md) to create a new project using this startup template. Alternatively, you can directly create & download from the [Get Started](https://abp.io/get-started) page. CLI approach is used here. +First, install the ABP CLI if you haven't installed before: + +```bash +dotnet tool install -g Volo.Abp.Cli +``` + +Then use the `abp new` command in an empty folder to create a new solution: + +```bash +abp new Acme.IssueManagement -t mvc-module +``` + +- `Acme.IssueManagement` is the solution name, like *YourCompany.YourProduct*. You can use single level, two-levels or three-levels naming. + +### Without User Interface + +The template comes with a UI by default. You can use `--no-ui` option to not include the UI layer. + +````bash +abp new Acme.IssueManagement -t mvc-module --no-ui +```` + +## Solution Structure + +Based on the options you've specified, you will get a slightly different solution structure. + +### Default Structure + +If you don't specify any option, you will have a solution like shown below: + +![issuemanagement-module-solution](../images/issuemanagement-module-solution.png) + +Projects are organized as `src`, `test` and `host` folders: + +* `src` folder contains the actual module which is layered based on [DDD](../Domain-Driven-Design.md) principles. +* `test` folder contains unit & integration tests. +* `host` folder contains applications with different configurations to demonstrate how to host the module in an application. These are not a part of the module, but useful on development. + +The diagram below shows the layers & project dependencies of the module: + +![layered-project-dependencies-module](../images/layered-project-dependencies-module.png) + +Each section below will explain the related project & its dependencies. + +#### .Domain.Shared Project + +This project contains constants, enums and other objects these are actually a part of the domain layer, but needed to be used by all layers/projects in the solution. + +An `IssueType` enum and an `IssueConts` class (which may have some constant fields for the `Issue` entity, like `MaxTitleLength`) are good candidates for this project. + +- This project has no dependency to other projects in the solution. All other projects depend on this directly or indirectly. + +#### .Domain Project + +This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../Entities.md), [domain services](../Domain-Services.md), [value types](../Value-Types.md), [repository interfaces](../Repositories.md) and other domain objects. + +An `Issue` entity, an `IssueManager` domain service and an `IIssueRepository` interface are good candidates for this project. + +- Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. + +#### .Application.Contracts Project + +This project mainly contains [application service](../Application-Services.md) **interfaces** and [Data Transfer Objects](../Data-Transfer-Objects.md) (DTO) of the application layer. It does exists to separate interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. + +An `IIssueAppService` interface and an `IssueCreationDto` class are good candidates for this project. + +- Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. + +#### .Application Project + +This project contains the [application service](../Application-Services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. + +An `IssueAppService` class is a good candidate for this project. + +- Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. +- Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. + +#### .EntityFrameworkCore Project + +This is the integration project for the EF Core. It defines the `DbContext` and implements repository interfaces defined in the `.Domain` project. + +- Depends on the `.Domain` project to be able to reference to entities and repository interfaces. + +> You can delete this project if you don't want to support EF Core for your module. \ No newline at end of file diff --git a/docs/en/Startup-Templates/Mvc.md b/docs/en/Startup-Templates/Mvc.md index 6916a630a3..e61fe5c8fb 100644 --- a/docs/en/Startup-Templates/Mvc.md +++ b/docs/en/Startup-Templates/Mvc.md @@ -61,7 +61,9 @@ If you don't specify any option, you will have a solution like shown below: ![bookstore-visual-studio-solution-v3](../images/bookstore-visual-studio-solution-v3.png) -Projects are organized in `src` and `test` folders. `src` folder contains the actual application which is layered based on [DDD](../Domain-Driven-Design.md) principles as mentioned before. The diagram below shows the layers & project dependencies of the solution: +Projects are organized in `src` and `test` folders. `src` folder contains the actual application which is layered based on [DDD](../Domain-Driven-Design.md) principles as mentioned before. + +The diagram below shows the layers & project dependencies of the application: ![layered-project-dependencies](../images/layered-project-dependencies.png) @@ -79,7 +81,7 @@ A `BookType` enum and a `BookConts` class (which may have some constant fields f This is the domain layer of the solution. It mainly contains [entities, aggregate roots](../Entities.md), [domain services](../Domain-Services.md), [value types](../Value-Types.md), [repository interfaces](../Repositories.md) and other domain objects. -A `Book` entity, a `BookManager` domain service and a `IBookRepository` interface are good candidates for this project. +A `Book` entity, a `BookManager` domain service and an `IBookRepository` interface are good candidates for this project. * Depends on the `.Domain.Shared` because it uses constants, enums and other objects defined in that project. @@ -87,12 +89,16 @@ A `Book` entity, a `BookManager` domain service and a `IBookRepository` interfac This project mainly contains [application service](../Application-Services.md) **interfaces** and [Data Transfer Objects](../Data-Transfer-Objects.md) (DTO) of the application layer. It does exists to separate interface & implementation of the application layer. In this way, the interface project can be shared to the clients as a contract package. +An `IBookAppService` interface and a `BookCreationDto` class are good candidates for this project. + * Depends on the `.Domain.Shared` because it may use constants, enums and other shared objects of this project in the application service interfaces and DTOs. #### .Application Project This project contains the [application service](../Application-Services.md) **implementations** of the interfaces defined in the `.Application.Contracts` project. +A `BookAppService` class is a good candidate for this project. + * Depends on the `.Application.Contracts` project to be able to implement the interfaces and use the DTOs. * Depends on the `.Domain` project to be able to use domain objects (entities, repository interfaces... etc.) to perform the application logic. diff --git a/docs/en/images/issuemanagement-module-solution.png b/docs/en/images/issuemanagement-module-solution.png new file mode 100644 index 0000000000..181924dd90 Binary files /dev/null and b/docs/en/images/issuemanagement-module-solution.png differ diff --git a/docs/en/images/layered-project-dependencies-module.png b/docs/en/images/layered-project-dependencies-module.png new file mode 100644 index 0000000000..7592f49878 Binary files /dev/null and b/docs/en/images/layered-project-dependencies-module.png differ