diff --git a/docs/en/Entity-Framework-Core-Migrations.md b/docs/en/Entity-Framework-Core-Migrations.md new file mode 100644 index 0000000000..7b4e31bc6e --- /dev/null +++ b/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 +{ + public DbSet Users { get; set; } + + /* Add DbSet properties for your Aggregate Roots / Entities here. */ + + public BookStoreDbContext(DbContextOptions options) + : base(options) + { + + } + + protected override void OnModelCreating(ModelBuilder builder) + { + base.OnModelCreating(builder); + + /* Configure the shared tables (with included modules) here */ + + builder.Entity(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` 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` 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` 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. \ No newline at end of file diff --git a/docs/en/Modules/Identity.md b/docs/en/Modules/Identity.md new file mode 100644 index 0000000000..028144c624 --- /dev/null +++ b/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... + diff --git a/docs/en/Modules/Tenant-Management.md b/docs/en/Modules/Tenant-Management.md new file mode 100644 index 0000000000..73e16aee8e --- /dev/null +++ b/docs/en/Modules/Tenant-Management.md @@ -0,0 +1,3 @@ +# Tenant Management Module + +TODO \ No newline at end of file diff --git a/docs/en/_resources/Diagrams.docx b/docs/en/_resources/Diagrams.docx new file mode 100644 index 0000000000..ed03173ec3 Binary files /dev/null and b/docs/en/_resources/Diagrams.docx differ diff --git a/docs/en/images/bookstore-efcore-dependencies.png b/docs/en/images/bookstore-efcore-dependencies.png new file mode 100644 index 0000000000..3de5a679ef Binary files /dev/null and b/docs/en/images/bookstore-efcore-dependencies.png differ diff --git a/docs/en/images/single-database-usage.png b/docs/en/images/single-database-usage.png new file mode 100644 index 0000000000..525cd7ad0a Binary files /dev/null and b/docs/en/images/single-database-usage.png differ