Dependency injection

This document provides a detailed overview of how Dependency Injection (DI) is configured and utilized within TheExampleApp. A solid understanding of this topic is crucial for maintaining and extending the application, as DI is the core mechanism for managing services and their dependencies.

The application leverages the built-in DI container provided by ASP.NET Core 2.1. Service registration is centralized in the ConfigureServices method of the Startup.cs class.

See also:

• /architecture/application_overview.md
• /configuration/service_configuration.md

Service registration

All services, whether from the framework, third-party libraries, or custom application code, are registered in the IServiceCollection within Startup.ConfigureServices. This method is called by the ASP.NET Core runtime at application startup.

The registration process involves mapping an interface (the abstraction) to a concrete class (the implementation) and defining the service's lifetime.

Here is a representative snippet from Startup.cs showing how various services are registered:

// File: TheExampleApp/Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // Framework services
    services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();
    services.AddSession(options => {
        // IdleTimeout is set high for this application's specific needs
        options.IdleTimeout = TimeSpan.FromDays(2);
    });
    services.AddMvc().AddRazorPagesOptions(
        options => {
            options.Conventions.AddPageRoute("/Courses", "Courses/Categories/{category?}");
            options.Conventions.AddPageRoute("/Courses/Index", "Courses/{slug}/lessons");
            options.Conventions.AddPageRoute("/Courses/Lessons", "Courses/{slug}/lessons/{lessonSlug}");
        });

    // Third-party library services
    services.AddContentful(Configuration);

    // Custom application services
    services.AddSingleton<IContentfulOptionsManager, ContentfulOptionsManager>();
    services.AddTransient<IContentfulClient, ContentfulClient>((ip) => {
        // ... custom factory implementation
    });
    services.AddSingleton<IViewLocalizer, JsonViewLocalizer>();
    services.AddTransient<IVisitedLessonsManager, VisitedLessonsManager>();
    services.AddTransient<IBreadcrumbsManager, BreadcrumbsManager>();

    // File provider for embedded resources (used by JsonViewLocalizer)
    var embeddedProvider = new EmbeddedFileProvider(GetType().GetTypeInfo().Assembly);
    services.AddSingleton<IFileProvider>(embeddedProvider);

    // ... other registrations
}

Built-in services

The application relies on several key services provided by the ASP.NET Core framework or integrated third-party libraries.

HttpClient (Staging Environment)

In staging environments, the application conditionally registers a custom HttpClient with a specialized message handler. This handler redirects Contentful API requests to a staging host.

// File: TheExampleApp/Startup.cs

if (CurrentEnvironment.IsStaging())
{
    var host = Environment.GetEnvironmentVariable("StagingHost");
    if (!string.IsNullOrEmpty(host))
    {
        services.AddSingleton((ip) =>
        {
            var stagingHandler = new StagingMessageHandler
            {
                StagingHost = host
            };
            return new HttpClient(stagingHandler);
        });
    }
}

The StagingMessageHandler uses a regex to replace "contentful" in API URLs with the staging host value. This is registered as a Singleton and is injected into the IContentfulClient factory when creating Contentful client instances.

IContentfulClient

While the contentful.aspnetcore SDK provides an AddContentful() extension method for basic registration, this application uses a custom factory to register IContentfulClient. This is a critical design decision that enables dynamic, per-session Contentful credentials.

The service is registered as Transient, ensuring a new client is created for each injection. The factory retrieves the current ContentfulOptions from our custom IContentfulOptionsManager, which may pull credentials from the user's session instead of the global configuration.

// File: TheExampleApp/Startup.cs

// Custom factory for IContentfulClient
services.AddTransient<IContentfulClient, ContentfulClient>((ip) => {
    var client = ip.GetService<HttpClient>();
    // The manager checks the session for custom options
    var options = ip.GetService<IContentfulOptionsManager>().Options;
    var contentfulClient = new ContentfulClient(client,
        options);
    var version = typeof(Startup).GetTypeInfo().Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()
.InformationalVersion;
    // Adds application info to the User-Agent header for Contentful's API
    contentfulClient.Application = $"app the-example-app.csharp/{version}; {contentfulClient.Application}";
    return contentfulClient;
});

This pattern is essential for the feature allowing users to preview content using different API keys at runtime. For more details on this configuration, see /configuration/service_configuration.md.

IHttpContextAccessor

