Vogen

If you choose to use record instead of class or struct, be aware of the following implementation differences in the generated code:

1. Value property accessibility: For records, the generated Value property uses init accessibility to support C# with expressions (e.g., var vo2 = vo1 with { Value = 42 }). However, using with to change the value does not correctly trigger the internal 'initialized' state of the object. While the Vogen analyzer will still catch this and cause a compilation error, it is technically inconsistent with the intended lifecycle.
2. ToString implementation: Vogen explicitly overrides ToString for classes and structs to avoid the default record behavior (which enumerates all fields). For records, Vogen still performs this override to ensure the output remains controlled.

Vogen includes analyzers that prevent the use of default or new() (without arguments) for Value Object structs to ensure invalid data cannot enter the domain. This triggers a compilation error VOG009.

// error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
CustomerId c = default;

// error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
var c2 = default(CustomerId);

When using struct as the underlying type for a Value Object, you cannot define your own constructors. Vogen automatically generates:

1. A parameter-less constructor (private).
2. A constructor that takes the underlying value.

Attempting to add custom constructors will result in compilation errors (e.g., VOG008). Use the generated .From() method for creation instead.

If the underlying primitive implements IConvertible, the generated wrapper will also implement IConvertible. This enables compatibility with Convert.ChangeType(), ORMs, and reflection-based serialization. The generated methods (e.g., ToInt32(), ToDecimal(), ToBoolean()) delegate directly to the underlying primitive.

Customization: You can provide your own custom implementations for specific IConvertible methods. Vogen will respect your custom code and only hoist the remaining methods that you haven't implemented.

If the underlying primitive implements IComparable<>, you can configure Vogen to implement IComparable<> and IComparable on the generated wrapper.

To enable this, set the ComparisonGeneration configuration to UseUnderlying. The generated method will be public int CompareTo([primitive] other)... where the generic argument is the type of the wrapped primitive.

Once serializers are generated, they must be registered with the MongoDB BsonSerializer. Vogen automatically generates a static class named RegisterBsonSerializersFor[NameOfProject] to handle this.

Automatic Registration (Default)

By default, the generated static class contains a static constructor that automatically registers all BSON serializers the first time the class is accessed.

Manual Registration

If you need to perform BSON configuration before the serializers are registered, you can switch to manual registration mode using the VogenDefaults assembly attribute with the Customizations.ManuallyRegisterBsonSerializers flag. This prevents the automatic static constructor from running and instead provides a TryRegister() method for you to call explicitly.

When a Vogen ValueObject is based on a primitive type that implements System.IConvertible (such as int, float, decimal, DateTime, etc.), Vogen automatically generates the IConvertible interface on the value object.

This allows your value objects to integrate seamlessly with .NET frameworks and APIs that rely on runtime type conversion, including:

• Convert.ChangeType() for dynamic conversions.
• ORMs (like Entity Framework or Dapper) that map database columns to properties at runtime.
• Reflection-based frameworks like ASP.NET Core parameter binding or WPF data binding.
• Generic data transformation pipelines.

[ValueObject<int>]
public partial struct UserId { }

var userId = UserId.From(42);
// IConvertible enables Convert.ChangeType to work directly with the value object
object asString = Convert.ChangeType(userId, typeof(string));  // "42"

When defining a struct Value Object, you cannot define your own constructors. Vogen automatically generates the parameter-less constructor and the constructor that accepts the underlying value. Attempting to add custom constructors will result in compilation errors (e.g., VOG008).

[ValueObject(typeof(int))]
public partial struct CustomerId {
    // This will cause a compilation error:
    public CustomerId(int value) { }
}