diff --git a/docs/en/FluentValidation.md b/docs/en/FluentValidation.md new file mode 100644 index 0000000000..bb45fb96d8 --- /dev/null +++ b/docs/en/FluentValidation.md @@ -0,0 +1,3 @@ +# FluentValidation Integration + +TODO \ No newline at end of file diff --git a/docs/en/Logging.md b/docs/en/Logging.md new file mode 100644 index 0000000000..9b9c604bed --- /dev/null +++ b/docs/en/Logging.md @@ -0,0 +1,5 @@ +# Logging + +ABP Framework doesn't implement any logging infrastructure. It uses the [ASP.NET Core's logging system](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging). + +> .NET Core's logging system is actually independent from the ASP.NET Core. It is usable in any type of application. \ No newline at end of file diff --git a/docs/en/Validation.md b/docs/en/Validation.md index a4b829c97d..0b86b50e40 100644 --- a/docs/en/Validation.md +++ b/docs/en/Validation.md @@ -1,3 +1,125 @@ -## Validation +# Validation -TODO \ No newline at end of file +Validation system is used to validate the user input or client request for a particular controller action or service method. + +ABP is compatible with the ASP.NET Core Model Validation system and everything written in [its documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/models/validation) is already valid for ABP based applications. So, this document mostly focuses on the ABP features rather than repeating the Microsoft documentation. + +In addition, ABP adds the following benefits: + +* Defines `IValidationEnabled` to add automatic validation to an arbitrary class. Since all the [application services](Application-Services.md) inherently implements it, they are also validated automatically. +* Automatically localize the validation errors. +* Provides extensible services to validate a method call or an object state. +* Provides [FluentValidation](https://fluentvalidation.net/) integration. + +## Validating DTOs + +This section briefly introduces the validation system. For details, see the [ASP.NET Core validation documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/models/validation). + +### Data Annotation Attributes + +Using data annotations is a simple way to implement the formal validation for a [DTO](Data-Transfer-Objects.md) in a declarative way. Example: + +````csharp +public class CreateBookDto +{ + [Required] + [StringLength(100)] + public string Name { get; set; } + + [Required] + [StringLength(1000)] + public string Description { get; set; } + + [Range(0, 999.99)] + public decimal Price { get; set; } +} +```` + +When you use this class as a parameter to an [application service](Application-Services.md) or a controller, it is automatically validated and a localized validation exception is thrown ([and handled](Exception-Handling.md) by the ABP framework). + +### IValidatableObject + +`IValidatableObject` can be implemented by a DTO to perform custom validation logic. `CreateBookDto` in the following example implements this interface and checks if the `Name` is equals to the `Description` and returns a validation error in this case. + +````csharp +using System.Collections.Generic; +using System.ComponentModel.DataAnnotations; + +namespace Acme.BookStore +{ + public class CreateBookDto : IValidatableObject + { + [Required] + [StringLength(100)] + public string Name { get; set; } + + [Required] + [StringLength(1000)] + public string Description { get; set; } + + [Range(0, 999.99)] + public decimal Price { get; set; } + + public IEnumerable Validate( + ValidationContext validationContext) + { + if (Name == Description) + { + yield return new ValidationResult( + "Name and Description can not be the same!", + new[] { "Name", "Description" } + ); + } + } + } +} +```` + +#### Resolving a Service + +If you need to resolve a service from the [dependency injection system](Dependency-Injection.md), you can use the `ValidationContext` object. Example: + +````csharp +var myService = validationContext.GetRequiredService(); +```` + +> While resolving services in the `Validate` method allows any possibility, it is not a good practice to implement your domain validation logic in DTOs. Keep DTOs simple. Their purpose is to transfer data (DTO: Data Transfer Object). + +## Validation Infrastructure + +This section explains a few additional services provided by the ABP framework. + +### IValidationEnabled Interface + +`IValidationEnabled` is an empty marker interface that can be implemented by any class (registered to and resolved from the [DI](Dependency-Injection.md)) to let the ABP framework perform the validation system for the methods of the class. Example: + +````csharp +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Validation; + +namespace Acme.BookStore +{ + public class MyService : ITransientDependency, IValidationEnabled + { + public virtual async Task DoItAsync(MyInput input) + { + //... + } + } +} +```` + +> ABP framework uses the [dynamic proxying / interception](Dynamic-Proxying-Interceptors.md) system to perform the validation. In order to make it working, your method should be **virtual** or your service should be injected and used over an **interface** (like `IMyService`). + +### AbpValidationException + +Once ABP determines a validation error, it throws an exception of type `AbpValidationException`. Your application code can throw `AbpValidationException`, but most of the times it is not needed. + +* `ValidationErrors` property of the `AbpValidationException` contains the validation error list. +* Log level of the `AbpValidationException` is set to `Warning`. It logs all the validation errors to the [logging system](Logging.md). +* `AbpValidationException` is automatically caught by the ABP framework and converted to a usable error into with HTTP 400 status code. See the [exception handling](Exception-Handling.md) document for more. + +## FluentValidation Integration + +Volo.Abp.FluentValidation package integrates the FluentValidation library to the validation system. See the [FluentValidation Integration document](FluentValidation.md) for more. \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 5667631c61..cf636ca182 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -87,7 +87,14 @@ "path": "Exception-Handling.md" }, { - "text": "Validation" + "text": "Validation", + "path": "Validation.md", + "items": [ + { + "text": "FluentValidation Integration", + "path": "FluentValidation.md" + } + ] }, { "text": "Authorization",