diff --git a/docs/en/Application-Services.md b/docs/en/Application-Services.md index d28a7290fb..9cfec614cb 100644 --- a/docs/en/Application-Services.md +++ b/docs/en/Application-Services.md @@ -367,6 +367,84 @@ public class DistrictKey } ```` +### Authorization (for CRUD App Services) + +There are two ways of authorizing the base application service methods; + +1. You can set the policy properties (xxxPolicyName) in the constructor of your service. Example: + +```csharp +public class MyPeopleAppService : CrudAppService +{ + public MyPeopleAppService(IRepository repository) + : base(repository) + { + GetPolicyName = "..."; + GetListPolicyName = "..."; + CreatePolicyName = "..."; + UpdatePolicyName = "..."; + DeletePolicyName = "..."; + } +} +``` + +`CreatePolicyName` is checked by the `CreateAsync` method and so on... You should specify a policy (permission) name defined in your application. + +2. You can override the check methods (CheckXxxPolicyAsync) in your service. Example: + +```csharp +public class MyPeopleAppService : CrudAppService +{ + public MyPeopleAppService(IRepository repository) + : base(repository) + { + } + + protected override async Task CheckDeletePolicyAsync() + { + await AuthorizationService.CheckAsync("..."); + } +} +``` + +You can perform any logic in the `CheckDeletePolicyAsync` method. It is expected to throw an `AbpAuthorizationException` in any unauthorized case, like `AuthorizationService.CheckAsync` already does. + +### Base Properties & Methods + +CRUD application service base class provides many useful base methods that **you can override** to customize it based on your requirements. + +#### CRUD Methods + +These are the essential CRUD methods. You can override any of them to completely customize the operation. Here, the definitions of the methods: + +````csharp +Task GetAsync(TKey id); +Task> GetListAsync(TGetListInput input); +Task CreateAsync(TCreateInput input); +Task UpdateAsync(TKey id, TUpdateInput input); +Task DeleteAsync(TKey id); +```` + +#### Querying + +These methods are low level methods those can be control how to query entities from the database. + +* `CreateFilteredQuery` can be overridden to create an `IQueryable` that is filtered by the given input. If your `TGetListInput` class contains any filter, it is proper to override this method and filter the query. It returns the (unfiltered) repository (which is already `IQueryable`) by default. +* `ApplyPaging` is used to make paging on the query. If your `TGetListInput` already implements `IPagedResultRequest`, you don't need to override this since the ABP Framework automatically understands it and performs the paging. +* `ApplySorting` is used to sort (order by...) the query. If your `TGetListInput` already implements the `ISortedResultRequest`, ABP Framework automatically sorts the query. If not, it fallbacks to the `ApplyDefaultSorting` which tries to sort by creating time, if your entity implements the standard `IHasCreationTime` interface. +* `GetEntityByIdAsync` is used to get an entity by id, which calls `Repository.GetAsync(id)` by default. +* `DeleteByIdAsync` is used to delete an entity by id, which calls `Repository.DeleteAsync(id)` by default. + +#### Object to Object Mapping + +These methods are used to convert Entities to DTOs and vice verse. They uses the [IObjectMapper](Object-To-Object-Mapping.md) by default. + +* `MapToGetOutputDtoAsync` is used to map the entity to the DTO returned from the `GetAsync`, `CreateAsync` and `UpdateAsync` methods. Alternatively, you can override the `MapToGetOutputDto` if you don't need to perform any async operation. +* `MapToGetListOutputDtosAsync` is used to map a list of entities to a list of DTOs returned from the `GetListAsync` method. It uses the `MapToGetListOutputDtoAsync` to map each entity in the list. You can override one of them based on your case. Alternatively, you can override the `MapToGetListOutputDto` if you don't need to perform any async operation. +* `MapToEntityAsync` method has two overloads; + * `MapToEntityAsync(TCreateInput)` is used to create an entity from `TCreateInput`. + * `MapToEntityAsync(TUpdateInput, TEntity)` is used to update an existing entity from `TUpdateInput`. + ## Lifetime Lifetime of application services are [transient](Dependency-Injection.md) and they are automatically registered to the dependency injection system.