Qowaiv is a (Single) Value Object library. It aims to model reusable (Single) Value Objects that can be used a wide variety of modeling scenarios, both inside and outside a Domain-driven context.
Supported scenarios include parsing, formatting, validation, (de)serialization, and domain specific logic.
A Value Object that can be represented by a single scalar.
Because we use .NET standard to support both .NET 4.5 (and higher) as .NET Core (2.0) the Visual Studio solution file requires VS2017.3 or higher. Visual Studio can be downloaded here: visualstudio.com/downloads.
Represents a date, so without hours (minutes, seconds, milliseconds).
Represents an Elo (rating), a method for calculating the relative skill levels of players in competitor-versus-competitor games.
Represents a (single) email address, including IPv4 domains.
Represents a collection of unique email addresses, excluding the empty and unknown email address.
Represents the size of a file or stream.
Represents a gender based on an ISO 5218 code.
Represents a house number in the range [1-999999999].
Explicitly marked local date time. It allows the clear distinction between local and UTC-based date times.
Represents a month in the range [1-12].
Represents a percentage/per mile/per ten thousand.
Represents a postal code. It supports validation for all countries.
The UUID (Universally unique identifier) aka GUID (Globally unique identifier) is an extension on the System.Guid. It is by default represented by a 22 length string, instead of a 32 length string.
Represents a week based date.
Represents a year in the range [1-9999].
A seed, representing random data to encrypt and decrypt data.
Represents money without the notion of the actual currency.
Represents a BIC as specified in ISO 13616.
Represents a currency based on an ISO 4217 code.
Represents an IBAN as specified in ISO 13616.
Represents the amount and the currency. Technically this is not SVO. However it acts identically as a SVO.
Represents a country based on an ISO 3166-1 code (or 3166-3 if the country does not longer exists).
Represents a (MS SQL) time-stamp is a data type that exposes automatically generated binary numbers, which are guaranteed to be unique within a database. time-stamp is used typically as a mechanism for version-stamping table rows. The storage size is 8 bytes. See: https://technet.microsoft.com/en-us/library/aa260631%28v=sql.80%29.aspx
To create a (SQL) parameter with a SVO as value, use the SvoParamater factory class. It will return SQL parameter with a converted database proof value.
Represents an Internet media type (also known as MIME-type and content type).
Represents a pattern to match strings, using wildcard characters ? and *. It also support the use of SQL wildcard characters _ and %.
Guard parameters, for centralizing and simplifying the argument checking.
During debugging sessions, by default, the IDE shows the result of ToString() on a watch. Although Tostring() is overridden for all Qowaiv Single Value Objects, for debugging a special debugger display is provided too, using a debugger display attribute.
The debugger display attribute refers to (private) property with the name "DebuggerDisplay", which represents the Single Value Object as string. If supported, formatted, and in case of a Empty or Unknown value with a notification of that too. The outcome of the DebuggerDisplay is tested in the UnitTests.
Because the rendering of debugger display is handled based on the development environment, and methods as debugger display are not supported by VB.NET, the debugger display attribute refers to a property instead.
Formatting is an important part of the functionality in Qowaiv. All SVO's implement IFormattable, and have custom formatting. For details, see the different remarks at the ToString(string, IFormatProvider).
The formatting arguments object, is a container object (struct) of the format and the format provider, the two arguments required for the System.Iformatable ToString() method.
This collection of formatting arguments stores them based on a type to apply on. On top of that, it has a Format() method, that is an extended implementation of string.Format(). The difference between these two methods is, that - when no custom format is supplied at the format string - string.Format() the default formatting of the object is used, where FormattingArgumentsCollection.Format() uses the default specified at the formatting collection of a type (if available).
Because there are scenario's where you want to set typical values as a country or a currency for the context of the current thread (like the culture info) there is a possibility to add these to the Qowaiv.Threading.ThreadDomain.
These values can be configured (in the application settings) or can be created with a creator function that can be registered. If not specified otherwise the current country will be created (if possible) based on the current culture.
We're extending the DataAnnotations from Microsoft with some more attributes:
- [Mandatory] Here the difference with Microsoft's [Required] attribute is that it works for value types as well, it will be invalid if the default value is used.
- [AllowedValues] and
- [ForbiddenValues] make it easy to validate string values, or objects/value types that have a string representation.
Also we propose a Result model that includes the validation messages, and Result which can contain both an object and validation messages. This can be a helpful return type for methods that need to return objects but first have to validate them.
The difference with Microsoft's default ValidationResult and ValidationMessages is that in this PR we support a severity: info, warning, or error.