Configuration Options

Vogen’s behavior can be customized on a global and per-value object level using VogenConfiguration. This section outlines the available options and their default values.

Default Instance: The VogenConfiguration.DefaultInstance property provides the default settings used if no explicit configuration is specified.

Global Configuration: The [Vogen] attribute can be used to apply global configurations. This attribute accepts a VogenConfiguration instance containing the desired customizations.

Local Configuration: You can further customize configuration for individual value objects by applying the [Vogen] attribute directly to the value object class. The configuration specified in the [Vogen] attribute takes precedence over the global settings.

Code Snippet:

//Global Configuration
          [Vogen(new VogenConfiguration { 
             // Configure settings here
          })]
          public class MyValueObject : ValueObject<MyValueObject> 
          { 
             //Value object implementation
          }
          
          //Local Configuration
          [Vogen(new VogenConfiguration { 
              // Configure settings here
          })]
          public class MyValueObject2 : ValueObject<MyValueObject2> 
          { 
              //Value object implementation
          }
          

Configuration Options:

• conversions: Specifies the type of conversion code to generate.
  • Default: Conversions.Default - generates type converters and a converter for System.Text.Json serialization.
  • Other Options: Conversions.Minimal, Conversions.None
  • Example:

    [Vogen(new VogenConfiguration { Conversions = Conversions.Minimal })] 
              

• throws: Specifies the type of exception thrown when validation fails.
  • Default: ValueObjectValidationException
  • Example:

    [Vogen(new VogenConfiguration { ValidationExceptionType = typeof(MyCustomValidationException) })]
              

• customizations: Enables or disables simple customization features.
  • Default: Customizations.None
  • Other Options: Customizations.All, Customizations.Equality
  • Example:

    [Vogen(new VogenConfiguration { Customizations = Customizations.Equality })]
              

• deserializationStrictness: Specifies how strict deserialization should be.
  • Default: DeserializationStrictness.AllowValidAndKnownInstances
  • Other Options: DeserializationStrictness.Validate, DeserializationStrictness.AllowValidAndKnownInstances, DeserializationStrictness.AllowOnlyKnownInstances
  • Example:

    [Vogen(new VogenConfiguration { DeserializationStrictness = DeserializationStrictness.Validate })] 
              

• explicitlySpecifyTypeInValueObject: Indicates whether value objects should explicitly define the primitive type they wrap.
  • Default: false
  • Example:

    [Vogen(new VogenConfiguration { ExplicitlySpecifyTypeInValueObject = true })] 
              

• disableStackTraceRecordingInDebug: Disables stack trace recording in Debug builds.
  • Default: false
  • Example:

    [Vogen(new VogenConfiguration { DisableStackTraceRecordingInDebug = true })]
              

Important Considerations:

• Ensure that any custom exception type you specify for ValidationExceptionType derives from System.Exception and has one public constructor that takes an int.
• Check for code analysis warnings related to invalid configuration settings.

Code Snippet:

// Configuration for a value object, combining global and local settings
          [Vogen(new VogenConfiguration { 
             // Configure settings here
          })]
          public class MyValueObject : ValueObject<MyValueObject>
          {
              //Value object implementation
          }
          
          // Global configuration (VogenAttribute in the assembly)
          [Vogen(new VogenConfiguration {
              // Configure settings here
          })]
          

Top-Level Directory Explanations

samples/ - This directory contains example projects that demonstrate the usage of the Vogen library. Each subdirectory represents a different example, and contains the necessary files and configurations for that example.

src/ - This directory contains the source code for the project. It includes the Vogen library itself, as well as any shared types and code fixers.

src/obj/ - This directory contains object files generated during the compilation process.

src/Vogen/ - This subdirectory contains the core Vogen library code. It includes subdirectories for diagnostics, extensions, generators, properties, rules, suppressors, templates, and binaries and object files.

tests/ - This directory contains unit tests and benchmarks for the project. It includes subdirectories for analyzer tests, consumer tests, snapshot tests, and Vogen benchmarks.

tests/AnalyzerTests/ - This subdirectory contains unit tests for the analyzer component of the Vogen library.

tests/ConsumerTests/ - This subdirectory contains unit tests for the consumer-side components of the Vogen library.

tests/SnapshotTests/ - This subdirectory contains snapshot tests, which test the output of the code generation and serialization components of the Vogen library.

tests/Vogen.Benchmarks/ - This subdirectory contains benchmarks for the performance of the Vogen library.