@ -174,12 +174,12 @@ public static IQueryable<IdentityUser> IncludeDetails(
* **Do** use the `IncludeDetails` extension method in the repository methods just like used in the example code above (see FindByNormalizedUserNameAsync).
* **Do** use the `IncludeDetails` extension method in the repository methods just like used in the example code above (see FindByNormalizedUserNameAsync).
- **Do** override `IncludeDetails` method of the repository for aggregates root which have **sub collections**. Example:
- **Do** override `WithDetails` method of the repository for aggregates root which have **sub collections**. Example:
ABP framework was designed as database agnostic, it can work any type of data source by the help of the [repository](Repositories.md) and [unit of work](Unit-Of-Work.md) abstractions.
ABP framework was designed as database agnostic. It can work any type of data source by the help of the [repository](Repositories.md) and [unit of work](Unit-Of-Work.md) abstractions. However, currently the following providers are implemented:
However, currently the following providers are implements:
* [Entity Framework Core](Entity-Framework-Core.md) (works with [various DBMS and providers](https://docs.microsoft.com/en-us/ef/core/providers/).)
* [Entity Framework Core](Entity-Framework-Core.md) (works with [various DBMS and providers](https://docs.microsoft.com/en-us/ef/core/providers/?tabs=dotnet-core-cli).)
* [MongoDB](MongoDB.md)
* [MongoDB](MongoDB.md)
* [Dapper](Dapper.md)
* [Dapper](Dapper.md)
More providers might be added in the next releases.
This document explains how to switch to the **MySQL** database provider for **[the application startup template](Startup-Templates/Application.md)** which comes with SQL Server provider pre-configured.
## Replace the Volo.Abp.EntityFrameworkCore.SqlServer Package
`.EntityFrameworkCore` project in the solution depends on the [Volo.Abp.EntityFrameworkCore.SqlServer](https://www.nuget.org/packages/Volo.Abp.EntityFrameworkCore.SqlServer) NuGet package. Remove this package and add the same version of the [Volo.Abp.EntityFrameworkCore.MySQL](https://www.nuget.org/packages/Volo.Abp.EntityFrameworkCore.MySQL) package.
## Replace the Module Dependency
Find ***YourProjectName*EntityFrameworkCoreModule** class inside the `.EntityFrameworkCore` project, remove `typeof(AbpEntityFrameworkCoreSqlServerModule)` from the `DependsOn` attribute, add `typeof(AbpEntityFrameworkCoreMySQLModule)` (also replace `using Volo.Abp.EntityFrameworkCore.SqlServer;` with `using Volo.Abp.EntityFrameworkCore.MySQL;`).
## Call UseMySQL
Find `UseSqlServer()` calls in your solution, replace with `UseMySQL()`
> Note: Instead, you can directly download a [startup template](https://abp.io/Templates) with EF Core pre-installed.
> Note: Instead, you can directly download a [startup template](https://abp.io/Templates) with EF Core pre-installed.
### Database Management System Selection
Entity Framework Core supports various database management systems ([see all](https://docs.microsoft.com/en-us/ef/core/providers/)). ABP framework and this document doesn't depend on any specific DBMS.
If you are creating a reusable library, avoid to depend on a specific DBMS package. However, in a final application you eventually will select a DBMS.
ABP framework provides integration packages for some common DBMSs to make the configuration a bit easier. [The startup templates](Startup-Templates/Index.md) come with **SQL Server (localdb) pre-configured**. See the following documents to learn how to configure for the other DBMS providers:
You can create your DbContext as you normally do. It should be derived from `AbpDbContext<T>` as shown below:
You can create your DbContext as you normally do. It should be derived from `AbpDbContext<T>` as shown below:
@ -62,7 +73,7 @@ public class MyDbContext : AbpDbContext<MyDbContext>
}
}
```
```
If you don't configure, the `Default` connection string is used. If you configure a specific connection string name, but not define this connection string name in the application configuration then it fallbacks to the `Default` connection string.
If you don't configure, the `Default` connection string is used. If you configure a specific connection string name, but not define this connection string name in the application configuration then it fallbacks to the `Default` connection string (see [the connection strings document](Connection-Strings.md) for more information).
## Registering DbContext To Dependency Injection
## Registering DbContext To Dependency Injection
@ -126,7 +137,8 @@ public class BookManager : DomainService
public BookManager(IRepository<Book,Guid> bookRepository) //inject default repository
//inject default repository to the constructor
public BookManager(IRepository<Book,Guid> bookRepository)
{
{
_bookRepository = bookRepository;
_bookRepository = bookRepository;
}
}
@ -142,7 +154,8 @@ public class BookManager : DomainService
Type = type
Type = type
};
};
await _bookRepository.InsertAsync(book); //Use a standard repository method
//Use a standard repository method
await _bookRepository.InsertAsync(book);
return book;
return book;
}
}
@ -153,9 +166,9 @@ This sample uses `InsertAsync` method to insert a new entity to the database.
### Add Custom Repositories
### Add Custom Repositories
Default generic repositories are powerful enough in most cases (since they implement `IQueryable`). However, you may need to create a custom repository to add your own repository methods.
Default generic repositories are powerful enough in most cases (since they implement `IQueryable`). However, you may need to create a custom repository to add your own repository methods. Assume that you want to delete all books by type.
Assume that you want to delete all books by type. It's suggested to define an interface for your custom repository:
It's suggested to define an interface for your custom repository:
````csharp
````csharp
public interface IBookRepository : IRepository<Book,Guid>
public interface IBookRepository : IRepository<Book,Guid>
@ -187,21 +200,23 @@ public class BookRepository : EfCoreRepository<BookStoreDbContext, Book, Guid>,
Now, it's possible to [inject](Dependency-Injection.md) the `IBookRepository` and use the `DeleteBooksByType` method when needed.
Now, it's possible to [inject](Dependency-Injection.md) the `IBookRepository` and use the `DeleteBooksByType` method when needed.
#### Override Default Generic Repository
#### Override the Default Generic Repository
Even if you create a custom repository, you can still inject the default generic repository (`IRepository<Book,Guid>` for this example). Default repository implementation will not use the class you have created.
Even if you create a custom repository, you can still inject the default generic repository (`IRepository<Book,Guid>` for this example). Default repository implementation will not use the class you have created.
If you want to replace default repository implementation with your custom repository, do it inside `AddAbpDbContext` options:
If you want to replace default repository implementation with your custom repository, do it inside the `AddAbpDbContext` options:
This is especially important when you want to **override a base repository method** to customize it. For instance, you may want to override `DeleteAsync` method to delete an entity in a more efficient way:
This is especially important when you want to **override a base repository method** to customize it. For instance, you may want to override `DeleteAsync` method to delete a specific entity in a more efficient way:
````csharp
````csharp
public override async Task DeleteAsync(
public override async Task DeleteAsync(
@ -215,7 +230,7 @@ public override async Task DeleteAsync(
### Access to the EF Core API
### Access to the EF Core API
In most cases, you want to hide EF Core APIs behind a repository (this is the main purpose of the repository). However, if you want to access the DbContext instance over the repository, you can use `GetDbContext()` or `GetDbSet()` extension methods. Example:
In most cases, you want to hide EF Core APIs behind a repository (this is the main purpose of the repository pattern). However, if you want to access the `DbContext` instance over the repository, you can use `GetDbContext()` or `GetDbSet()` extension methods. Example:
````csharp
````csharp
public class BookService
public class BookService
@ -243,9 +258,9 @@ public class BookService
#### Set Default Repository Classes
#### Set Default Repository Classes
Default generic repositories are implemented by `EfCoreRepository` class by default. You can create your own implementation and use it for default repository implementation.
Default generic repositories are implemented by `EfCoreRepository` class by default. You can create your own implementation and use it for all the default repository implementations.
First, define your repository classes like that:
First, define your default repository classes like that:
```csharp
```csharp
public class MyRepositoryBase<TEntity>
public class MyRepositoryBase<TEntity>
@ -271,7 +286,7 @@ public class MyRepositoryBase<TEntity, TKey>
First one is for [entities with composite keys](Entities.md), second one is for entities with single primary key.
First one is for [entities with composite keys](Entities.md), second one is for entities with single primary key.
It's suggested to inherit from the `EfCoreRepository` class and override methods if needed. Otherwise, you will have to implement all standard repository methods manually.
It's suggested to inherit from the `EfCoreRepository` class and override methods if needed. Otherwise, you will have to implement all the standard repository methods manually.
Now, you can use `SetDefaultRepositoryClasses` option:
Now, you can use `SetDefaultRepositoryClasses` option:
@ -40,6 +40,33 @@ ABP automatically discovers this class and registers the setting definitions.
* **Providers**: Can be used to restrict providers available for a particular setting (see the setting value providers section for more).
* **Providers**: Can be used to restrict providers available for a particular setting (see the setting value providers section for more).
* **Properties**: A name/value collection to set custom properties about this setting those can be used later in the application code.
* **Properties**: A name/value collection to set custom properties about this setting those can be used later in the application code.
### Change Setting Definitions of a Depended Module
In some cases, you may want to change some properties of a settings defined in some other module that your application/module depends on. A setting definition provider can query and update setting definitions.
The following example gets a setting defined by the [Volo.Abp.Emailing](Emailing.md) package and changes its properties:
````csharp
public class MySettingDefinitionProvider : SettingDefinitionProvider
{
public override void Define(ISettingDefinitionContext context)
{
var smtpHost = context.GetOrNull("Abp.Mailing.Smtp.Host");
if (smtpHost != null)
{
smtpHost.DefaultValue = "mail.mydomain.com";
smtpHost.DisplayName =
new LocalizableString(
typeof(MyLocalizationResource),
"SmtpServer_DisplayName"
);
}
}
}
````
> Using constants for the setting names is a good practice and ABP packages do it. `Abp.Mailing.Smtp.Host` setting name is a constant defined by the `EmailSettingNames` class (in the `Volo.Abp.Emailing` namespace).
## Reading Setting Values
## Reading Setting Values
### ISettingProvider
### ISettingProvider
@ -118,6 +145,30 @@ There are 5 pre-built setting value providers registered by the order below:
Global, Tenant and User setting value providers use the `ISettingStore` to read the value from the data source (see the section below).
Global, Tenant and User setting value providers use the `ISettingStore` to read the value from the data source (see the section below).
### Setting Values in the Application Configuration
As mentioned in the previous section, `ConfigurationSettingValueProvider` reads the settings from the `IConfiguration` service, which can read values from the `appsettings.json` by default. So, the easiest way to configure setting values to define them in the `appsettings.json` file.
For example, you can configure [IEmailSender](Emailing.md) settings as shown below:
"Abp.Mailing.DefaultFromDisplayName": "My Application",
"Abp.Mailing.Smtp.Host": "mail.mydomain.com",
"Abp.Mailing.Smtp.Port": "547",
"Abp.Mailing.Smtp.UserName": "myusername",
"Abp.Mailing.Smtp.Password": "mySecretPassW00rd",
"Abp.Mailing.Smtp.EnableSsl": "True"
}
}
````
Setting values should be configured under the `Settings` section as like in this example.
> `IConfiguration` is an .NET Core service and it can read values not only from the `appsettings.json`, but also from the environment, user secrets... etc. See [Microsoft's documentation]( https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/ ) for more.
### Custom Setting Value Providers
### Custom Setting Value Providers
If you need to extend the setting system, you can define a class derived from the `SettingValueProvider` class. Example:
If you need to extend the setting system, you can define a class derived from the `SettingValueProvider` class. Example:
@ -165,7 +216,7 @@ This example adds it as the last item, so it will be the first value provider us
### ISettingStore
### ISettingStore
While a setting value provider is free to use any source to get the setting value, the`ISettingStore` service is the default source of the setting values. Global, Tenant and User setting value providers use it.
While a setting value provider is free to use any source to get the setting value, the`ISettingStore` service is the default source of the setting values. Global, Tenant and User setting value providers use it.
Mehmet Tüken
7 years ago