Dependency Injection

Overview

This document details the use of the Dependency Injection (DI) design pattern within TheExampleApp. DI is a core architectural principle of ASP.NET Core, used to achieve Inversion of Control (IoC) between classes and their dependencies. This promotes loose coupling, making the application more modular, maintainable, and easier to test.

In this application, DI is managed by the built-in services container. Services are registered with the container during application startup, and the container is then responsible for creating instances of these services and injecting them into dependent classes, such as Razor Page Models, middleware, and other services.

For a higher-level view of the application's structure, please see the Architecture Overview.

DI in ASP.NET Core

The application leverages the native DI container provided by the ASP.NET Core framework. The central point of configuration for the DI container is the ConfigureServices method within the Startup.cs class.

// In TheExampleApp/Startup.cs

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // Service registrations go here...
}

Any class that requires a dependency simply declares it as a parameter in its constructor. The DI container resolves the dependency graph at runtime, automatically providing the required instances.

Service Registration

All services, whether from the framework, third-party libraries, or custom application code, must be registered in ConfigureServices. The application registers several key services to support its functionality.

The following is a breakdown of the most important registrations in Startup.cs:

// In TheExampleApp/Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    // Provides access to the current HttpContext from within services.
    services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();

    // Registers the default Contentful services, including a default IContentfulClient.
    services.AddContentful(Configuration);

    // In staging environments, registers a custom HttpClient with a message handler
    // that redirects Contentful API requests to a staging host.
    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);
            });
        }
    }

    // Registers a custom manager for dynamically providing Contentful options.
    services.AddSingleton<IContentfulOptionsManager, ContentfulOptionsManager>();

    // Re-registers the IContentfulClient with a custom factory to enable runtime credential switching.
    services.AddTransient<IContentfulClient, ContentfulClient>((ip) => {
        var client = ip.GetService<HttpClient>();
        var options = ip.GetService<IContentfulOptionsManager>().Options;
        var contentfulClient = new ContentfulClient(client, options);
        // Sets custom application identifier for analytics
        var version = typeof(Startup).GetTypeInfo().Assembly
            .GetCustomAttribute<AssemblyInformationalVersionAttribute>()
            .InformationalVersion;
        contentfulClient.Application = $"app the-example-app.csharp/{version}; {contentfulClient.Application}";
        return contentfulClient;
    });

    // Registers custom application services.
    services.AddSingleton<IViewLocalizer, JsonViewLocalizer>();
    services.AddTransient<IVisitedLessonsManager, VisitedLessonsManager>();
    services.AddTransient<IBreadcrumbsManager, BreadcrumbsManager>();

    // Registers MVC services with custom Razor Pages routing.
    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}");
    });

    // Configures session state with extended idle timeout.
    services.AddSession(options => {
        options.IdleTimeout = TimeSpan.FromDays(2);
    });

    // Registers embedded file provider for accessing embedded locale resources.
    var embeddedProvider = new EmbeddedFileProvider(GetType().GetTypeInfo().Assembly);
    services.AddSingleton<IFileProvider>(embeddedProvider);
}

Notable Registrations

Custom IContentfulClient Factory: While services.AddContentful() provides a default client, this application overrides it to inject a client that sources its configuration from our custom IContentfulOptionsManager. This allows the app to switch Contentful spaces and API keys at runtime based on session data, a key feature for the settings page. The factory also sets a custom application identifier that includes the app version for Contentful analytics.

Staging Environment HttpClient: In staging environments (detected via CurrentEnvironment.IsStaging()), the application registers a custom HttpClient with a StagingMessageHandler. This handler intercepts requests to Contentful and redirects them to a staging host specified by the StagingHost environment variable, enabling testing against alternative Contentful environments.

Embedded File Provider: An EmbeddedFileProvider is registered to provide access to embedded locale resource files (such as en-US.json and de-DE.json) that are compiled into the assembly. This supports the application's internationalization features.

For more details on the services themselves, see the Services Configuration documentation.

Service Lifetimes