IHttpContextAccessor is a fundamental framework service that provides access to the current HttpContext from within other services. It is registered as a Singleton using TryAddSingleton to prevent multiple registrations.

// File: TheExampleApp/Startup.cs
services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();

It is a dependency for several custom services that need to interact with request-specific data like session state, cookies, or request items:

• ContentfulOptionsManager (reads session state)
• VisitedLessonsManager (reads/writes cookies)
• BreadcrumbsManager (reads HttpContext.Items)

Note: Accessing HttpContext from a Singleton service can be problematic if not handled carefully. The correct pattern, used here, is to inject IHttpContextAccessor into the singleton and then access its HttpContext property within a method call. This ensures you are always working with the HttpContext of the current request, not a stale context captured when the singleton was created. See /core_features/session_management.md.

IViewLocalizer

The application uses a custom implementation of IViewLocalizer for its internationalization (i18n) needs. JsonViewLocalizer replaces the default resource-file-based localization with a system that reads translation strings from JSON files located in /wwwroot/locales.

It is registered as a Singleton because it loads and caches all translation files into memory at application startup, which is an expensive one-time operation.

// File: TheExampleApp/Startup.cs
services.AddSingleton<IViewLocalizer, JsonViewLocalizer>();

The implementation in JsonViewLocalizer.cs uses an injected IFileProvider to find and parse the JSON locale files.

// File: TheExampleApp/Configuration/LocalizationConfiguration.cs

public class JsonViewLocalizer : IViewLocalizer
{
    private Dictionary<string, Dictionary<string,string>> _items = new Dictionary<string, Dictionary<string, string>>();

    // The constructor loads all JSON files on application start
    public JsonViewLocalizer(IFileProvider provider)
    {
        var files = provider.GetDirectoryContents("");

        foreach (IFileInfo file in files)
        {
            using ( var sr = new StreamReader(file.CreateReadStream()))
            {
                var fileContents = sr.ReadToEnd();
                var dictionary = JsonConvert.DeserializeObject<Dictionary<string, string>>(fileContents);
                var fileName = Path.GetFileNameWithoutExtension(file.Name);
                _items.Add(fileName.Substring(fileName.LastIndexOf('.') + 1), dictionary);
            }
        }
    }
    // ... implementation
}

For more information on how localization is handled, refer to /features/localization.md.

Custom services

The application defines several of its own services to encapsulate business logic and separate concerns.

IContentfulOptionsManager

• Lifetime: Singleton
• Implementation: ContentfulOptionsManager.cs
• Purpose: To act as the single source of truth for ContentfulOptions. Its primary responsibility is to check if custom Contentful credentials exist in the current user's session. If they do, it returns them; otherwise, it falls back to the default options from appsettings.json. This enables the dynamic IContentfulClient behavior described earlier.

// File: TheExampleApp/Configuration/ContentfulOptionsManager.cs

public class ContentfulOptionsManager : IContentfulOptionsManager
{
    private ContentfulOptions _options;
    private readonly IHttpContextAccessor _accessor;

    public ContentfulOptionsManager(IOptions<ContentfulOptions> options, IHttpContextAccessor accessor)
    {
        _options = options.Value; // Caches the default options
        _accessor = accessor;
    }

    public ContentfulOptions Options {
        get {
            // Checks session on every access
            var sessionString = _accessor.HttpContext.Session.GetString(nameof(ContentfulOptions));

            if (!string.IsNullOrEmpty(sessionString))
            {
                return JsonConvert.DeserializeObject<ContentfulOptions>(sessionString);
            }
            return _options; // Fallback to default
        }
    }
    // ...
}

IVisitedLessonsManager

• Lifetime: Transient
• Implementation: VisitedLessons.cs
• Purpose: Manages tracking which course lessons a user has visited. It uses a browser cookie for persistence.
• Rationale for Transient Lifetime: The manager's state (VisitedLessons list) is initialized from a cookie in its constructor. A new instance must be created for each request to ensure it reads the most up-to-date cookie sent by the client.

// File: TheExampleApp/Configuration/VisitedLessons.cs

public class VisitedLessonsManager: IVisitedLessonsManager
{
    private readonly IHttpContextAccessor _accessor;
    public List<string> VisitedLessons { get; private set; }

