ConfigurationProperties class

Turns a class into a typed view of a group of settings: every field is filled from the property of the same name under prefix.

Reading settings one by one with @Value(r'${db.url}') spreads property names and conversions over the code. With this annotation the settings of one area (a database pool, an API client) live in one class with typed fields and defaults, and other beans inject that class. The class becomes a bean and gets introspection metadata by itself, without @Component() or @Introspected().

Field maxSize is read from prefix.max-size in any relaxed spelling (prefix.maxSize, prefix.max_size, the environment variable PREFIX_MAXSIZE), from the first property source that has it, and converted to the field's type. Lists and sets bind from a comma list or indexed keys (prefix.hosts[0], YAML lists, PREFIX_HOSTS_0_), maps from the keys below them (prefix.headers.x-a, prefix.headers[x.y]), nested @Introspected objects from prefix.nested.*, also inside lists and maps (prefix.servers[0].name, prefix.backends.eu.url). A list from a higher-precedence source replaces the whole list; map entries are merged per key. Binder describes these rules in full.

A mutable class is bound through its setters:

// From db.url, db.max-size, db.timeout and db.hosts.
@ConfigurationProperties('db')
@Validated()
class DbProperties {
  @NotBlank()
  String url = '';
  int maxSize = 10;
  Duration timeout = const Duration(seconds: 5);
  List<String> hosts = [];
}

@Component()
class ConnectionPool {
  ConnectionPool(this.properties); // already bound and validated
  final DbProperties properties;
}

A class whose only constructor has parameters is created through that constructor instead (constructor binding), which suits immutable classes. A parameter without a property takes its DefaultValue, else its Dart default value, else null when it is nullable; otherwise the start fails naming the property.

@ConfigurationProperties('db')
class DbProperties {
  const DbProperties(this.url, {@DefaultValue('10') required this.maxSize,
      this.timeout = const Duration(seconds: 5)});
  final String url;
  final int maxSize;
  final Duration timeout;
}

With @Validated() on the class, the constraint annotations (@NotBlank(), @Min(1), ...) are checked after binding, and a violation fails the start with a message naming the property.

The annotation can also go on a @Bean method, to bind the object the method returns, for example a class of another package.

Spring (Java):

@ConfigurationProperties("db") @Validated
public class DbProperties {
  String url; int maxSize = 10; Duration timeout;
}

@ConfigurationProperties("db")
public record DbProperties(String url, @DefaultValue("10") int maxSize) {}
Inheritance
Implemented types

Constructors

ConfigurationProperties(String prefix, {String? name, bool ignoreInvalidFields = false, bool ignoreUnknownFields = true})
Binds the properties under prefix. name sets the bean name instead of the one derived from the class.
const

Properties

classes → List<Type>
No other class is introspected because of this annotation: only the annotated class gets metadata (Introspected.classes is empty).
no setteroverride
hashCode → int
The hash code for this object.
no setterinherited
ignoreInvalidFields → bool
Whether a value that cannot be converted is ignored, so the field keeps its default, instead of failing the start. Off by default: a typo in a value should be noticed.
final
ignoreUnknownFields → bool
Whether properties under prefix that match no field are ignored, which is the default.
final
name → String?
The bean name; null gives the class name in lowerCamelCase.
finalinherited
prefix → String
The common start of the property names, in canonical form (lower case, - between words): db for db.url, or my-app.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited