diff --git a/docs/en/Community-Articles/2023-03-20-Dapper/POST.md b/docs/en/Community-Articles/2023-03-20-Dapper/POST.md index 4fae76c4bb..9860013766 100644 --- a/docs/en/Community-Articles/2023-03-20-Dapper/POST.md +++ b/docs/en/Community-Articles/2023-03-20-Dapper/POST.md @@ -15,7 +15,7 @@ In ABP Framework, we suggest to use Dapper in a combination with Entity Framewor * EF Core's change tracking system automatically update changes in the database. * EF Core is better compatible with Object Oriented Programming (OOP) practices and is more type safe to work with. So, EF Core code is more understandable and maintainable. -In most of your use cases, you typically work with one or a few entities and a maintainable codebase can be chosen instead of slight performance difference. However, there may be certain places in your application where it matters: +In most of your use cases, you typically work with one or a few entities and a maintainable codebase can be chosen instead of a slight performance difference. However, there may be certain places in your application where it matters: * You may work with a lot of entities, so want to query faster (Indeed, EF Core's [AsNoTracking()](https://learn.microsoft.com/en-us/ef/core/querying/tracking) extension can help in most cases). * You may be performing too many database operations in a single request. @@ -23,6 +23,32 @@ In most of your use cases, you typically work with one or a few entities and a m For such cases, Dapper can be a good choice. You can easily write SQL queries and bind the result to your objects. +## Creating a new ABP Solution + +To demonstrate the Dapper usage, I've created an ABP solution. You can find the [full source code of the demo application here](https://github.com/abpframework/abp-samples/tree/master/Dapper). If you want to create the same solution from scratch, follow the steps below: + +Install the ABP CLI if you haven't installed it before: + +````bash +dotnet tool install -g Volo.Abp.Cli +```` + +Create a new solution with the ABP Framework's non-layered startup template with MVC UI and EF Core database: + +```` +abp new DapperDemo -t app-nolayers +```` + +> The startup template or a different UI selection don't matter for this article. I selected these options to keep the demo solution simple. + +After creating the solution, run the following command to migrate the database (run the command in the folder of the `.csproj` file: + +````csharp +dotnet run --migrate-database +```` + +> If you've created a layered solution, then run the `DbMigrator` application inside the solution. If you have trouble by creating the solution, please refer to the [Quick Start](https://docs.abp.io/en/abp/latest/Tutorials/Todo/Single-Layer/Index) document. + ## Setting Up the Entity Framework Core Part We will use EF Core with Dapper, so we need to configure the EF Core first. I will use the following `Book` entity as an example: @@ -36,12 +62,16 @@ public class Book : AuditedAggregateRoot } ```` -Once I created the `Book` entity, I should add it to my `DbContext` class. +If you are using a layered solution, entities are located in the `Domain` project. For my demo solution, I just placed it in the `Entities` folder of the single project: + +![book-class-in-rider](book-class-in-rider.png) + +Once I created the `Book` entity, I should add it to my `DbContext` class: ````csharp public class DapperDemoDbContext : AbpDbContext { - // 1 - ADD A DBSET PROPERTY + // 1: ADD A DBSET PROPERTY public DbSet Books { get; set; } public DapperDemoDbContext(DbContextOptions options) @@ -53,7 +83,7 @@ public class DapperDemoDbContext : AbpDbContext { //...other code parts - // 1 - MAP YOUR ENTITY TO THE DATABASE TABLE + // 2: MAP YOUR ENTITY TO A DATABASE TABLE builder.Entity(b => { b.ToTable("Books"); @@ -64,7 +94,77 @@ public class DapperDemoDbContext : AbpDbContext ```` -TODO: database migrations... +Now, we can add a new database migration: + +````bash +dotnet ef migrations add Added_Book +```` + +And apply changes to database: + +````bash +dotnet ef database update +```` + +At this point, you should see the Books table if you check your database: + +![book-database-table](book-database-table.png) + +> As you see, the `Books` table contains more fields than the `Book` entity's property count. Other properties are inherited from the `AuditedAggregateRoot` table. You could inherit from the `BasicAggregateRoot` class if you don't want these properties. + +## Seeding the Database + +ABP's [data seeding](https://docs.abp.io/en/abp/latest/Data-Seeding) system is a great way to add some test data to the database. The following class inserts two books to the `Books` table when I migrate the database: + +````csharp +public class DapperDemoDataSeederContributor : IDataSeedContributor, ITransientDependency +{ + private readonly IRepository _bookRepository; + + public DapperDemoDataSeederContributor(IRepository bookRepository) + { + _bookRepository = bookRepository; + } + + public async Task SeedAsync(DataSeedContext context) + { + if (await _bookRepository.GetCountAsync() > 0) + { + return; + } + + await _bookRepository.InsertAsync( + new Book + { + Name = "1984", + PublishDate = new DateTime(1949, 6, 8), + Price = 19.84f + } + ); + + await _bookRepository.InsertAsync( + new Book + { + Name = "The Hitchhiker's Guide to the Galaxy", + PublishDate = new DateTime(1995, 9, 27), + Price = 42.0f + } + ); + } +} +```` + +After creating the `DapperDemoDataSeederContributor` class, I can re-run the following command: + +````bash +dotnet run --migrate-database +```` + +Now, I can see the records in the database: + +![book-table-data](book-table-data.png) + +Now, all ready to try Dapper to query from the `Books` table. ## Using Dapper Without the Integration Package @@ -80,7 +180,118 @@ dotnet add package Dapper > If your application is layered, then we suggest to add the `Dapper` package to your `EntityFrameworkCore` integration project in your solution. +### Executing a Dapper Query + +I will query from the `Books` table, but I don't want to use the `Book` entity to map the result (because I don't need to all properties). So, I am creating a new class for the query result: +````csharp +public class BookDataView +{ + public Guid Id { get; set; } + public string Name { get; set; } + public float Price { get; set; } +} +```` + +Now, we can use Dapper's `QueryAsync` extension method as shown below: + +````csharp +public class DemoService : ITransientDependency +{ + private readonly IRepository _bookRepository; + + public DemoService(IRepository bookRepository) + { + _bookRepository = bookRepository; + } + + [UnitOfWork] + public virtual async Task> GetListAsync() + { + var database = (await _bookRepository.GetDbContextAsync()).Database; + var dbConnection = database.GetDbConnection(); + var dbTransaction = database.CurrentTransaction?.GetDbTransaction(); + + var queryResult = await dbConnection.QueryAsync( + "SELECT Id, Name, Price FROM Books", + transaction: dbTransaction + ); + + return queryResult.ToList(); + } +} +```` + +Let's examine that class: + +* I am injecting ABP's standard [generic repository](https://docs.abp.io/en/abp/latest/Repositories) service in to the `DemoService` constructor. +* `_bookRepository.GetDbContextAsync()` returns the underlying `DbContext` object of EF Core. We need to have the [Volo.Abp.EntityFrameworkCore](https://www.nuget.org/packages/Volo.Abp.EntityFrameworkCore) package reference to be able to access that method. If you have created a single-layer solution, the reference does already exists. If you have created a layered solution you may need to manually add this package to the project that contains the `DemoService` class. Because the layered solution isolates the EF Core dependency from rest of the solution. +* Dapper needs a `DbConnection` and a `DbTransaction` object (as optional) to execute a query. We are getting them over the `database` object obtained from the `DbContext`. We suggest to always pass the current `DbTransaction` object while working with Dapper. Because, if there is a database transaction on the same database connection that you execute queries, and you don't pass the transaction object, you get an exception. +* Finally, we can use Dapper's `QueryAsync` extension method to execute the database query. +* Notice that the `GetListAsync` method is made as `virtual` and marked with `UnitOfWork` attribute to enable the [Unit Of Work](https://docs.abp.io/en/abp/latest/Unit-Of-Work) for that method. It ensures the database connection is available in the body of the `GetListAsync` method. + +That's all. You can execute any Dapper operation using the `DbConnection` and `DbTransaction` objects obtained from the `_bookRepository` object. Please refer to Dapper's documentation for other operations. + +> We've obtained the `DbContext` object from a repository. However, a repository is not required to obtain a `DbContext`. Instead, you could inject the `IDbContextProvider` service (`IDbContextProvider` for this demo) and call its `GetDbContextAsync` method. + +## Using the Volo.Abp.Dapper Package + +In the previous section, you saw that you don't need to an ABP integration package to be able to use Dapper in your ABP applications. However, there is an integration package here: [Volo.Abp.Dapper](https://www.nuget.org/packages/Volo.Abp.Dapper). Actually, that package doesn't contain much services. It just provides a convenient base class to create Dapper based repository classes. + +### Installing the Volo.Abp.Dapper Package + +You can use [ABP CLI](https://docs.abp.io/en/abp/latest/CLI#add-package) to easily install ABP packages to your projects. Execute the following command in the folder of `.csproj` you want to install the package: + +```` +abp add-package Volo.Abp.Dapper +```` + +> You can check the [ABP Dapper document](https://docs.abp.io/en/abp/latest/Dapper) for alternative installation options. + +### Creating a Repository Class + +In the `DemoService` example, we have used database objects out of a [repository](https://docs.abp.io/en/abp/latest/Repositories) class. If you want to implement layering your solution and abstracting database operations, it can be better to create a repository class to execute Dapper operations. + +Here, a repository class that executes the same database query: + +````csharp +public class BookRepository : DapperRepository, ITransientDependency +{ + public BookRepository(IDbContextProvider dbContextProvider) + : base(dbContextProvider) + { + } + + public virtual async Task> GetListAsync() + { + var connection = await GetDbConnectionAsync(); + var queryResult = await connection.QueryAsync( + "SELECT Id, Name, Price FROM Books", + transaction: await GetDbTransactionAsync() + ); + return queryResult.ToList(); + } +} +```` + +Let's examine that class: + +* It inherits from the `DapperRepository` class, which provides useful methods and properties for database operations. It also implements the `IUnitOfWorkEnabled` interface, so ABP makes the database connection (and transaction if requested) available in the method body by implementing dynamic proxies (a.k.a. interception). +* `GetListAsync` method made `virtual`. That's needed to make the interception process working. It wouldn't be needed if we introduce `IBookRepository` for that class and always use it by injecting the `BookRepository` class (in this case, it will use interface proxying - however, this is too much details for the purpose of this article). +* We are using the `GetDbConnectionAsync` and `GetDbTransactionAsync` methods to obtain the current database connection and transaction (that is managed by ABP's [unit of work](https://docs.abp.io/en/abp/latest/Unit-Of-Work) system). + +You can then inject the `BookRepository` class when you want to get a list of `BookDataView` whenever it is needed. In the demo project, I used it inside the `IndexModel.cshtml.cs` to show a list of books on the page: + +![list-of-books](list-of-books.png) + +## Conclusion + +In this article, I've explained ABP's Dapper integration and demonstrated how you can execute Dapper operations in your applications. I suggest to use Dapper when it is really needed and adds any significant value (generally a performance gain) to your application. Otherwise, EF Core is much more convenient for most of the database operations and you will have a more maintainable codebase using EF Core. + +## Source Code + +You can find the [full source code of the demo application here](https://github.com/abpframework/abp-samples/tree/master/Dapper). -s +## See Also +* [ABP Dapper documentation](https://docs.abp.io/en/abp/latest/Dapper) diff --git a/docs/en/Community-Articles/2023-03-20-Dapper/book-class-in-rider.png b/docs/en/Community-Articles/2023-03-20-Dapper/book-class-in-rider.png new file mode 100644 index 0000000000..db1e5791b4 Binary files /dev/null and b/docs/en/Community-Articles/2023-03-20-Dapper/book-class-in-rider.png differ diff --git a/docs/en/Community-Articles/2023-03-20-Dapper/book-database-table.png b/docs/en/Community-Articles/2023-03-20-Dapper/book-database-table.png new file mode 100644 index 0000000000..d1584118d9 Binary files /dev/null and b/docs/en/Community-Articles/2023-03-20-Dapper/book-database-table.png differ diff --git a/docs/en/Community-Articles/2023-03-20-Dapper/book-table-data.png b/docs/en/Community-Articles/2023-03-20-Dapper/book-table-data.png new file mode 100644 index 0000000000..6b9ea69b59 Binary files /dev/null and b/docs/en/Community-Articles/2023-03-20-Dapper/book-table-data.png differ diff --git a/docs/en/Community-Articles/2023-03-20-Dapper/list-of-books.png b/docs/en/Community-Articles/2023-03-20-Dapper/list-of-books.png new file mode 100644 index 0000000000..23b190afa6 Binary files /dev/null and b/docs/en/Community-Articles/2023-03-20-Dapper/list-of-books.png differ