When registering a service, a lifetime must be specified. The lifetime dictates when and how instances of the service are created and disposed of. The application uses all three standard lifetimes:

Lifetime	Description	Application Examples
Singleton	A single instance of the service is created for the entire application lifetime. Every subsequent request for the service receives the same instance.	IContentfulOptionsManager, IViewLocalizer, IHttpContextAccessor, HttpClient (in staging), IFileProvider. These are suitable as singletons because they either hold global state or provide access to request-specific context in a safe way.
Scoped	A new instance is created once per client request (connection). The same instance is provided throughout the entire scope of that single request.	The Breadcrumbs middleware, while not a service itself, has its dependencies resolved within a request scope. Many framework services like DbContext (if used) are typically scoped.
Transient	A new instance is created every time the service is requested from the container. This is ideal for lightweight, stateless services.	IContentfulClient, IVisitedLessonsManager, IBreadcrumbsManager. These services are registered as transient to ensure they receive the most up-to-date dependencies (like HttpContext) for each injection, preventing state conflicts between different parts of a single request.

Custom Services

The application defines several custom services to encapsulate specific business logic. These are registered with the DI container and consumed throughout the application.

IContentfulOptionsManager

This service is a cornerstone of the application's dynamic Contentful integration. Its purpose is to provide ContentfulOptions (Space ID, API keys) that can be sourced from either the appsettings.json configuration or the user's current Session. This enables the "Try the API" feature where a user can input their own credentials.

The implementation relies on IHttpContextAccessor to check the session for custom options before falling back to the default configuration.

// In 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; // Default options from config
        _accessor = accessor;
    }

    public ContentfulOptions Options
    {
        get {
            // Check session for custom options
            var sessionString = _accessor.HttpContext.Session.GetString(nameof(ContentfulOptions));

            if (!string.IsNullOrEmpty(sessionString))
            {
                // If found, deserialize and return them
                return JsonConvert.DeserializeObject<ContentfulOptions>(sessionString);
            }
            // Otherwise, return the default options
            return _options;
        }
    }

    public bool IsUsingCustomCredentials
    {
        get
        {
            var sessionString = _accessor.HttpContext.Session.GetString(nameof(ContentfulOptions));

            if (string.IsNullOrEmpty(sessionString))
            {
                return false;
            }

            var options = JsonConvert.DeserializeObject<ContentfulOptions>(sessionString);

            // Returns true if any of the session options differ from default configuration
            return (options.SpaceId == _options.SpaceId &&
                options.UsePreviewApi == _options.UsePreviewApi &&
                options.DeliveryApiKey == _options.DeliveryApiKey &&
                options.PreviewApiKey == _options.PreviewApiKey) == false;
        }
    }
}

Further details on this integration can be found in the Contentful Integration document.

IBreadcrumbsManager

This transient service provides a way for Razor Pages to modify the breadcrumbs that are automatically generated by the Breadcrumbs middleware. The middleware creates a list of breadcrumbs based on the URL path and stores it in HttpContext.Items. The BreadcrumbsManager accesses this list via IHttpContextAccessor and provides methods to manipulate it.

// In TheExampleApp/Configuration/Breadcrumbs.cs
public class BreadcrumbsManager : IBreadcrumbsManager
{
    private readonly IHttpContextAccessor _accessor;
    private List<Breadcrumb> _crumbs;

    public BreadcrumbsManager(IHttpContextAccessor accessor)
    {
        _accessor = accessor;
        // Retrieves the breadcrumb list generated by the middleware for the current request.
        _crumbs = accessor.HttpContext.Items["breadcrumbs"] as List<Breadcrumb>;
    }

    public void ReplaceCrumbForSlug(string slug, string label)
    {
        // Searches for a breadcrumb with a matching label (the slug parameter represents the current label to find)
        if(_crumbs.Any(c => c.Label == slug))
        {
            _crumbs.First(c => c.Label == slug).Label = label;
        }
    }
}

IVisitedLessonsManager