    public VisitedLessonsManager(IHttpContextAccessor accessor)
    {
        VisitedLessons = new List<string>();
        _accessor = accessor;
        // Reads the cookie at the time of instantiation
        var cookie = _accessor.HttpContext.Request.Cookies[_key];
        if (!string.IsNullOrEmpty(cookie))
        {
            VisitedLessons = new List<string>(cookie.Split(';', StringSplitOptions.RemoveEmptyEntries));
        }
    }
    // ...
}

IBreadcrumbsManager

• Lifetime: Transient
• Implementation: Breadcrumbs.cs
• Purpose: Provides a way to programmatically modify breadcrumb labels after they have been generated by the Breadcrumbs middleware. This is useful for replacing generic URL slugs (e.g., lesson-1) with dynamic, human-readable titles fetched from Contentful (e.g., "Introduction to ASP.NET Core").
• Rationale for Transient Lifetime: The Breadcrumbs middleware runs early in the request pipeline and stores the generated breadcrumbs in HttpContext.Items. The BreadcrumbsManager is instantiated later (e.g., in a Razor Page model) and reads this data from HttpContext.Items in its constructor. A transient lifetime ensures it is created after the middleware has run and has access to the correct request's items.

// File: TheExampleApp/Configuration/Breadcrumbs.cs

public class BreadcrumbsManager : IBreadcrumbsManager
{
    private readonly IHttpContextAccessor _accessor;
    private List<Breadcrumb> _crumbs;

    public BreadcrumbsManager(IHttpContextAccessor accessor)
    {
        _accessor = accessor;
        // Reads breadcrumbs generated by the middleware from HttpContext.Items
        _crumbs = accessor.HttpContext.Items["breadcrumbs"] as List<Breadcrumb>;
    }

    public void ReplaceCrumbForSlug(string slug, string label)
    {
        if(_crumbs.Any(c => c.Label == slug))
        {
            _crumbs.First(c => c.Label == slug).Label = label;
        }
    }
}

IFileProvider

• Lifetime: Singleton
• Implementation: EmbeddedFileProvider (from Microsoft.Extensions.FileProviders)
• Purpose: Provides access to embedded resource files within the application's assembly. This is used by JsonViewLocalizer to read the JSON translation files that are embedded as resources.
• Rationale for Singleton Lifetime: The embedded files are part of the compiled assembly and do not change at runtime, making it safe and efficient to share a single instance across the entire application.

// File: TheExampleApp/Startup.cs

var embeddedProvider = new EmbeddedFileProvider(GetType().GetTypeInfo().Assembly);
services.AddSingleton<IFileProvider>(embeddedProvider);

Service lifetimes

Choosing the correct service lifetime is critical for application stability, performance, and correctness. The application primarily uses Singleton and Transient lifetimes.

Lifetime	Description	When to Use in This App	Examples
Singleton	A single instance of the service is created for the entire application lifetime. This instance is shared across all requests.	For services that are stateless or hold application-wide, immutable state. Also for services that are expensive to create and can be safely shared.	IHttpContextAccessor, IViewLocalizer, IContentfulOptionsManager, IFileProvider, HttpClient (staging)
Scoped	A single instance is created per client request (per scope).	Not explicitly used in Startup.cs, but is the default for many framework services like Entity Framework's DbContext. It's the standard choice for services that need to maintain state within a single request.	(No direct examples in custom registrations)
Transient	A new instance is created every time the service is requested from the DI container.	For lightweight, stateless services, or for services whose state is request-specific and must be initialized at the moment of injection.	IContentfulClient, IVisitedLessonsManager, IBreadcrumbsManager

Singleton vs. Transient Patterns

The application demonstrates key patterns for using these lifetimes effectively:

1. Expensive Initialization -> Singleton: JsonViewLocalizer reads and parses multiple files on creation. Making it a Singleton ensures this work is only done once at startup, improving performance on subsequent requests.

2. Request-Specific State -> Transient: VisitedLessonsManager and BreadcrumbsManager both derive their initial state from the incoming HttpContext (cookies and items, respectively). A Transient lifetime guarantees that a fresh instance, initialized with the current request's data, is provided whenever the service is injected. If they were Singleton, they would be initialized with data from the very first request to the application and would never be updated.

3. Dynamic Dependencies -> Transient: IContentfulClient is registered as Transient because its configuration can change with every request, based on the session. The custom factory ensures that each time a client is needed, it is created with the correct credentials for the current user context, as determined by the IContentfulOptionsManager.