This documentation provides an in-depth overview of the configuration options available in the development environment for the stevedunn/vogen project. The focus is on the specific configuration settings you can use to customize the build and functionality of your value objects.

Configuration Options

Below are the configuration options available, along with code examples illustrating their usage.

1. Conversions

Controls what conversion code is generated. The default setting is Conversions.Default, which generates type converters along with a converter for serialization using System.Text.Json.

var config = new Vogen.Config
{
    Conversions = Conversions.Default
};

2. Exceptions Handling

Specifies the type of exception thrown when validation fails. The default is ValueObjectValidationException.

var config = new Vogen.Config
{
    Throws = typeof(ValueObjectValidationException)
};

3. Customizations

This setting enables customization switches. By default, it is set to Customizations.None.

var config = new Vogen.Config
{
    Customizations = Customizations.None
};

4. Deserialization Strictness

Indicates how strict deserialization should be. The default value is DeserializationStrictness.AllowValidAndKnownInstances, allowing for predefined instances that may otherwise be invalid.

var config = new Vogen.Config
{
    DeserializationStrictness = DeserializationStrictness.AllowValidAndKnownInstances
};

5. From Primitive Casting

Defines the type of casting used from primitive to wrapper. It defaults to CastOperator.Explicit.

var config = new Vogen.Config
{
    FromPrimitiveCasting = CastOperator.Explicit
};

6. Parsable for Strings

Determines what is generated for IParsable types with strings. Defaulted to ParsableForStrings.GenerateMethodsAndInterface.

var config = new Vogen.Config
{
    ParsableForStrings = ParsableForStrings.GenerateMethodsAndInterface
};

7. Try From Generation

Specifies the implementation details for TryFrom methods. It defaults to TryFromGeneration.GenerateBoolAndErrorOrMethods.

var config = new Vogen.Config
{
    TryFromGeneration = TryFromGeneration.GenerateBoolAndErrorOrMethods
};

8. Is Initialized Method Generation

Indicates whether the IsInitialized() method should be generated. The default value is IsInitializedMethodGeneration.Generate.

var config = new Vogen.Config
{
    IsInitializedMethodGeneration = IsInitializedMethodGeneration.Generate
};

9. Type Explicit Specification

Controls whether individual value objects should explicitly specify the primitive type they wrap. By default, it is set to false.

var config = new Vogen.Config
{
    ExplicitlySpecifyTypeInValueObject = false
};

10. Disable Stack Trace Recording in Debug

If set to true, stack trace recording will be disabled. This can affect how exceptions are thrown when a value object is created in an uninitialized state.

var config = new Vogen.Config
{
    DisableStackTraceRecordingInDebug = true
};

Code Examples for Configuration Combinations

When combining configurations, defaults are utilized if values are not specified. Below is an example of combining configurations:

var baseConfig = new Vogen.Config
{
    Customizations = Customizations.None,
    Throws = typeof(ValueObjectValidationException)
};

var additionalConfig = new Vogen.Config
{
    Conversions = Conversions.Default,
    FromPrimitiveCasting = CastOperator.Explicit
};

var combinedConfig = CombineConfigurations.CombineAndResolveAnythingUnspecified(baseConfig, additionalConfig);

Validation of Configuration

Ensure that the configuration adheres to the expected types and constraints. For example, if a custom exception is specified, it must derive from System.Exception and have an appropriate constructor.

if (customExceptionType != null && !typeof(System.Exception).IsAssignableFrom(customExceptionType))
{
    throw new InvalidOperationException("The specified throws type must derive from System.Exception.");
}

Conclusion

The configuration settings in the stevedunn/vogen project provide extensive options for customization of value objects in C#. Adjusting these settings allows for accommodating strictness in conversions, exceptions handling, and more to tailor the functionality to project requirements.

Source: Configuration Documentation