This transient service is responsible for tracking which course lessons a user has visited. It uses browser cookies for persistence across sessions. It depends on IHttpContextAccessor to read from the request cookies during initialization and to write to the response cookies when a new lesson is marked as visited.

The visited lessons are stored in a cookie named ContentfulVisitedLessons as a semicolon-delimited list of lesson IDs. The cookie is set to expire after 7 days and is marked as HTTP-only for security.

// In TheExampleApp/Configuration/VisitedLessons.cs
public class VisitedLessonsManager: IVisitedLessonsManager
{
    private readonly string _key = "ContentfulVisitedLessons";
    private readonly IHttpContextAccessor _accessor;

    public List<string> VisitedLessons { get; private set; }

    public VisitedLessonsManager(IHttpContextAccessor accessor)
    {
        VisitedLessons = new List<string>();
        _accessor = accessor;
        // Reads the cookie from the current request to initialize the list of visited lessons.
        var cookie = _accessor.HttpContext.Request.Cookies[_key];
        if (!string.IsNullOrEmpty(cookie))
        {
            VisitedLessons = new List<string>(cookie.Split(';', StringSplitOptions.RemoveEmptyEntries));
        }
    }

    public void AddVisitedLesson(string lessonId)
    {
        VisitedLessons.Add(lessonId);
        var options = new CookieOptions();
        options.HttpOnly = true;
        options.Expires = DateTime.Now.AddDays(7);
        // Appends a cookie to the current response with distinct lesson IDs.
        _accessor.HttpContext.Response.Cookies.Append(_key, string.Join(';', VisitedLessons.Distinct()), options);
    }
}

Constructor Injection

The primary mechanism for consuming registered services is constructor injection. The DI container supplies the necessary service instances when creating an object. This pattern is used extensively in Razor Page Models and custom services.

Example: Injecting IContentfulClient into a Page Model

The IndexModel requires an IContentfulClient to fetch content from the CMS. It declares this dependency in its constructor, and the framework provides it automatically.

// In TheExampleApp/Pages/Index.cshtml.cs
public class IndexModel : BasePageModel
{
    // The _client field is inherited from BasePageModel
    // private readonly IContentfulClient _client;

    public IndexModel(IContentfulClient client) : base(client)
    {
        // The 'client' instance is provided by the DI container.
        // The base constructor assigns it to the _client field.
    }

    public async Task OnGet()
    {
        // The injected client is now available for use.
        var indexPage = (await _client.GetEntries(/* ... */)).FirstOrDefault();
        // ...
    }
}

This pattern is also used by View Components, which also support constructor injection.

IHttpContextAccessor

The IHttpContextAccessor is a critical service in this application, enabling access to the HttpContext of the current request from within services that are not direct components of the request pipeline (e.g., middleware).

It is registered as a singleton in Startup.cs:

services.TryAddSingleton<IHttpContextAccessor, HttpContextAccessor>();

Usage and Considerations

Several custom services (ContentfulOptionsManager, BreadcrumbsManager, VisitedLessonsManager) depend on IHttpContextAccessor to access request-specific data like session state, cookies, and HttpContext.Items.

Important: While IHttpContextAccessor itself is a singleton, the HttpContext property it exposes is tied to the current asynchronous context. This means that when accessing _accessor.HttpContext, you are always getting the context for the request currently being processed on that thread.

Gotcha: It is an anti-pattern to store the result of _accessor.HttpContext in a field of a singleton service. This can lead to capturing a stale HttpContext from a previous request. The correct pattern, as used in this application, is to access the HttpContext property directly within the method or property where it is needed.

Correct Usage Example:

// In TheExampleApp/Configuration/ContentfulOptionsManager.cs

// The accessor is stored, not the HttpContext itself.
private readonly IHttpContextAccessor _accessor;

public ContentfulOptions Options
{
    get {
        // HttpContext is accessed here, ensuring it's the one for the current request.
        var sessionString = _accessor.HttpContext.Session.GetString(nameof(ContentfulOptions));
        // ...
    }
}