@ -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<Guid>
}
````
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:
Once I created the `Book` entity, I should add it to my `DbContext` class:
````csharp
public class DapperDemoDbContext : AbpDbContext<DapperDemoDbContext>
{
// 1 - ADD A DBSET PROPERTY
// 1: ADD A DBSET PROPERTY
public DbSet<Book> Books { get; set; }
public DapperDemoDbContext(DbContextOptions<DapperDemoDbContext> options)
@ -53,7 +83,7 @@ public class DapperDemoDbContext : AbpDbContext<DapperDemoDbContext>
{
//...other code parts
// 1 - MAP YOUR ENTITY TO THE DATABASE TABLE
// 2: MAP YOUR ENTITY TO A DATABASE TABLE
builder.Entity<Book>(b =>
{
b.ToTable("Books");
@ -64,7 +94,77 @@ public class DapperDemoDbContext : AbpDbContext<DapperDemoDbContext>
````
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:
> 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
public DapperDemoDataSeederContributor(IRepository<Book,Guid> 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:
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:
public DemoService(IRepository<Book,Guid> bookRepository)
{
_bookRepository = bookRepository;
}
[UnitOfWork]
public virtual async Task<List<BookDataView>> GetListAsync()
{
var database = (await _bookRepository.GetDbContextAsync()).Database;
var dbConnection = database.GetDbConnection();
var dbTransaction = database.CurrentTransaction?.GetDbTransaction();
var queryResult = await dbConnection.QueryAsync<BookDataView>(
"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<T>` service (`IDbContextProvider<DapperDemoDbContext>` 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<DapperDemoDbContext>, ITransientDependency
{
public BookRepository(IDbContextProvider<DapperDemoDbContext> dbContextProvider)
: base(dbContextProvider)
{
}
public virtual async Task<List<BookDataView>> GetListAsync()
{
var connection = await GetDbConnectionAsync();
var queryResult = await connection.QueryAsync<BookDataView>(
"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:
## 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).
Halil İbrahim Kalkan
4 years ago
