After loading configuration into strongly typed POCO classes (e.g. IOptions), this package allows to extend these classes
with validation routines to make sure loaded data is correct during runtime.
Built in e-mail, URL, IP address, string and numeric value validators along with generic and custom validation possibility.
Provides means to validate strongly typed configuration class properties on common types (IP address, URL, e-mail address, numbers and strings) of configuration values being valid.
Validation for configuration objects are performed entirely for all class properties (does not throw exception on first failure). Handling validation outcome is upon application business logic. There is special exception type provided, if throwing exception is required.
Package is very lightweight, targeting .Net Standard 2.0 (works with .Net Framework 4.7.2+ and .Net Core 2+) and does not have any other external dependencies.
Usage
Configuration validation works with strongly typed POCO classes where entire configuration or configuration sections (several configuration classes) are loaded from configuration files (json/xml/yaml/whatever) or environment variables into these class objects.
Imagine you have this POCO class, holding configuration values, loaded from some configuration files (e.g. Microsoft.Extensions.Configuration.* IOptions usage).
public class SampleConfig
{
// Here are properties of configuration values, filled from some configuration.
public int SomeValue { get; set; }
public short SomeShortValue { get; set; }
public long SomeLongValue { get; set; }
public string SomeName { get; set; }
public string SomeEndpoint { get; set; }
public string SomeEmail { get; set; }
public string SomeIp { get; set; }
}
To add validation for loaded values during runtime, you have to slightly extend these classes - they should implement IValidatableConfiguration interface, which demands only IEnumerable<ConfigurationValidationItem> Validate(); method to be added for this class. This method then performs validations, collects them and returns all found misconfigurations in a collection of ConfigurationValidationItems.
Package contains helper class ConfigurationValidationCollector, which can considerably ease performing such validations and collecting outcome.
Here is sample of such strongly typed configuration/section class after modifications:
public class SampleConfig : IValidatableConfiguration
{
// Here are properties of configuration values, filled from some configuration.
public int SomeValue { get; set; }
public short SomeShortValue { get; set; }
public long SomeLongValue { get; set; }
public string SomeName { get; set; }
public string SomeEndpoint { get; set; }
public string SomeEmail { get; set; }
public string SomeIp { get; set; }
/// <summary>
/// Performs the validation of this configuration object.
/// Returns empty list if no problems found, otherwise list contains validation problems.
/// </summary>
public IEnumerable<ConfigurationValidationItem> Validate()
{
// Helper to collect and perform validations
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
// Here are validations
validations.ValidateNotZero(c => c.SomeValue, "Configuration should not contain default value (=0).");
validations.ValidateNotNullOrEmpty(c => c.SomeName, "Configuration should specify value for Name.");
validations.ValidateUri(c => c.SomeEndpoint, "External API endpoint is incorrect");
validations.ValidateEmail(c => c.SomeEmail, "E-mail address is wrong.");
validations.ValidateIpV4Address(c => c.SomeIp, "IP address is not valid.");
validations.ValidatePublicIpV4Address(c => c.SomeIp, "IP address is not a public IP address.");
// Generic methods, expecting boolean outcome of Linq expression
validations.ValidateMust(c => c.SomeEndpoint.StartsWith("https", StringComparison.OrdinalIgnoreCase), nameof(this.SomeEndpoint), "Enpoint is no SSL secured.");
validations.ValidateMust(c => c.SomeEndpoint.EndsWith("/", StringComparison.OrdinalIgnoreCase), nameof(this.SomeEndpoint), "Enpoint should end with shash /.");
validations.ValidateMust(c =>
c.SomeName.Contains("sparta", StringComparison.OrdinalIgnoreCase)
&& c.SomeValue > 10,
$"{nameof(this.SomeName)} and {nameof(this.SomeValue)}",
"Combined validations failed.");
// Syntactic sugar
validations.ValidateStartsWith(c => c.SomeEndpoint, "https", "Enpoint is no SSL secured.");
validations.ValidateEndsWith(c => c.SomeEndpoint, "/", "Enpoint should end in slash character.");
// Returning all found validation problems
return validations.Result;
}
}
as shown on example - helper class contains many ready-made routines to validate class properties for some widely used configuration value correctness.
Usage in console (simple) app
Samples folder contains an example of usage of this functionality in Console application.
Here I omit code on how to load configuration into strongly typed object sampleConfig (see Sample project on usage of Microsoft.Extensions.Configuration for this purpose).
var validations = sampleConfig.Validate().ToList();
if (validations.Count == 0)
{
// All is fine
}
if validation method returned some validations, this means there are problems in configured values and they can be enumerated to handle:
throw new ConfigurationValidationException("Configuration is incorrect.", validations);
and then handle its property ex.ValidationData in some general exception handler.
Using interface on configuration with IoC container allows to do some magic of finding all these classes and performing validations in centralized manner.
Usage in AspNetCore Web API/app
In ASP.NET Core you can act on configuration validation results in several ways, starting from preventing app startup with IStartupFilter and least intrusive - as HealthCheck.
Three approaches are shown in another repository Sample project: Salix.AspNetCore.Utilities and are briefly described below.
Registering validatable configurations with IoC
First register all your strongly typed configuration class objects with IoC (services):
// With configuration as IOptions
services.Configure<SampleConfig>(_configuration.GetSection("SampleConfig"));
// As normal singleton instance for injection
services.AddSingleton(ctx => ctx.GetRequiredService<IOptions<SampleConfig>>().Value);
// As IValidatableConfiguration instance for "automatic" validations
services.AddSingleton<IValidatableConfiguration>(ctx => ctx.GetRequiredService<IOptions<SampleConfig>>().Value);
IStartupFilter
This is most invasive approach as there are no apparent visible display for reasons of application "crash" during startup.
Create class, implementing IStartupFilter, which takes all IValidatableConfiguration instances, validates them and throws exception if any misconfigurations are found.
public class ConfigurationValidationStartupFilter : IStartupFilter
{
private readonly IEnumerable<IValidatableConfiguration> _cfgs;
// Constructor gets injected all instances of validatable condifuration objects
public ConfigurationValidationStartupFilter(IEnumerable<IValidatableConfiguration> cfgs)
=> _cfgs = cfgs;
public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
{
var fails = new List<ConfigurationValidationItem>();
foreach (IValidatableConfiguration cfg in _cfgs)
{
// Runs Validation on all instances and collects outcomes
fails.AddRange(cfg.Validate());
}
if (fails.Count > 0)
{
// If any found - throws special exception
throw new ConfigurationValidationException("There are issues with configuration.", fails);
}
return next;
}
}
Then register this filter as well in Startup ConfigureServices method.
Upon Asp.Net Core application startup - this filter will be invoked and will end up in application "crash". You will have to dig up reasons for crash via application monitoring and environment logs.
Less intrusive approach as it allows you to get some visible response from your application when changes are deployed. Application itself will not work, but you will get whatever you set to return in this middleware component.
It is quite similar to Developer Error page, you can create something, which returns HTML contents to requesting party (e.g. browser) via this middleware component.
It is quite a code sample to be shown here. See example in Salix.AspNetCore.Utilities repository (or use it :-) ).
In essence you should do the same as in IStartupFilter implementation above, just in case of validations - change Response to some information, invoke its WriteAsync with content and do not call await next.
HealthCheck
Standard approach with Microsoft.Extensions.Diagnostics.HealthChecks package implementation.
This is least intrusive approach and will not prevent your application from starting up (unless misconfiguration itself prevents it).
As with middleware - see example for such HealthCheck in Salix.AspNetCore.Utilities repository (or use it :-) ).
When using HealthCheck-ing approach - make sure you actually check the health of your app deployment with it.
Provided validations
There are number of ready-made validations provided for values in your configuration objects as methods on ConfigurationValidationCollector class.
ValidateNotNullOrEmpty
For string configuration properties this is simple validation to check whether value is not NULL or empty string.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateNotNullOrEmpty(c => c.Property, "Validation failed message.");
ValidateContains
For string configuration properties this validates whether configured value contains given string as part of it. Validation is case insensitive and uses current Culture set in application.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateContains(c => c.Property, "mydomain", "Validation failed message.");
ValidateStartsWith
For string configuration properties this validates whether configured value starts with given string. Validation is case insensitive and uses current Culture set in application.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateStartsWith(c => c.Property, "https", "API endpoint should be SSL secured.");
ValidateEndsWith
For string configuration properties this validates whether configured value ends with given string. Validation is case insensitive and uses current Culture set in application.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateEndsWith(c => c.Property, "/", "API endpoint should end in slash /.");
ValidateNotZero
For short, integer and long configuration properties this validates whether configured value is not zero (0).
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateNotZero(c => c.Property, "Validation failed message.");
ValidateEmail
For string configuration values this will check whether configuration property contains valid e-mail address. It does not check whether such address really exists, just validates if it is in correct e-mail address format.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateEmail(c => c.Property, "Not correct e-mail address.");
ValidateUri
For string configuration values this will check whether configuration property contains absolute internet address (with protocol). Example: https://data.organization.com/api
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateUri(c => c.Property, "Not correct API address.");
ValidateIpV4Address
For string configuration values this will check whether configuration property contains correct IP address. Example: 182.23.1.0
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateIpV4Address(c => c.Property, "Not correct IP address.");
ValidatePublicIpV4Address
For string configuration values in addition to checking whether value is correct IP address, it will also check whether it belongs to public IP address range (not internal address ranges 10.0.0.0/8; 192.168.0.0/16; 172.16.0.0/12).
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidatePublicIpV4Address(c => c.Property, "Should not be internal IP address.");
ValidatePrivateIpV4Address
For string configuration values in addition to checking whether value is correct IP address, it will also check whether it belongs to private IP address range (10.0.0.0/8; 192.168.0.0/16; 172.16.0.0/12).
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidatePrivateIpV4Address(c => c.Property, "Should not be internal IP address.");
ValidateMust
For one or more configuration values will allow to supply custom validation as Linq expression resulting into boolean value.
Second parameter should contain name(s) of configuration class properties, which are responsible for failing this validation.
var validations = new ConfigurationValidationCollector<SampleConfig>(this);
validations.ValidateMust(c => c.Property1 > 2000 && c.Property2 == "year", "Property1&2", "Combined validation failed.");