Merge tag '9.0.0' into net35

Tag 9.0.0

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or sample code about the feature request here.

.github/ISSUE_TEMPLATE/support-request.md

@@ -0,0 +1,21 @@
+---
+name: Support Request
+about: Issues, bug reports and general support requests
+title: ''
+labels: ''
+assignees: ''
+
+---
+<!--
+Please check the documentation at https://fluentvalidation.net first to see if your question is addressed there.
+If not, please fill in the details below.
+-->
+
+**Which version of FluentValidation are you using?**
+Please specify which version of FluentValidation you're using. 
+
+**Which version of ASP.NET are you using?**
+If you are using FluentValidation with ASP.NET, please provide the version of ASP.NET that you're using (eg .NET Core 2.1, NET Core 3.1 etc)
+
+**Describe the issue that you're having**
+A clear and concise description of the issue that you're having, steps to reproduce, and sample code to reproduce the issue. 

CONTRIBUTING.md

@@ -22,9 +22,9 @@ Please log a new issue in the appropriate GitHub repository:
 * [Legacy ASP.NET MVC5 / WebApi 2 extensions](https://github.com/FluentValidation/FluentValidation.LegacyWeb)
 
 ## Filing issues
-The best way to get your bug fixed is to be as detailed as you can be about the problem. 
+The best way to get your bug fixed is to be as detailed as you can be about the problem.
 
-Please first check the documentation at https://fluentvalidation.net first to see if your question is addressed there. 
+Please first check the documentation at https://fluentvalidation.net first to see if your question is addressed there.
 If not, then please provide the exact version of FluentValidation that you're using along with a detailed explanation of the issue and complete steps to reproduce the problem is ideal.
 
 Please ensure all sample code is properly formatted and readable (GitHub supports [markdown](https://github.github.com/github-flavored-markdown/))
@@ -36,4 +36,17 @@ Make sure you can build the code. Familiarize yourself with the project workflow
 
 If you wish to submit a new feature, please open an issue to discuss it with the project maintainers - don't open a pull request without first discussing whether the feature fits with the project roadmap.
 
-Tests must be provided for all pull requests that add or change functionality. 
+Tests must be provided for all pull requests that add or change functionality.
+
+## Building the Docs
+
+The docs are built separately from the source code. Building the docs requires Python 3 and pip. This is then used to install Sphinx and dependencies, which then enable `make` to build the site.
+
+For example, on Linux / within WSL:
+
+* `sudo apt install python3-pip`
+* `cd docs` to go to the docs directory
+* `pip3 install -r requirements.txt` to install the required packages for the docs
+* On WSL, you may need to exit and restart at this point.
+* `PATH=$PATH:~/.local/lib/python3.8/site-packages` (you may want to add this to your `.bashrc` file as well.)
+* `make html` to build the site or `make serve` to watch for changes.

Changelog.txt

@@ -1,4 +1,4 @@
-9.0 -
+9.0 - 6 July 2020
 Removed support for netstandard1.1, netstandard1.6 and net45 (net461 still supported)
 Removed support for unsupported .NET Core versions (2.2 and 3.0). LTS versions are supported (2.1 and 3.1)
 Default email validation mode now uses the same logic as ASP.NET Core. Previous regex behaviour is opt-in.
@@ -29,6 +29,8 @@ SourceLink integration.
 Additional ValidationException constructor that allows using both the default message and a custom one together.
 ScalePrecisionValidator algorithm now matches SQL Server.
 Additional overload of the When methods that contain the validation context.
+Automatically scanned types can be excluded when calling RegisterValidatorsFromAssemblyContaining in ASP.NET Core projects.
+New AutomaticValidationEnabled property for use in ASP.NET Core projects (defaults to true).
 
 8.6.2 - 29 February 2020
 Fix CollectionIndex placeholder not working with async workflow.

README.md

@@ -9,19 +9,12 @@ and lambda expressions for building validation rules.
 FluentValidation can be installed using the Nuget package manager or the `dotnet` CLI.
 
 ```
-Install-Package FluentValidation
+dotnet add package FluentValidation
 ```
 
 For ASP.NET Core integration:
 ```
-Install-Package FluentValidation.AspNetCore
-```
-
-For legacy ASP.NET MVC/WebApi integration:
-
-```
-Install-Package FluentValidation.MVC5
-Install-Package FluentValidation.WebApi
+dotnet add package FluentValidation.AspNetCore
 ```
 
 ---

docs/aspnet.md

@@ -2,12 +2,13 @@
 
 ### Getting Started
 
-FluentValidation can be integrated with ASP.NET Core. Once enabled, MVC will use FluentValidation to validate objects that are passed in to controller actions by the model binding infrastructure.
+FluentValidation supports integration with ASP.NET Core 2.1 or 3.1 (3.1 recommended). Once enabled, MVC will use FluentValidation to validate objects that are passed in to controller actions by the model binding infrastructure.
 
-To enable MVC integration, you'll need to add a reference to the `FluentValidation.AspNetCore` assembly by installing the appropriate NuGet package:
+
+To enable MVC integration, you'll need to add a reference to the `FluentValidation.AspNetCore` assembly by installing the appropriate NuGet package. From the command line, you can install the package by typing:
 
 ```shell
-Install-Package FluentValidation.AspNetCore
+dotnet add package FluentValidation.AspNetCore
 ```
 
 Once installed, you'll need to configure FluentValidation in your app's Startup class by calling the `AddFluentValidation` extension method inside the `ConfigureServices` method (which requires a `using FluentValidation.AspNetCore`). This method must be called directly after calling `AddMvc`.
@@ -21,7 +22,7 @@ public void ConfigureServices(IServiceCollection services) {
 }
 ```
 
-In order for ASP.NET to discover your validators, they must be registered with the services collection. You can either do this by calling the `AddTransient` method for each of your validators...
+In order for ASP.NET to discover your validators, they must be registered with the services collection. You can either do this by calling the `AddTransient` method for each of your validators:
 
 
 ```csharp
@@ -35,19 +36,27 @@ public void ConfigureServices(IServiceCollection services) {
 }
 ```
 
-...or by using the `AddFromAssemblyContaining` method to automatically register all validators within a particular assembly. This will automatically find any public, non-abstract types that inherit from `AbstractValidator` and register them with the container (open generics are not supported).
+### Automatic Registration
+
+You can also use the `AddFromAssemblyContaining` method to automatically register all validators within a particular assembly. This will automatically find any public, non-abstract types that inherit from `AbstractValidator` and register them with the container (open generics are not supported).
 
 ```csharp
 services.AddMvc()
   .AddFluentValidation(fv => fv.RegisterValidatorsFromAssemblyContaining<PersonValidator>());
 ```
 
-```eval_rst
-.. note::
-  Validators that are registered automatically using `RegisterValidationsFromAssemblyContaining` are registered as `Transient` with the container. You can choose to register them as a different lifetime by instead using the extension method `AddValidatorsFromAssemblyContaining`, or by explicitly registering individual validators with the container instead of auto-registering.
+Validators that are registered automatically using `RegisterValidationsFromAssemblyContaining` are registered as `Transient` with the container rather than as `Singleton`. This is done to avoid lifecycle scoping issues where a developer may inadvertantly cause a singleton-scoped validator from depending on a Transient or Request-scoped service (for example, a DB context). If you are aware of these kind of issues and understand how to avoid them, then you may choose to regiter the validators as singletons instead, which will give a performance boost by passing in a second argument: `fv.RegisterValidatorsFromAssemblyContaining<PersonValidator>(lifetime: ServiceLifetime.Singleton)` (note that this optional parameter is only available in FluentValidation 9.0 or newer).
+
+You can also optionally prevent certain types from being automatically registered when using this approach by passing a filter to `RegisterValidationsFromAssemblyContaining`. For example, if there is a specific validator type that you don't want to be registered, you can use a filter callback to exclude it:
+
+```csharp
+services.AddMvc()
+  .AddFluentValidation(fv => fv.RegisterValidatorsFromAssemblyContaining<PersonValidator>(discoveredType => discoveredType.ValidatorType != typeof(SomeValidatorToExclude)));
 ```
 
-This example assumes that the PersonValidator is defined to validate a class called `Person`:
+### Using the validator in a controller
+
+This next example assumes that the `PersonValidator` is defined to validate a class called `Person`. Once you've configured FluentValidation, ASP.NET will then automatically validate incoming requests using the validator mappings configured in your startup routine.
 
 ```csharp
 public class Person {
@@ -67,7 +76,6 @@ public class PersonValidator : AbstractValidator<Person> {
 }
 ```
 
-
 We can use the Person class within our controller and associated view:
 
 ```csharp
@@ -115,7 +123,7 @@ public class PeopleController : Controller {
 
 Now when you post the form, MVC's model-binding infrastructure will validate the `Person` object with the `PersonValidator`, and add the validation results to ModelState.
 
-*Note for advanced users* When validators are executed using this automatic integration, the [RootContextData](/advanced.html#root-context-data) contains an entry called `InvokedByMvc` with a value set to true, which can be used within custom validators to tell whether a validator was invoked automatically (by MVC), or manually.
+*Note for advanced users* When validators are executed using this automatic integration, the [RootContextData](advanced.html#root-context-data) contains an entry called `InvokedByMvc` with a value set to true, which can be used within custom validators to tell whether a validator was invoked automatically (by MVC), or manually.
 
 ### Compatibility with ASP.NET's built-in Validation
 
@@ -133,7 +141,7 @@ services.AddMvc().AddFluentValidation(fv => {
 
 ### Implicit vs Explicit Child Property Validation
 
-When validating complex object graphs, by default, you must explicitly specify any child validators for complex properties by using `SetValidator` ([see the section on validating complex properties](/start.html#complex-properties))
+When validating complex object graphs, by default, you must explicitly specify any child validators for complex properties by using `SetValidator` ([see the section on validating complex properties](start.html#complex-properties))
 
 When running an ASP.NET MVC application, you can also optionally enable implicit validation for child properties. When this is enabled, instead of having to specify child validators using `SetValidator`, MVC's validation infrastructure will recursively attempt to automatically find validators for each property. This can be done by setting `ImplicitlyValidateChildProperties` to true:
 

docs/conf.py

@@ -34,14 +34,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-source_parsers = {
-    '.md': CommonMarkParser
-}
+#source_parsers = {
+#    '.md': CommonMarkParser
+#}
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:

docs/configuring.md

@@ -38,7 +38,9 @@ It is also possible to use your own custom arguments in the validation message.
 
 ```csharp
 //Using static values in a custom message:
-RuleFor(customer => x.Surname).NotNull().WithMessage(customer => string.Format("This message references some constant values: {0} {1}", "hello", 5));
+RuleFor(customer => x.Surname)
+  .NotNull()
+  .WithMessage(customer => string.Format("This message references some constant values: {0} {1}", "hello", 5))
 //Result would be "This message references some constant values: hello 5"
 
 //Referencing other property values:
@@ -81,13 +83,4 @@ ValidatorOptions.DisplayNameResolver = (type, member, expression) => {
 };
 ```
 
-This is not a realistic example as it changes all properties to have the suffix "Foo", but hopefully illustrates the point.
-
-Additionally, FluentValidation will respect the use of the DisplayName and Display attributes for generating the property's name within error messages:
-
-```csharp
-public class Person {
-  [Display(Name="Last name")]
-  public string Surname { get; set; }
-}
-```
+This is not a realistic example as it changes all properties to have the suffix "Foo", but hopefully illustrates the point.

docs/custom-state.md

@@ -0,0 +1,33 @@
+# Custom State
+
+There may be an occasion where you'd like to return contextual information about the state of your validation rule when it was run. The `WithCustomState` method allows you to associate any custom data with the validation results.
+
+We could assign a custom state by modifying a line to read:
+
+```csharp
+public class PersonValidator : AbstractValidator<Person> {
+  public PersonValidator() {
+    RuleFor(person => person.Surname).NotNull();
+    RuleFor(person => person.Forename).NotNull().WithState(person => 1234);  
+  }
+}
+```
+
+This state is then available within the `CustomState` property of the `ValidationFailure`.
+
+```csharp
+var validator = new PersonValidator();
+var result = validator.Validate(new Person());
+foreach (var failure in result.Errors) {
+  Console.WriteLine($"Property: {failure.PropertyName} State: {failure.CustomState}");
+}
+```
+
+The output would be:
+
+```
+Property: Surname State:
+Property: Forename State: 1234
+```
+
+By default the `CustomState` property will be `null` if `WithState` hasn't been called.

docs/custom-validators.md

@@ -1,6 +1,6 @@
 # Custom Validators
 
-There are several ways to create a custom, reusable validator. The recommended way is to make use of the [Predicate Validator](/built-in-validators.html#predicate-validator) to write a custom validation function, but you can also write a custom implementation of the PropertyValidator class.
+There are several ways to create a custom, reusable validator. The recommended way is to make use of the [Predicate Validator](built-in-validators.html#predicate-validator) to write a custom validation function, but you can also write a custom implementation of the PropertyValidator class.
 
 For these examples, we'll imagine a scenario where you want to create a reusable validator that will ensure a List object contains fewer than 10 items.
 

docs/error-codes.md

@@ -0,0 +1,38 @@
+# Custom Error Codes
+
+A custom error code can also be associated with validation rules by calling the `WithErrorCode` method:
+
+```csharp
+public class PersonValidator : AbstractValidator<Person> {
+  public PersonValidator() {
+    RuleFor(person => person.Surname).NotNull().WithErrorCode("ERR1234");        
+    RuleFor(person => person.Forename).NotNull();
+  }
+}
+```
+
+The resulting error code can be obtained from the `ErrorCode` property on the `ValidationFailure`:
+
+```csharp
+var validator = new PersonValidator();
+var result = validator.Validate(new Person());
+foreach (var failure in result.Errors) {
+  Console.WriteLine($"Property: {failure.PropertyName} Error Code: {failure.ErrorCode}");
+}
+```
+
+The output would be:
+
+```
+Property: Surname Error Code: ERR1234
+Property: Forename Error Code: NotNullValidator
+```
+
+## ErrorCode and Error Messages
+
+The `ErrorCode` is also used to determine the default error message for a particular validator. At a high level:
+
+* The error code is used as the lookup key for an error message. For example, a `NotNull()` validator has a default error code of `NotNullValidator`, which used to look up the error messages from the `LanguageManager`. [See the documentation on localization.](localization)
+* If you provide an error code, you could also provide a localized message with the name of that error code to create a custom message.
+* If you provide an error code but no custom message, the message will fall back to the default message for that validator. You're not required to add a custom message.
+* Using `ErrorCode` can also be used to override the default error message. For example, if you use a custom `Must()` validator, but you'd like to reuse the `NotNull()` validator's default error message, you can call `WithErrorCode("NotNullValidator")` to achieve this result.

docs/index.rst

@@ -14,7 +14,7 @@ The following platforms are supported:
 * .NET Core 2.0+
 * `.NET Standard 2.0+ <https://docs.microsoft.com/en-us/dotnet/standard/net-standard>`_
 
-For automatic validation with ASP.NET, FluentValidation supports ASP.NET Core 2.1+ (3.1 recommended)
+For automatic validation with ASP.NET, FluentValidation supports ASP.NET Core 2.1 and 3.1.
 
 If you're new to using FluentValidation, check out the :doc:`start` page.
 
@@ -44,7 +44,7 @@ Example
   :caption: Getting Started
 
   installation
-  start 
+  start
   collections
   rulesets
   including-rules
@@ -58,7 +58,9 @@ Example
 
   configuring
   conditions
-
+  severity
+  error-codes
+  custom-state
 
 .. _validator-docs:
 .. toctree::
@@ -85,12 +87,12 @@ Example
 .. _aspnet-docs:
 .. toctree::
   :maxdepth: 1
-  :caption: ASP.NET Integration 
+  :caption: ASP.NET Integration
 
   aspnet
   mvc5
   webapi
-  
+
 .. _advanced-docs:
 .. toctree::
   :maxdepth: 1

docs/installation.md

@@ -21,8 +21,14 @@ Or using the .net core CLI from a terminal window:
 dotnet add package FluentValidation
 ```
 
-For integration with ASP.NET Core, install the FluentValidation.AspNetCore package:
+For integration with ASP.NET Core, install the FluentValidation.AspNetCore package from Visual Studio:
 
 ```shell
 Install-Package FluentValidation.AspNetCore
+```
+
+or from the command line:
+
+```shell
+dotnet add package FluentValidation.AspNetCore
 ```