#2909 Added initial EF Core Migrations document

docs/en/Entity-Framework-Core-Migrations.md

@@ -0,0 +1,123 @@
+# EF Core Code First Migrations
+
+Entity Framework Core provides an easy to use and powerful [database migration system](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/). ABP Framework [startup templates](Startup-Templates/Index.md) takes the advantage of this system to allows you to develop your application in a standard way.
+
+> See [its own documentation](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/) to understand the EF Core Code First Migrations and why you need to such a system.
+
+However, EF Core migration system is **not so good in a modular environment** where each module maintains its **own database schema** while two or more modules may **share a single database** in practical.
+
+Since ABP Framework cares about modularity in all aspects, it provides a **solution** to this problem. It is important to understand this solution if you need to **customize your database structure**.
+
+This document begins by **introducing the default structure** provided by [the application startup template](Startup-Templates/Application.md) and **discusses various scenarios** you may want to implement for your application.
+
+## The Default Solution & Database Configuration
+
+When you [create a new web application](https://abp.io/get-started) (with EF Core, which is the default database provider), your solution structure will be similar to the picture below:
+
+![bookstore-visual-studio-solution-v3](D:\Github\abp\docs\en\images\bookstore-visual-studio-solution-v3.png)
+
+> Actual solution structure may be a bit different based on your preferences, but the database part will be same.
+
+### The Database Structure
+
+The startup template has some [application modules](Modules/Index.md) pre-installed. Each layer of the solution has corresponding module package references. So, the `.EntityFrameworkCore` project has the NuGet references for the `.EntityFrameworkCore` packages of the used modules:
+
+![bookstore-efcore-dependencies](D:\Github\abp\docs\en\images\bookstore-efcore-dependencies.png)
+
+In this way, you collect all the EF Core dependencies under the `.EntityFrameworkCore` project.
+
+> In addition to the module references, it references to the `Volo.Abp.EntityFrameworkCore.SqlServer` package since the startup template is pre-configured for the SQL Server. See the documentation if you want to [switch to another DBMS](Entity-Framework-Core-Other-DBMS.md).
+
+While every module has its own `DbContext` class by design and can use its **own physical database**, the solution is configured to use a **single shared database** as shown in the figure below:
+
+![single-database-usage](D:\Github\abp\docs\en\images\single-database-usage.png)
+
+This is **the simplest configuration** and suitable for most of the applications. `appsettings.json` file has a **single connection string**, named `Default`:
+
+````json
+"ConnectionStrings": {
+  "Default": "..."
+}
+````
+
+So, you have a **single database schema** which contains all the tables of the modules **sharing** this database.
+
+#### Module Tables
+
+Every module uses its own databases tables. For example, the [Identity Module](Modules/Identity.md) has some tables to manage the users and roles in the system. 
+
+#### Table Prefixes
+
+Since it is allowed to share a single database by all modules (it is the default configuration), a module typically uses a prefix to group its own tables.
+
+The fundamental modules, like [Identity](Modules/Identity.md), [Tenant Management](Modules/Tenant-Management.md) and [Audit Logs](Modules/Audit-Logging.md), use the `Abp` prefix, while some other modules use their own prefixes. [Identity Server](Modules/IdentityServer.md) module uses the `IdentityServer` prefix for example.
+
+If you want, you can change the database table name prefix for a module for your application. Example:
+
+````csharp
+Volo.Abp.IdentityServer.AbpIdentityServerDbProperties.DbTablePrefix = "Ids";
+````
+
+This code changes the prefix of the [Identity Server](Modules/IdentityServer.md) module. Write this code at the very beginning in your application.
+
+> Every module also defines `DbSchema` property (near to `DbTablePrefix`), so you can set it for the databases support the schema usage.
+
+### The Projects
+
+From the database point of view, there are three important projects those will be explained in the next sections.
+
+#### .EntityFrameworkCore Project
+
+This project has the `DbContext` class (`BookStoreDbContext` for this sample) of your application. You typically use this `DbContext` in your application code (in your custom [repositories](Repositories.md) if you follow the best practices).
+
+It is almost an empty `DbContext` since your application don't have any entities at the beginning, except the pre-defined `AppUser` entity:
+
+````csharp
+[ConnectionStringName("Default")]
+public class BookStoreDbContext : AbpDbContext<BookStoreDbContext>
+{
+    public DbSet<AppUser> Users { get; set; }
+
+    /* Add DbSet properties for your Aggregate Roots / Entities here. */
+
+    public BookStoreDbContext(DbContextOptions<BookStoreDbContext> options)
+        : base(options)
+    {
+
+    }
+
+    protected override void OnModelCreating(ModelBuilder builder)
+    {
+        base.OnModelCreating(builder);
+
+        /* Configure the shared tables (with included modules) here */
+
+        builder.Entity<AppUser>(b =>
+        {
+            //Sharing the same table "AbpUsers" with the IdentityUser
+            b.ToTable("AbpUsers"); 
+            
+            //Configure base properties
+            b.ConfigureByConvention();
+            b.ConfigureAbpUser();
+
+            //Moved customization of the "AbpUsers" table to an extension method
+            b.ConfigureCustomUserProperties();
+        });
+
+        /* Configure your own tables/entities inside the ConfigureBookStore method */
+        builder.ConfigureBookStore();
+    }
+}
+````
+
+This simple `DbContext` class still needs some explanations:
+
+* It defines a `[ConnectionStringName]` attribute which tells ABP to use the `Default` connection string for this `Dbcontext` (You can see the [connection string document](Connection-Strings.md) to learn how ABP manages the connection strings. For now, you can ignore it since this document will return to this topic later).
+* It inherits from the `AbpDbContext<T>`  instead of the standard `DbContext` class (You can see the [EF Core integration](Entity-Framework-Core.md) document for more. For now, know that the `AbpDbContext<T>` base class implements some conventions of the ABP Framework to automate some common tasks for you).
+* It declares a `DbSet` property for the `AppUser` entity. `AppUser` shares the same table (named `AbpUsers` by default) with the `IdentityUser` entity of the [Identity module](Modules/Identity.md). The startup template provides this entity inside the application since we think that the User entity is generally needs to be customized in your application.
+* The constructor takes a `DbContextOptions<T>` instance.
+* It overrides the `OnModelCreating` method to define the EF Core mappings.
+  * It first calls the the `base.OnModelCreating` method to let the ABP Framework to implement the base mappings for us.
+  * It then configures the mapping for the `AppUser` entity. There is a special case for this entity, which will be explained in the next sections.
+  * It finally calls the `builder.ConfigureBookStore()` extension method to configure other entities of your application.

docs/en/Modules/Identity.md

@@ -0,0 +1,4 @@
+# Identity Management Module
+
+See [the source code](https://github.com/abpframework/abp/tree/dev/modules/identity). Documentation will come soon...
+

docs/en/Modules/Tenant-Management.md

@@ -0,0 +1,3 @@
+# Tenant Management Module
+
+TODO