Monolith Modular Application Development Tutorial

docs/en/docs-nav.json

@@ -50,7 +50,7 @@
           "path": "tutorials"
         },
         {
-          "text": "TODO application",
+          "text": "TODO Application",
           "items": [
             {
               "text": "Overview",
@@ -67,7 +67,7 @@
           ]
         },
         {
-          "text": "Book Store application",
+          "text": "Book Store Application",
           "items": [
             {
               "text": "Overview",
@@ -115,6 +115,39 @@
             }
           ]
         },
+        {
+          "text": "Modular Monolith Application",
+          "items": [
+            {
+              "text": "Overview",
+              "path": "tutorials/modular-crm/index.md"
+            },
+            {
+              "text": "1: Creating the initial solution",
+              "path": "tutorials/modular-crm/part-01.md"
+            },
+            {
+              "text": "2: Creating the initial Products module",
+              "path": "tutorials/modular-crm/part-02.md"
+            },
+            {
+              "text": "3: Building the Products module",
+              "path": "tutorials/modular-crm/part-03.md"
+            },
+            {
+              "text": "4: Creating the initial Ordering module",
+              "path": "tutorials/modular-crm/part-04.md"
+            },
+            {
+              "text": "5: Building the Ordering module",
+              "path": "tutorials/modular-crm/part-05.md"
+            },
+            {
+              "text": "6: Integrating the modules",
+              "path": "tutorials/modular-crm/part-06.md"
+            }
+          ]
+        },
         {
           "text": "Community Articles",
           "path": "https://abp.io/community"

docs/en/framework/architecture/best-practices/index.md

@@ -1,7 +1,5 @@
 # Module Development Best Practices & Conventions
 
-### Introduction
-
 This document describes the **best practices** and **conventions** for those who want to develop **modules** that satisfy the following specifications:
 
 * Develop modules that conform to the **Domain Driven Design** patterns & best practices.
@@ -10,7 +8,7 @@ This document describes the **best practices** and **conventions** for those who
 
 Also, this guide is mostly usable for general **application development**.
 
-### Guides
+## The Guides
 
 * Overall
   * [Module Architecture](./module-architecture.md)

docs/en/tutorials/index.md

@@ -3,4 +3,5 @@
 The following guides explains how to build ABP based applications:
 
 * [TODO Application](todo/index.md): This is a single-part, quick-start tutorial to build a simple application with ABP. Start with this tutorial if you want to quickly understand how ABP works.
-* [Book Store Application](book-store/overview.md): This is a multi-part, complete tutorial to build a bookstore application with ABP. Start with this tutorial if you want to create a layered solution with ABP and apply DDD best practices.
+* [Book Store Application](book-store/index.md): This is a multi-part, complete tutorial to build a bookstore application with ABP. Start with this tutorial if you want to create a layered solution with ABP and apply DDD best practices.
+* [Modular Monolith Application](modular-crm/index.md): This is a multi-part tutorial that demonstrates how to create application modules, compose and communicate them to build a monolith modular web application.

docs/en/tutorials/modular-crm/index.md

@@ -0,0 +1,34 @@
+# Modular Monolith Application Development Tutorial
+
+````json
+//[doc-nav]
+{
+  "Next": {
+    "Name": "Creating the initial solution",
+    "Path": "tutorials/modular-crm/part-01"
+  }
+}
+````
+
+ABP provides a great infrastructure and tooling to build modular software solutions. In this tutorial, you will learn how to create application modules, compose and communicate them to build a monolith modular web application.
+
+> **This tutorial focuses on modularity.** The example application's functionality and user interface are intentionally kept simple. If you want to learn real world, full featured application logic development with ABP, please follow the [Book Store tutorial](../book-store/index.md).
+
+## Tutorial Outline
+
+This tutorial is organized as the following parts:
+
+* [Part 01: Creating the initial solution](part-01.md)
+* [Part 02: Creating the initial Products module](part-02.md)
+* [Part 03: Building the Products module](part-03.md)
+* [Part 04: Creating the initial Ordering module](part-04.md)
+* [Part 05: Building the Ordering module](part-05.md)
+* [Part 06: Integrating the modules](part-06.md)
+
+## Download the Source Code
+
+You can download the completed sample solution [here](https://github.com/abpframework/abp-samples/tree/master/ModularCRM).
+
+## See Also
+
+* [Book Store: Web Application Development Tutorial](../book-store/index.md)

docs/en/tutorials/modular-crm/part-01.md

@@ -0,0 +1,37 @@
+# Creating the Initial Solution
+
+````json
+//[doc-nav]
+{
+  "Next": {
+    "Name": "Creating the initial Products module",
+    "Path": "tutorials/modular-crm/part-02"
+  }
+}
+````
+
+Follow the [Get Stared](../../get-started/layered-web-application.md) guide to create a new layered web application with the following configuration:
+
+* **Solution name**: `ModularCrm`
+* **UI Framework**: ASP.NET Core MVC / Razor Pages
+* **Database Provider**: Entity Framework Core
+
+You can select the other options based on your preference.
+
+> **Please complete the [Get Stared](../../get-started/layered-web-application.md) guide and run the web application before going further.**
+
+The initial solution structure should be like the following in ABP Studio's *Solution Explorer*:
+
+![solution-explorer-modular-crm-initial](images/solution-explorer-modular-crm-initial.png)
+
+Initially, you see a `ModularCrm` solution and a `ModularCrm` module under that solution.
+
+> An ABP Studio module is typically a .NET solution and an ABP Studio solution is an umbrella concept for multiple .NET Solutions (see the [concepts](../../studio/concepts.md) document for more).
+
+`ModularCrm` module is your main application, which is a layered .NET solution that consists of several packages (.NET projects). You can expand the `ModularCrm` module to see its packages:
+
+![solution-explorer-modular-crm-expanded](images/solution-explorer-modular-crm-expanded.png)
+
+## Summary
+
+We've created the initial layered monolith solution. In the next part, we will learn how to create a new application module and install it to the main application.

docs/en/tutorials/modular-crm/part-02.md

@@ -0,0 +1,138 @@
+# Creating the Initial Products Module
+
+````json
+//[doc-nav]
+{
+  "Previous": {
+    "Name": "Creating the initial solution",
+    "Path": "tutorials/modular-crm/part-01"
+  },
+  "Next": {
+    "Name": "Building the Products module",
+    "Path": "tutorials/modular-crm/part-03"
+  }
+}
+````
+
+In this part, you will build a new module for product management and install it to the main CRM application.
+
+## Creating Solution Folders
+
+You can create solution folders and sub-folders in *Solution Explorer* to better organize your solution components. Right-click to the solution root on the *Solution Explorer* panel, and select *Add* -> *New Folder* command:
+
+![abp-studio-add-new-folder-command](images/abp-studio-add-new-folder-command.png)
+
+That command opens a dialog where you can set the folder name:
+
+![abp-studio-new-folder-dialog](images/abp-studio-new-folder-dialog.png)
+
+Create `main` and `modules` folder using the *New Folder* command, then move the `ModularCrm` module into the `main` folder (simply by drag & drop). The *Solution Explorer* panel should look like the following figure now:
+
+![abp-studio-solution-explorer-with-folders](images/abp-studio-solution-explorer-with-folders.png)
+
+## Creating The Module
+
+There are two module templates provided by ABP Studio:
+
+* **Empty Module**: You can use that module template to build your module structure from scratch.
+* **DDD Module**: A Domain-Driven Design based layered module structure.
+
+We will use the *DDD Module* template for the Product module. We will use the *Empty Module* template later in this tutorial.
+
+Right-click the `modules` folder on the *Solution Explorer* panel, and select the *Add* -> *New Module* -> *DDD Module* command:
+
+![abp-studio-add-new-dd-module](images/abp-studio-add-new-dd-module.png)
+
+This command opens a new dialog to define properties of the new module. You can use the following values to create a new module named `ModularCrm.Products`:
+
+![abp-studio-create-new-module-dialog](images/abp-studio-create-new-module-dialog.png)
+
+When you click the *Next* button, you are redirected to the UI selection step.
+
+### Selecting the UI Type
+
+Here, you can select the UI type you want to support in your module:
+
+![abp-studio-create-new-module-dialog-step-ui](images/abp-studio-create-new-module-dialog-step-ui.png)
+
+A module;
+
+* May not contain a UI and leaves the UI development to the final application.
+* May contain a single UI implementation that is typically in the same technology with the main application.
+* May contain more than one UI implementation if you want to create a reusable application module and you want to make that module usable by different applications with different UI technologies. For example, all of [pre-built ABP modules](https://abp.io/modules) support multiple UI options.
+
+In this tutorial, we are selecting the MVC UI since we are building that module only for our `ModularCrm` solution and we are using the MVC UI in our application. So, select the MVC UI and click the *Next* button.
+
+### Selecting the Database Provider
+
+The next step is to select the database provider (or providers) you want to support with your module:
+
+![abp-studio-create-new-module-dialog-step-db](images/abp-studio-create-new-module-dialog-step-db.png)
+
+Since our main application is using Entity Framework Core and we will use the `ModularCrm.Products` module only for that main application, we can select the *Entity Framework Core* option and click the *Create* button.
+
+### Exploring the New Module
+
+After adding the new module, the *Solution Explorer* panel should look like the following figure:
+
+![abp-studio-solution-explorer-two-modules](images/abp-studio-solution-explorer-two-modules.png)
+
+The new `ModularCrm.Products` module has been created and added to the solution. The `ModularCrm.Products` module has a separate and independent .NET solution. Right-click the `ModularCrm.Products` module and select the *Open with* -> *Explorer* command:
+
+![abp-studio-open-in-explorer](images/abp-studio-open-in-explorer.png)
+
+This command opens the solution folder in your file system:
+
+![product-module-folder](images/product-module-folder.png)
+
+You can open `ModularCrm.Products.sln` in your favorite IDE (e.g. Visual Studio):
+
+![product-module-visual-studio](images/product-module-visual-studio.png)
+
+As seen in the preceding figure, the `ModularCrm.Products` solution consists of several layers, each has own responsibility.
+
+### Installing the Product Module to the Main Application
+
+A module does not contain an executable application inside. The `Modular.Products.Web` project is just a class library project, not an executable web application. A module should be installed to an executable application in order to run it.
+
+> **Ensure that the web application is not running in [Solution Runner](../../studio/running-applications.md) or in your IDE. Installing a module to a running application will produce errors.**
+
+The product module has no relation to the main application yet. Right-click to the `ModularCrm` module (inside the `main` folder) and select the *Import Module* command:
+
+![abp-studio-import-module](images/abp-studio-import-module.png)
+
+The *Import Module* command opens a dialog as shown below:
+
+![abp-studio-import-module-dialog](images/abp-studio-import-module-dialog.png)
+
+Select the `ModularCrm.Products` module and check the *Install this module* option. If you don't check that option, it only imports the module but doesn't setup project dependencies. Importing a module without installation can be used to manually setup your project dependencies. Here, we want to make it automatically, so checking the *Install this module* option.
+
+When you click the *OK* button, ABP Studio opens the *Install Module* dialog:
+
+![abp-studio-module-installation-dialog](images/abp-studio-module-installation-dialog.png)
+
+This dialog simplifies installing a multi-layer module to a multi-layer application. It automatically determines which package of the `ModularCrm.Products` module should be installed to which package of the main application. For example, the `ModularCrm.Products.Domain` package is installed to the `ModularCrm.Domain` package. In that way, you can use domain objects ([entities](../../framework/architecture/domain-driven-design/entities.md), [repositories](../../framework/architecture/domain-driven-design/repositories.md), ...) of the products module from the domain layer of your main application.
+
+The default package match is good for this tutorial, so you can click the *OK* button to proceed.
+
+### Building the Main Application
+
+After the installation, build the entire solution by right-clicking to the `ModularCrm` module (under the `main` folder) and select the *Dotnet CLI* -> *Graph Build* command:
+
+![abp-studio-graph-build](images/abp-studio-graph-build.png)
+
+Graph Build is a dotnet CLI command that recursively build all the referenced dotnet projects even if they are not a part of the root solution.
+
+> While developing multi-module solutions with ABP Studio, you may need to perform *Graph Build* on the root/main module if you made changes in the depending modules.
+
+### Run the Main Application
+
+Open the *Solution Runner* panel, click the *Play* button (near to the solution root), right-click the `ModularCrm.Web` application and select the *Browse* command. It will open the web application in the built-in browser. Then you can navigate to the *Products* page on the main menu of the application to see the Products page that is coming from the `ModularCrm.Products` module:
+
+![abp-studio-solution-runner-initial-product-page](images/abp-studio-solution-runner-initial-product-page.png)
+
+## Summary
+
+In this part, we've created a new module to manage products in our modular application. Then we installed the new module to the main application and run the solution to test if it has successfully installed.
+
+In the next part, you will learn how to create entities, services and a basic user interface for the products module.