Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/altasoft/DomainPrimitives
C# Domain Primitives generator
https://github.com/altasoft/DomainPrimitives
ddd domain dotnet dotnet-core entity primitive-types source-generators strongly-typed value-object
Last synced: 3 months ago
JSON representation
C# Domain Primitives generator
- Host: GitHub
- URL: https://github.com/altasoft/DomainPrimitives
- Owner: altasoft
- License: mit
- Created: 2024-01-09T11:36:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-06-19T07:50:38.000Z (5 months ago)
- Last Synced: 2024-07-20T04:39:45.804Z (4 months ago)
- Topics: ddd, domain, dotnet, dotnet-core, entity, primitive-types, source-generators, strongly-typed, value-object
- Language: C#
- Homepage:
- Size: 2.99 MB
- Stars: 51
- Watchers: 7
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- RSCG_Examples - https://github.com/altasoft/DomainPrimitives
- csharp-source-generators - AltaSoft.DomainPrimitives -   - A C# toolkit purposefully designed to accelerate the development of domain-specific primitives within your applications. This streamlined solution empowers developers to efficiently encapsulate fundamental domain logic. Through this toolkit, you'll significantly reduce code complexity while improving the maintainability of your project. (Source Generators / Domain Driven Design (DDD))
README
# DomainPrimitives for C#
[](https://www.nuget.org/profiles/AltaSoft)
[](https://dotnet.microsoft.com)
# Table of Contents
- [Introduction](#introduction)
- [Key Features](#key-features)
- [Generator Features](#generator-features)
- [Supported Underlying types](#supported-underlying-types)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Creating your Domain type](#creating-your-domain-type)
- [Json Conversion](#json-conversion)
- [Contributions](#contributions)
- [Contact](#contact)
- [License](#license)
## Introduction
Welcome to **AltaSoft.DomainPrimitives** - a C# toolkit purposefully designed to accelerate the development of domain-specific primitives within your applications. This streamlined solution empowers developers to efficiently encapsulate fundamental domain logic. Through this toolkit, you'll significantly reduce code complexity while improving the maintainability of your project.
## Key Features
* **Simplified Primitive Creation** - Utilize source generators to swiftly create domain-specific primitives with ease and precision.
* **Versatile Underlying Type Support** - Embrace a wide array of underlying types, catering to diverse application requirements.
* **Enhanced Code Quality** - Create clean, maintainable, and thoroughly testable code through encapsulation and robust design principles.
With `AltaSoft.DomainPrimitives`, experience an accelerated development process while upholding code quality standards. This toolkit empowers developers to focus on the core business logic without compromising on precision or efficiency.
## Generator Features
The **AltaSoft.DomainPrimitives.Generator** offers a diverse set of features:
* **Implicit Operators:** Streamlines type conversion to/from the underlying primitive type. [Example](#implicit-usage-of-domaintype)
* **Specialized Constructor Generation:** Automatically validates and constructs instances of this domain type. This constructor, tailored for the domain primitive, utilizes the underlying type as a parameter, ensuring the value's correctness within the domain.
* **TryCreate method:** Introduces a TryCreate method that attempts to create an instance of the domain type and returns a bool indicating the success or failure of the creation process, along with any validation errors.
* **JsonConverters:** Handles JSON serialization and deserialization for the underlying type. [Example](#json-conversion)
* **TypeConverters:** Assists in type conversion to/from it's underlying type. [Please refer to generated type converter below](#type-converter)
* **Swagger Custom Type Mappings:** Facilitates easy integration with Swagger by treating the primitive type as it's underlying type. [Please refer to generated swagger helper below](#swagger-mappers)
* **Interface Implementations:** All DomainPritmitives Implement `IConvertible`, `IComparable`, `IComparable`, `IEquatable`, `IEqualityComparer`, `IParsable` interfaces.
* **NumberType Operations:** Automatically generates basic arithmetic and comparison operators, by implementing Static abstract interfaces. [More details regarding numeric types](#number-types-attribute)
* **IParsable Implementation:** Automatically generates parsing for non-string types.
* **XML Serialiaziton** Generates IXmlSerializable interface implementation, to serialize and deserialize from/to xml.
* **EntityFrameworkCore ValueConverters** Facilitates seamless integration with EntityFrameworkCore by using ValueConverters to treat the primitive type as its underlying type. For more details, refer to [EntityFrameworkCore ValueConverters](EntityFrameworkCoreExample.md)
## Supported Underlying types
1. `string`
2. `Guid`
3. `byte`
4. `sbyte`
5. `short`
6. `ushort`
7. `int`
8. `uint`
9. `long`
10. `ulong`
11. `decimal`
12. `double`
13. `float`
14. `bool`
15. `char`
16. `TimeSpan`
17. `DateTime`
18. `DateTimeOffset`
19. `DateOnly`
20. `TimeOnly`
## Getting Started
### Prerequisites
* .NET 7 or higher
* NuGet Package Manager
### Installation
To use **AltaSoft.DomainPrimitives**, install two NuGet packages:
1. `AltaSoft.DomainPrimitives`
2. `AltaSoft.DomainPrimitives.Generator`
In your project file add references as follows:
```xml
```
## **Creating your Domain type**
For optimal performance, it is recommended to use `readonly struct`, especially when wrapping value types. If the type is a `reference` type, consider using `class` over `struct`.
```csharp
public readonly partial struct PositiveInteger : IDomainValue
{
///
public static PrimitiveValidationResult Validate(int value)
{
if (value <= 0)
return PrimitiveValidationResult.Error("value is non-positive");
return PrimitiveValidationResult.Ok;
}
}
```
This will automatically generate by default 4 classes
## **PositiveInteger.Generated**
```csharp
//------------------------------------------------------------------------------
//
// This code was generated by 'AltaSoft DomainPrimitives Generator'.
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
//
//------------------------------------------------------------------------------
#nullable enable
using System;
using System.Numerics;
using System.Diagnostics;
using System.Runtime.CompilerServices;
using AltaSoft.DomainPrimitives;
using System.Diagnostics.CodeAnalysis;
using System.Text.Json.Serialization;
using AltaSoft.DomainPrimitives.XmlDataTypes.Converters;
using System.ComponentModel;
using System.Xml;
using System.Xml.Schema;
using System.Xml.Serialization;
namespace AltaSoft.DomainPrimitives.XmlDataTypes;
[JsonConverter(typeof(PositiveIntegerJsonConverter))]
[TypeConverter(typeof(PositiveIntegerTypeConverter))]
[UnderlyingPrimitiveType(typeof(int))]
[DebuggerDisplay("{_value}")]
public readonly partial struct PositiveInteger : IEquatable
, IComparable
, IComparable
, IAdditionOperators
, ISubtractionOperators
, IMultiplyOperators
, IDivisionOperators
, IModulusOperators
, IComparisonOperators
, IParsable
, IConvertible
, IXmlSerializable
#if NET8_0_OR_GREATER
, IUtf8SpanFormattable
#endif
{
///
public Type GetUnderlyingPrimitiveType() => typeof(int);
///
public object GetUnderlyingPrimitiveValue() => (int)this;
private int _valueOrThrow => _isInitialized ? _value : throw new InvalidDomainValueException("The domain value has not been initialized", this);
[DebuggerBrowsable(DebuggerBrowsableState.Never)]
private readonly int _value;
[DebuggerBrowsable(DebuggerBrowsableState.Never)]
private readonly bool _isInitialized;
///
/// Initializes a new instance of the class by validating the specified value using static method.
///
/// The value to be validated.
public PositiveInteger(int value) : this(value, true)
{
}
private PositiveInteger(int value, bool validate)
{
if (validate)
{
ValidateOrThrow(value);
}
_value = value;
_isInitialized = true;
}
///
[Obsolete("Domain primitive cannot be created using empty Constructor", true)]
public PositiveInteger()
{
}
///
/// Tries to create an instance of AsciiString from the specified value.
///
/// The value to create PositiveInteger from
/// When this method returns, contains the created PositiveInteger if the conversion succeeded, or null if the conversion failed.
/// true if the conversion succeeded; otherwise, false.
public static bool TryCreate(int value, [NotNullWhen(true)] out PositiveInteger? result)
{
return TryCreate(value, out result, out _);
}
///
/// Tries to create an instance of AsciiString from the specified value.
///
/// The value to create PositiveInteger from
/// When this method returns, contains the created PositiveInteger if the conversion succeeded, or null if the conversion failed.
/// When this method returns, contains the error message if the conversion failed; otherwise, null.
/// true if the conversion succeeded; otherwise, false.
public static bool TryCreate(int value,[NotNullWhen(true)] out PositiveInteger? result, [NotNullWhen(false)] out string? errorMessage)
{
var validationResult = Validate(value);
if (!validationResult.IsValid)
{
result = null;
errorMessage = validationResult.ErrorMessage;
return false;
}
result = new (value, false);
errorMessage = null;
return true;
}
///
/// Validates the specified value and throws an exception if it is not valid.
///
/// The value to validate
/// Thrown when the value is not valid.
public void ValidateOrThrow(int value)
{
var result = Validate(value);
if (!result.IsValid)
throw new InvalidDomainValueException(result.ErrorMessage, this);
}
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public override bool Equals(object? obj) => obj is PositiveInteger other && Equals(other);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public bool Equals(PositiveInteger other)
{
if (!_isInitialized || !other._isInitialized)
return false;
return _value.Equals(other._value);
}
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator ==(PositiveInteger left, PositiveInteger right) => left.Equals(right);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator !=(PositiveInteger left, PositiveInteger right) => !(left == right);
///
public int CompareTo(object? obj)
{
if (obj is null)
return 1;
if (obj is PositiveInteger c)
return CompareTo(c);
throw new ArgumentException("Object is not a PositiveInteger", nameof(obj));
}
///
public int CompareTo(PositiveInteger other)
{
if (!other._isInitialized)
return 1;
if (!_isInitialized)
return -1;
return _value.CompareTo(other._value);
}
///
/// Implicit conversion from to
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static implicit operator PositiveInteger(int value) => new(value);
///
/// Implicit conversion from (nullable) to (nullable)
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
[return: NotNullIfNotNull(nameof(value))]
public static implicit operator PositiveInteger?(int? value) => value is null ? null : new(value.Value);
///
/// Implicit conversion from to
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static implicit operator int(PositiveInteger value) => (int)value._valueOrThrow;
///
/// Implicit conversion from (nullable) to (nullable)
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
[return: NotNullIfNotNull(nameof(value))]
public static implicit operator int?(PositiveInteger? value) => value is null ? null : (int?)value.Value._valueOrThrow;
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger operator +(PositiveInteger left, PositiveInteger right) => new(left._valueOrThrow + right._valueOrThrow);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger operator -(PositiveInteger left, PositiveInteger right) => new(left._valueOrThrow - right._valueOrThrow);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger operator *(PositiveInteger left, PositiveInteger right) => new(left._valueOrThrow * right._valueOrThrow);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger operator /(PositiveInteger left, PositiveInteger right) => new(left._valueOrThrow / right._valueOrThrow);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger operator %(PositiveInteger left, PositiveInteger right) => new(left._valueOrThrow % right._valueOrThrow);
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator <(PositiveInteger left, PositiveInteger right) => left._valueOrThrow < right._valueOrThrow;
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator <=(PositiveInteger left, PositiveInteger right) => left._valueOrThrow <= right._valueOrThrow;
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator >(PositiveInteger left, PositiveInteger right) => left._valueOrThrow > right._valueOrThrow;
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator >=(PositiveInteger left, PositiveInteger right) => left._valueOrThrow >= right._valueOrThrow;
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static PositiveInteger Parse(string s, IFormatProvider? provider) => int.Parse(s, provider);
///
public static bool TryParse([NotNullWhen(true)] string? s, IFormatProvider? provider, [MaybeNullWhen(false)] out PositiveInteger result)
{
if (!int.TryParse(s, provider, out var value))
{
result = default;
return false;
}
if (TryCreate(value, out var created))
{
result = created.Value;
return true;
}
result = default;
return false;
}
#if NET8_0_OR_GREATER
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public bool TryFormat(Span utf8Destination, out int bytesWritten, ReadOnlySpan format, IFormatProvider? provider)
{
return ((IUtf8SpanFormattable)_valueOrThrow).TryFormat(utf8Destination, out bytesWritten, format, provider);
}
#endif
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public override int GetHashCode() => _valueOrThrow.GetHashCode();
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
TypeCode IConvertible.GetTypeCode() => ((IConvertible)(Int32)_valueOrThrow).GetTypeCode();
///
bool IConvertible.ToBoolean(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToBoolean(provider);
///
byte IConvertible.ToByte(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToByte(provider);
///
char IConvertible.ToChar(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToChar(provider);
///
DateTime IConvertible.ToDateTime(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToDateTime(provider);
///
decimal IConvertible.ToDecimal(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToDecimal(provider);
///
double IConvertible.ToDouble(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToDouble(provider);
///
short IConvertible.ToInt16(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToInt16(provider);
///
int IConvertible.ToInt32(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToInt32(provider);
///
long IConvertible.ToInt64(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToInt64(provider);
///
sbyte IConvertible.ToSByte(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToSByte(provider);
///
float IConvertible.ToSingle(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToSingle(provider);
///
string IConvertible.ToString(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToString(provider);
///
object IConvertible.ToType(Type conversionType, IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToType(conversionType, provider);
///
ushort IConvertible.ToUInt16(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToUInt16(provider);
///
uint IConvertible.ToUInt32(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToUInt32(provider);
///
ulong IConvertible.ToUInt64(IFormatProvider? provider) => ((IConvertible)(Int32)_valueOrThrow).ToUInt64(provider);
///
public XmlSchema? GetSchema() => null;
///
public void ReadXml(XmlReader reader)
{
var value = reader.ReadElementContentAs();
ValidateOrThrow(value);
System.Runtime.CompilerServices.Unsafe.AsRef(in _value) = value;
System.Runtime.CompilerServices.Unsafe.AsRef(in _isInitialized) = true;
}
///
public void WriteXml(XmlWriter writer) => writer.WriteValue(((int)_valueOrThrow).ToXmlString());
///
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public override string ToString() => _valueOrThrow.ToString();
}
```
## **JsonConverter**
```csharp
//------------------------------------------------------------------------------
//
// This code was generated by 'AltaSoft DomainPrimitives Generator'.
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
//
//------------------------------------------------------------------------------
#nullable enable
using AltaSoft.DomainPrimitives;
using System;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Globalization;
using System.Text.Json.Serialization.Metadata;
namespace AltaSoft.DomainPrimitives.Converters;
///
/// JsonConverter for
///
public sealed class PositiveIntegerJsonConverter : JsonConverter
{
///
public override PositiveInteger Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
try
{
return JsonInternalConverters.Int32Converter.Read(ref reader, typeToConvert, options);
}
catch (InvalidDomainValueException ex)
{
throw new JsonException(ex.Message);
}
}
///
public override void Write(Utf8JsonWriter writer, PositiveInteger value, JsonSerializerOptions options)
{
JsonInternalConverters.Int32Converter.Write(writer, (int)value, options);
}
///
public override PositiveInteger ReadAsPropertyName(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
try
{
return JsonInternalConverters.Int32Converter.ReadAsPropertyName(ref reader, typeToConvert, options);
}
catch (InvalidDomainValueException ex)
{
throw new JsonException(ex.Message);
}
}
///
public override void WriteAsPropertyName(Utf8JsonWriter writer, PositiveInteger value, JsonSerializerOptions options)
{
JsonInternalConverters.Int32Converter.WriteAsPropertyName(writer, (int)value, options);
}
}
```
## **Type Converter**
```csharp
//------------------------------------------------------------------------------
//
// This code was generated by 'AltaSoft DomainPrimitives Generator'.
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
//
//------------------------------------------------------------------------------
#nullable enable
using AltaSoft.DomainPrimitives;
using System;
using System.ComponentModel;
using System.Globalization;
namespace AltaSoft.DomainPrimitives.Converters;
///
/// TypeConverter for
///
public sealed class PositiveIntegerTypeConverter : Int32Converter
{
///
public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
{
var result = base.ConvertFrom(context, culture, value);
if (result is null)
return null;
try
{
return new PositiveInteger((int)result);
}
catch (InvalidDomainValueException ex)
{
throw new FormatException("Cannot parse PositiveInteger", ex);
}
}
}
```
## **Swagger Mappers**
A single file for all domainPrimitives containing all type mappings is generated.
```csharp
//------------------------------------------------------------------------------
//
// This code was generated by 'AltaSoft DomainPrimitives Generator'.
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
//
//------------------------------------------------------------------------------
#nullable enable
using AltaSoft.DomainPrimitives;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;
namespace AltaSoft.DomainPrimitives.Converters.Extensions;
///
/// Helper class providing methods to configure Swagger mappings for DomainPrimitive types of AltaSoft.DomainPrimitives
///
public static class SwaggerTypeHelper
{
///
/// Adds Swagger mappings for specific custom types to ensure proper OpenAPI documentation generation.
///
/// The SwaggerGenOptions instance to which mappings are added.
///
/// The method adds Swagger mappings for the following types:
///
///
public static void AddSwaggerMappings(this SwaggerGenOptions options)
{
options.MapType(() => new OpenApiSchema
{
Type = "integer",
Format = "int32",
Title = "PositiveInteger",
Description = @"A domain primitive type representing a positive integer."
});
options.MapType(() => new OpenApiSchema
{
Type = "integer",
Format = "int32",
Nullable = true,
Title = "Nullable",
Description = @"A domain primitive type representing a positive integer."
});
}
```
## Specialized ToString method
By Default IDomainValue uses its underlying type's ToString method however this can be overriden by implementing a method specified below
```csharp
static virtual string ToString(T value) => value.ToString() ?? string.Empty;
```
## Managing Generated Operators for numeric types
Mathematical operators for particular numeric types can be customized using the `SupportedOperationsAttribute`. If left unspecified, all operators are generated by default (as shown below). Once this attribute is applied, manual specification of the operators becomes mandatory. Note that for `byte`, `sbyte`, `short`, and `ushort` types, mathematical operators will not be generated by default.
### Default numeric types Generated Operators
1. `byte, sbyte` => `None`
2. `short, ushort` => `None`
3. `int, uint` => `+ - / * %`
3. `long, ulong` => `+ - / * %`
3. `double` => `+ - / * %`
3. `decimal` => `+ - / * %`
### using `SupportedOperationsAttribute`
```csharp
[SupportedOperations(Addition = false, Division = false, Modulus = false, Multiplication = true, Subtraction = true)]
public readonly partial struct PositiveInteger : IDomainValue
{
///
public static PrimitiveValidationResult Validate(int value)
{
if (value <= 0)
return PrimitiveValidationResult.Error("value is non-positive");
return PrimitiveValidationResult.Ok;
}
}
```
### For further customization of the operators, consider implementing specific interfaces. This action will override the generated operators for the respective domain type:
```csharp
public readonly partial struct PositiveInteger :
IDomainValue,
IAdditionOperators
{
///
public static PrimitiveValidationResult Validate(int value)
{
if (value <= 0)
return PrimitiveValidationResult.Error("value is non-positive");
return PrimitiveValidationResult.Ok;
}
// custom + operator
public static PositiveInteger operator +(PositiveInteger left, PositiveInteger right)
{
return (left._value + right._value + 1);
}
}
```
## Managing Serialization Format for date-related types
Certain date-related types like `DateTime`, `DateOnly`, `TimeOnly`, `DateTimeOffset`, and `TimeSpan` can modify their serialization/deserialization format using the `SerializationFormatAttribute`.
For instance, consider the `GDay` type, which represents an XML gDay value. It implements the `IDomainValue` interface and utilizes the `SerializationFormatAttribute` to specify a serialization format.
```csharp
///
/// Represents an XML GDay value object, providing operations for parsing and handling gDay values.
///
[SerializationFormat("dd")]
public readonly partial struct GDay : IDomainValue
{
///
public static PrimitiveValidationResult Validate(int value)
{
return PrimitiveValidationResult.Ok;
}
///
public static DateOnly Default => default;
// Customized string representation of DateOnly
///
public static string ToString(DateOnly value) => value.ToString("dd");
}
```
# Disable Generation of Converters
To disable the generation of Converters, Swagger Mappers or XML serialization, in .csproj file follow the below described steps.
```xml
false
false
false
false
```
:warning: Please note that `DomainPrimitiveGenerator_GenerateXmlSerialization` value by default is `false`.
# Additional Features
1. **PrimitiveValidationResult:** Offers an Ok result and a string containing the error message. It also includes an implicit operator to automatically convert a string to an error value.
[PrimitiveValidationResult](src/AltaSoft.DomainPrimitives/PrimitiveValidationResult.cs)
2. **AltaSoft.DomainPrimitives.StringLengthAttribute** can be used to specify minimum and maximum length restrictions on DomainPrimitives
```csharp
[StringLength(minimumLength:1, maximumLength:100, validate:false)]
public partial class AsciiString : IDomainValue
{
///
public static PrimitiveValidationResult Validate(string value)
{
var input = value.AsSpan();
// ReSharper disable once ForCanBeConvertedToForeach
for (var i = 0; i < input.Length; i++)
{
if (!char.IsAscii(input[i]))
return "value contains non-ascii characters";
}
return PrimitiveValidationResult.Ok;
}
}
```
The Validate property can be used to automatically enforce boolean and string length validations within domain primitives.
Additionally, this attribute can be utilized by **ORMs** to impose string length restrictions in the database.
3. **Chaining Primitive Types**
* Chaining of primitive types is possible. For instance, considering the `PositiveInteger` and `BetweenOneAnd100` DomainPrimitives:
```csharp
public readonly partial struct PositiveInteger : IDomainValue
{
///
public static PrimitiveValidationResult Validate(int value)
{
if (value <= 0)
return PrimitiveValidationResult.Error("value is non-positive");
return PrimitiveValidationResult.Ok;
}
}
public readonly partial struct BetweenOneAnd100 : IDomainValue
{
public static PrimitiveValidationResult Validate(PositiveInteger value)
{
if (value < 100)
return "Value must be less than 100"; //implicit operator to convert string to PrimitiveValidationResult
return PrimitiveValidationResult.Ok;
}
}
```
4.
Defined type `BetweenOneAnd100` automatically inherits restrictions from PositiveInteger. Operators restricted in PositiveInteger are also inherited. Further restrictions on operators can be added using the `SupportedOperationsAttribute`:
```csharp
[SupportedOperations(Addition=false)]
public readonly partial struct BetweenOneAnd100 : IDomainValue
{
public static PrimitiveValidationResult Validate(PositiveInteger value)
{
if (value < 100)
return "Value must be less than 100";
return PrimitiveValidationResult.Ok;
}
}
```
# Restrictions
1. **Implementation of IDomainValue Interface**
* DomainPrimitives are mandated to implement the `IDomainValue` interface to ensure adherence to domain-specific constraints and behaviors.
2. **Constructor Limitation**
* No constructors should be explicitly defined within DomainPrimitives. Doing so will result in a compiler error.
3. **Prohibition of Public Properties or Fields**
* DomainPrimitive types should not contain any explicitly defined public properties or fields. The backing field will be automatically generated.
* If any property or field is explicitly named `_value`, `_valueOrDefault`, or `_isInitialized`, a compiler error will be triggered.
# Examples
## Implicit Usage of DomainType
```csharp
public readonly partial struct PositiveAmount : IDomainValue
{
public static PrimitiveValidationResult Validate(decimal value)
{
if (value <= 0m)
return "Must be a a positive number";
return PrimitiveValidationResult.Ok;
}
}
public static class Example
{
public static void ImplicitConversion()
{
var amount = new PositiveAmount(100m);
PositiveAmount amount2 = 100m; // implicitly converted to PositiveAmount
//implicilty casted to decimal
decimal amountInDecimal = amount + amount2;
}
}
```
# Json Conversion
```csharp
[SupportedOperations] // no mathematical operators should be generated
public readonly partial struct CustomerId : IDomainValue
{
public static PrimitiveValidationResult Validate(decimal value)
{
if (value <= 0m)
return "Must be a a positive number";
return PrimitiveValidationResult.Ok;
}
}
public sealed class Transaction
{
public CustomerId FromId { get; set; }
public CustomerId? ToId { get; set; }
public PositiveAmount Amount { get; set; }
public PositiveAmount? Fees { get; set; }
}
public static void JsonSerializationAndDeserialization()
{
var amount = new Transaction()
{
Amount = 100.523m,
Fees = null,
FromId = 1,
ToId = null
};
var jsonValue = JsonSerializer.Serialize(amount); //this will produce the same result as changing customerId to int and PositiveAmount to decimal
var newValue = JsonSerializer.Deserialize(jsonValue)
}
```
`Serialized Json`
```json
{
"FromId": 1,
"ToId": null,
"Amount": 100.523,
"Fees": null
}
```
# Contributions
Contributions to AltaSoft.DomainPrimitives are welcome! Whether you have suggestions or wish to contribute code, feel free to submit a pull request or open an issue.
# Contact
For support, questions, or additional information, please visit GitHub Issues.
# License
This project is licensed under [MIT](LICENSE.TXT). See the LICENSE file for details.