Environment

Environment is the application's configuration as code sees it: every property from every source, and the active profiles.

Why

Most beans never need it. @Value and @ConfigurationProperties read properties for them, and @Profile switches beans on profiles. Take the Environment when:

• the key is only known at run time (shop.banner.$language);
• a decision in code depends on the active profiles;
• text from elsewhere contains ${...} placeholders to fill.

The environment is a bean. A constructor parameter of type Environment receives it; EnvironmentAware works too. Placeholders in values are resolved and relaxed names are found.

Environment is read-only. ConfigurableEnvironment is the side that changes it: property sources, profiles, conversion. It is for startup code, such as an EnvironmentPostProcessor, and for tests.

Example

import 'package:spring_core_dart/spring_core_dart.dart';

@Service()
class FeatureFlags {
  FeatureFlags(this.env);
  final Environment env;

  // Converted to the requested type by the ConversionService.
  bool get betaOn => env.getPropertyAs<bool>('shop.beta', defaultValue: false)!;
  int get maxItems => env.getPropertyAs<int>('shop.max-basket-size') ?? 10;
  Duration? get timeout => env.getPropertyAs<Duration>('shop.checkout-timeout');

  // The key depends on the language, so @Value cannot name it.
  String banner(String language) =>
      env.getProperty('shop.banner.$language') ??
      env.resolvePlaceholders(r'Welcome to ${shop.title}');

  // Throws MissingPropertyException when no source has the key.
  String get title => env.getRequiredProperty('shop.title');

  // Tells "set to empty" from "not set".
  bool get hasMotto => env.containsProperty('shop.motto');

  bool get showDebugInfo => env.matchesProfiles(['dev & !test']);
}

Reading the configuration without a context, in a command-line tool or a test:

Future<void> main(List<String> args) async {
  final environment = StandardEnvironment()
    ..propertySources.addFirst(SimpleCommandLinePropertySource(args));
  // Reads application.* and the profile files, as SpringApplication does.
  await ConfigDataEnvironment(environment).processAndApply();
  final port = environment.getPropertyAs<int>('server.port');
}

A test can replace the OS environment variables:

final environment = StandardEnvironment(
  systemEnvironment: {'SPRING_PROFILES_ACTIVE': 'test'},
);
environment.activeProfiles; // ['test']

Members

Environment (and PropertyResolver, which it implements):

ConfigurableEnvironment adds:

StandardEnvironment is the implementation used everywhere. It starts with one property source, the environment variables. SpringApplication adds the command line, --dart-define values, the config files and the defaults.

Changing it at startup

Beans should not change the environment: other beans may already have read it. To add a source or a profile, use an EnvironmentPostProcessor. It runs while the environment is prepared, before any bean exists.

class RegionProfile implements EnvironmentPostProcessor {
  @override
  void postProcessEnvironment(
    ConfigurableEnvironment environment,
    SpringApplication application,
  ) {
    // Machines in the EU data centre run with the `eu` profile.
    if (environment.getProperty('REGION') == 'eu') {
      environment.addActiveProfile('eu');
    }
  }
}

final app = SpringApplication(
  [appBeans],
  environmentPostProcessors: [RegionProfile()],
);

A post-processor whose order is smaller than EnvironmentPostProcessor.configDataOrder (implement Ordered) runs before the config files are read, so its profiles and sources decide which files are loaded. The others run after.

In Spring (Java)

@Service
class FeatureFlags {
  private final Environment env;
  FeatureFlags(Environment env) { this.env = env; }

  boolean betaOn() { return env.getProperty("shop.beta", Boolean.class, false); }
  boolean showDebugInfo() { return env.matchesProfiles("dev & !test"); }
}

Differences that matter:

• Typed access is getPropertyAs<T>(key) instead of getProperty(key, Class). Dart has no overloading.
• matchesProfiles takes a list of expressions, not varargs.
• There are no JVM system properties.
• Post-processors are passed to SpringApplication(environmentPostProcessors: [...]), not listed in META-INF/spring.factories.

See also

• Property sources
• Profiles
• Placeholders
• @Value
• Aware interfaces
• ConversionService