Error Handling and Logging

Exception Catalogue

SimplEnteiner does not define a large hierarchy of custom exception types. It relies primarily on standard BCL exceptions (ArgumentNullException, ArgumentException, InvalidOperationException) raised with descriptive messages, plus one custom exception type for circular dependencies.

Error Handling Flow During Build()

flowchart TD
    A[container.Build] --> B[BuildPendings: flush unregistered bindings]
    B --> C{Registry.Add validation per binding}
    C -->|fails| E1[ArgumentException / InvalidOperationException]
    C -->|ok| D[Scope.Build]
    D --> E[Registry.ValidateAll per scope]
    E -->|missing dependency| E2[InvalidOperationException: Cannot resolve all dependencies]
    E -->|cycle detected| E3[CircularDependencyException]
    E -->|ok| F[Scope.Start: invoke IStartable on singletons]
    F --> G[Recurse into child scopes]
    G --> H[Build complete]

Because Build() performs validation before starting any IStartable singletons, a configuration error anywhere in the graph prevents any startable singleton from running — there's no partial-startup state where some services are running and others failed validation.

Best Practices for Handling Errors in Consuming Code

1. Call container.Build() inside your application's startup path, not lazily. Wrap it (or the whole composition-root method) so failures surface as clear, early, fatal startup errors rather than being discovered mid-request:

   try
   {
       container.Build();
   }
   catch (TypeAnalyzes.CircularDependencyException ex)
   {
       // ex.CircularPath gives you the exact offending cycle for logging/diagnostics
       throw new ApplicationException($"DI cycle detected: {string.Join(" -> ", ex.CircularPath)}", ex);
   }
   catch (InvalidOperationException ex)
   {
       // Missing binding, decorator misconfiguration, etc.
       throw;
   }
   

2. Use AnalyzeReachability(...) in a startup self-test or dedicated test, not on every production boot if your registration graph is large enough that the O(n) walk matters (see Performance and Optimization) — though for most applications running it at every startup is perfectly fine and recommended.

3. Do not rely on GetService-style null-on-miss semantics when going through the MS.DI integration — SimplEnteinerServiceProvider.GetService propagates SimplEnteiner's own InvalidOperationException for missing non-concrete bindings rather than returning null, which differs from some other IServiceProvider implementations. Use try/catch or pre-validate via Build()/AnalyzeReachability instead of relying on null-checks after GetService.

4. Treat the plain Exception thrown by GetInjectableConstructor (multiple [Inject]-marked constructors) as a compile-time-detectable class-authoring mistake — fix the offending type rather than catching this specific case at runtime.

5. OnRelease/OnActivation callbacks should not throw. Neither CleanupService.Dispose()/DisposeAsync() nor Resolver.ResolveRegistration wrap these callback invocations in try/catch — an exception thrown from an OnRelease callback during scope disposal will propagate out of Dispose()/DisposeAsync() and can prevent subsequent tracked instances in the same cleanup batch from being disposed (since the loop is not guarded). Keep these callbacks defensive.

Logging

There is no built-in logging (ILogger, Microsoft.Extensions.Logging, Console.Write*, trace sources, or any other diagnostic output) anywhere in the SimplEnteiner codebase. All "log points" you might want (binding registered, instance activated/released, decorator applied) must be added by consumers via:

• .OnActivation(instance => logger.LogDebug(...)) / .OnRelease(instance => logger.LogDebug(...)) per binding.
• Implementing IInitializable/IAsyncInitializable/IStartable on your own types and logging from within those hooks.
• Wrapping services with a logging decorator.

See Configuration and Settings → Logging Configuration for the same conclusion from a configuration-surface perspective.

Continue to Building and Deployment.