OptionsAttribute

NexusLabs.Needlr.Generators

OptionsAttribute Class

Marks a class as an options/configuration type that should be bound to a configuration section. The source generator will automatically generate the services.Configure<T>() call.

public sealed class OptionsAttribute : System.Attribute

Inheritance System.Object 🡒 System.Attribute 🡒 OptionsAttribute

Example

// Section name inferred as "Database"
[Options]
public class DatabaseOptions
{
    public string ConnectionString { get; set; } = "";
    public int CommandTimeout { get; set; } = 30;
}

// Explicit section name
[Options("MyApp:Database")]
public class DbOptions
{
    public string ConnectionString { get; set; } = "";
}

// With validation at startup
[Options(ValidateOnStart = true)]
public class StripeOptions
{
    [Required]
    public string ApiKey { get; set; } = "";
}

// Named options for multiple instances
[Options("Databases:Primary", Name = "Primary")]
[Options("Databases:Replica", Name = "Replica")]
public class ConnectionOptions
{
    public string ConnectionString { get; set; } = "";
    public bool ReadOnly { get; set; }
}

Remarks

When applied to a class, the generator will emit code to bind the class to a configuration section. If no section name is specified, it is inferred from the class name by stripping common suffixes (Options, Settings, Config).

All three options interfaces are registered automatically: - IOptions<T> - Singleton, no reload - IOptionsSnapshot<T> - Scoped, reloads per request - IOptionsMonitor<T> - Singleton with change notifications

Constructors

OptionsAttribute() Constructor

Initializes a new instance of the OptionsAttribute class with the section name inferred from the class name.

public OptionsAttribute();

OptionsAttribute(string) Constructor

Initializes a new instance of the OptionsAttribute class with an explicit section name.

public OptionsAttribute(string sectionName);

Parameters

sectionName System.String

The configuration section name to bind to (e.g., "Database" or "MyApp:Database").

Properties

OptionsAttribute.Name Property

Gets or sets the name for named options. When set, registers as a named option that can be retrieved via IOptionsSnapshot<T>.Get(name) or IOptionsMonitor<T>.Get(name).

public string? Name { get; set; }

Property Value

System.String

Remarks

Use this when you need multiple configurations of the same options type, such as primary and replica database connections.

OptionsAttribute.SectionName Property

Gets the configuration section name to bind to. If null, the section name is inferred from the class name.

public string? SectionName { get; }

Property Value

System.String

OptionsAttribute.ValidateMethod Property

Gets or sets the name of the validation method to use.

public string? ValidateMethod { get; set; }

Property Value

System.String

Example

[Options(ValidateOnStart = true, ValidateMethod = nameof(CheckConfig))]
public class MyOptions
{
    public IEnumerable<ValidationError> CheckConfig()
    {
        if (string.IsNullOrEmpty(Value))
            yield return "Value is required";
    }
}

Remarks

By default (when null), the generator looks for a method named Validate. Set this property to use a differently-named method.

The method must return IEnumerable<ValidationError> (or IEnumerable<string> for backward compatibility) and take no parameters (for instance methods) or the options type as a parameter (for static methods).

OptionsAttribute.ValidateOnStart Property

Gets or sets a value indicating whether to validate the options at application startup. When true, validation errors will prevent the application from starting.

public bool ValidateOnStart { get; set; }

Property Value

System.Boolean

Remarks

When enabled, the generator will emit: - .ValidateDataAnnotations() - Validates [Required], [Range], etc. - .ValidateOnStart() - Runs validation during startup

For custom validation, implement a Validate() method returning IEnumerable<ValidationError>, or specify an external validator using the Validator property.

OptionsAttribute.Validator Property

Gets or sets the external validator type to use.

public System.Type? Validator { get; set; }

Property Value

System.Type

Example

[Options(ValidateOnStart = true, Validator = typeof(MyOptionsValidator))]
public class MyOptions { ... }

public class MyOptionsValidator : IOptionsValidator<MyOptions>
{
    public IEnumerable<ValidationError> Validate(MyOptions options) { ... }
}

Remarks

When set, validation is delegated to the specified type instead of a method on the options class. The validator type must implement IOptionsValidator<T> or FluentValidation's AbstractValidator<T> (if FluentValidation is referenced).

Can be combined with ValidateMethod to specify a custom method name on the validator type (default is Validate).