Dependency injection (development)
Contracts live in Neo.DependencyInjection.Abstractions; the default container
lives in Neo.DependencyInjection. ServiceCollection and
ServiceProvider define registration and resolution; DefaultServiceCollection
is the default implementation. Import Neo.DependencyInjection.* for typed
registration and lookup extensions. This development API follows .NET DI's
service identities, registration order, constructor selection and lifetimes,
using neoCLR Result and Optional contracts.
Try it
Register an existing instance, build a provider, then resolve it by its service type. The caller owns supplied instances; use disposes the provider.
module Examples.Extensions.Introductions.DependencyInjection
import System.*
import System.Result.*
import Neo.DependencyInjection.*
class Message {
val Text: string
init(text: string) { Text = text }
}
func Main() -> int {
let services: ServiceCollection = DefaultServiceCollection()
let Ok(_) = services.AddSingleton<Message>(Message("Hello from DI")) else { return 1 }
let Ok(provider) = services.Build() else { return 1 }
use owned = provider
let Ok(message) = provider.GetRequiredService<Message>() else { return 1 }
Console.WriteLine(message.Text)
return 0
}
Complete sample project · Build and run instructions
Registration and activation
ServiceDescriptor(service, source, lifetime) is immutable. ServiceSource
selects Constructor(TypeInfo), Factory((ServiceProvider) -> Result<Object, ServiceError>) or Instance(Object). A collection accepts descriptors through
Add, or uses Add(service, implementation, lifetime), AddFactory and
AddInstance. Invalid types, assignability, lifetimes and instance identities
return InvalidRegistration. Instance descriptors require singleton lifetime.
Service instances are reference types with fully bound identities. Open generic
service/implementation definitions are supported for constructor registrations;
value-type services are not supported.
AddTransient<TService, TImplementation>(), AddScoped<...>() and
AddSingleton<...>() register implementations. Their single-type overloads
register the type as its own implementation. Factory overloads accept
(ServiceProvider) -> Result<TService, ServiceError>; AddSingleton(instance)
retains a caller-owned instance. Registration returns Result<unit, ServiceError>.
Build() returns Result<ServiceProvider, ServiceError>. It snapshots the
registrations, so later additions do not affect an existing provider. Constructor
plans select the public constructor with the most available dependencies. Another
applicable constructor is ambiguous when it requires a type absent from that
selection. Build does not call constructors or factories. Optional parameter
defaults, collection injection and keyed parameter annotations are not implemented. ActivationError distinguishes unsupported types, missing or
ambiguous constructors and invocation failures.
Factories receive the current provider. A singleton factory always receives the
root provider, even when requested from a scope. Factory results are checked for
assignability before being cached or returned. Invalid results return
InvalidFactoryResult; cyclic resolution returns Cycle. Reported failures reset
resolution state so subsequent calls can retry. Guest terminal faults retain the
runtime's terminal-failure behavior; they are not converted into ServiceError.
Resolution
| Member | Result |
|---|---|
GetRequiredService(TypeInfo) |
Result<Object, ServiceError>; Missing when unregistered |
GetService(TypeInfo) |
Result<Optional<Object>, ServiceError>; None only when unregistered |
GetServices(TypeInfo) |
Result<Sequence<Object>, ServiceError>; empty when unregistered |
Corresponding <T>() extension |
The same behavior with typed values |
Single lookup uses the last registration. Plural lookup preserves registration
order; separate singleton registrations retain separate instances. All lookup
forms propagate activation and factory errors. GetServices<T> projects its
result storage without a second element-array copy. ServiceProvider itself is
implicitly available for constructor injection and single lookup, but cannot be
explicitly registered and is not included in plural lookup.
Lifetimes and disposal
Transient registrations create a value on each resolution. Scoped registrations
cache within one scope. Singletons cache within the root provider and are shared
by all its scopes. CreateScope() returns an independently disposable provider;
a scope created from another scope shares the same root, not the parent's cache.
Root resolution of scoped services always returns ScopeRequired. This deliberate
always-on validation prevents captive scoped dependencies in singleton activation;
.NET exposes configurable scope validation.
Dispose each created scope. Created disposable services are released once per provider, in reverse creation order; duplicate references within that provider are deduplicated. Explicit instances remain caller-owned. A factory transfers ownership of its result: avoid returning caller-owned disposable objects through a factory or aliasing ownership across providers. Prefer instance registration for external ownership. Root disposal invalidates live scopes but does not dispose their owned services. Disposal is idempotent. Resolution and scope creation after disposal return Disposed. A factory that disposes its provider cannot publish a new result; the result is released if necessary.
Resolution is synchronous and invocation-owned, consistent with serialized guest continuations and isolated worker heaps. Providers are not a shared-object threading contract. Async factories/disposal are not supported. Registration lookup is linear; activation uses one argument array and ordinary reflection. There is no allocation-free or optimized-throughput claim.
Native execution
Automatic construction requires constructor metadata and executable retention.
The native build helper accepts repeatable
--reflection-constructor-type Full.Type.Name arguments, resolved from the final
compiled application. The private schema-7 policy sets constructors and
construct. Do not reuse metadata indices from a different compilation.
The current native retention contract supports nongeneric implementation
declarations with supported scalar/reference constructor arguments. Closed generic
service interfaces, such as Localizer<Feature>, are ordinary service identities.
Generic implementation construction requires further native retention work;
explicit factories can construct types already supported by ordinary codegen.
Missing constructor metadata remains an explicit runtime fault, not an empty
constructor list. General reflective method invocation is a separate capability.
Keyed services and function objects
ServiceDescriptor.ServiceKey is an optional Object key. The four-argument
constructor accepts (service, key, source, lifetime). Null denotes the ordinary
unkeyed identity, matching .NET. Other keys use normal neoCLR Object equality;
key equality must remain stable while registered. Primitive value keys box at the
Object boundary. No AnyKey wildcard or implicit fallback is provided.
AddKeyed, AddKeyedFactory and AddKeyedInstance are the runtime-type
registration forms. Typed AddKeyedTransient, AddKeyedScoped and
AddKeyedSingleton provide implementation, self-registration and factory forms;
the singleton form also accepts an instance. Keyed factories receive
(ServiceProvider, Object?), with the registered key as their second argument.
GetRequiredKeyedService<T>(key), GetKeyedService<T>(key) and
GetKeyedServices<T>(key) select only that type/key pair. Runtime-type forms take
(TypeInfo, Object?). Last-registration and ordered-plural rules apply within each
pair, and caches remain per registration. Unkeyed lookup excludes non-null keys.
Missing required keyed lookup returns MissingKeyed(type, key); null-key missing
lookup retains Missing. Factory failures remain errors in optional lookup too.
Automatic constructor parameters currently resolve unkeyed dependencies; keyed
parameter annotations and key inheritance are not implemented. A factory can
explicitly resolve a keyed dependency.
Bound Function objects are services. Register a value of (int) -> int with
AddKeyedSingleton<(int) -> int>(key, function), retrieve that same type, and invoke
the returned function normally. The registration does not execute the function.
Multiple methods sharing one structural signature can therefore use different
keys. Bound instance methods retain their receiver. Registering a function does
not transfer disposal ownership of its captured receiver; register an owned
receiver separately when the provider should dispose it. Function objects have no
automatic-constructor registration: use instance or factory registration.
The key model follows .NET keyed DI. The deliberate differences are Result/Optional outcomes, neoCLR's own value equality (including canonical text equality), always-on scope validation and the documented subset of constructor/retention support.
Conditional defaults
ServiceCollection.TryAdd(ServiceDescriptor) returns Result<bool, ServiceError>:
true when added, false when the exact service type/key already exists, or an error
when a new descriptor is invalid. Existing registrations win regardless of lifetime
or activation source. A duplicate is skipped before validating its replacement.
Factories are never invoked by registration checks.
Typed TryAddTransient, TryAddScoped, TryAddSingleton and their TryAddKeyed*
forms mirror the Add helpers, including implementation mappings, self registration,
factories and singleton instances. Runtime-type helpers include TryAdd,
TryAddFactory, TryAddInstance and keyed equivalents. Null keys share the unkeyed
identity; non-null keys use ordinary equality. The bool result is a deliberate
neoCLR addition to .NET's conditional-registration convention. TryAddEnumerable
and wildcard keys are not part of this foundation. Registration may allocate a
descriptor or factory adapter even when skipped; no allocation-free claim is made.
Registration checks use TypeInfo.ContainsGenericParameters, the shared recursive
identity query. Inheritance openness (IsOpen) does not reject an otherwise closed
service. Open generic constructor mappings are supported; open factory/instance registrations are rejected.
Tested application example
The DI feature page includes a complete scoped greeting example. Its source is shared with the built-in container tests; the runnable project shows the exact native constructor-retention option.
Open generic mappings (development)
Register typeof(Service<>) with typeof(Implementation<>) using a constructor
source and the desired lifetime. Both must be generic definitions of matching
arity. Resolution closes the implementation with the requested service arguments,
checks constraints and assignability, then uses the ordinary constructor plan.
Exact closed registrations take precedence for single lookup. Plural lookup
includes matching closed and open registrations in registration order.
Caches and cycle detection are per registration and closed service identity; keys and lifetimes retain their existing rules. Invalid closure returns InvalidRegistration; constructor-plan failures return Activation. Native programs must retain the generic implementation constructors and the required closed service shapes. Unretained construction is an explicit failure, not dynamic code generation. Collection injection and keyed constructor annotations remain gaps.
Namespace and assembly migration (2026-10-28)
Replace System.DependencyInjection imports with Neo.DependencyInjection and rebuild against the new assembly. No old-name compatibility shim is provided. See the application-service boundary for dependencies and migration.
Development assembly split (2026-10-28): contracts, descriptors, lifetime/error types and typed registration/resolution helpers live in Neo.DependencyInjection.Abstractions.dll, referencing only System.Runtime. Neo.DependencyInjection.dll contains the default container and constructor activation. Namespaces remain unchanged; rebuild consumers against the new assembly identities. No new friend access or public implementation helper is introduced.