Blog posts by Ethan Schofer

Managing Your Graph Conventions

Tue, 31 Dec 2024 16:58:12 GMT

UPDATE

With the latest Graph NuGet packages (3.14.3) they have made a lot of the functionality of the ConventionRepository internal. Specifically, it contains some collections. There is currently no way to instantiate these, even with some sort of mock or substitute. So, for the time being, the unit test section of this article will not work.

Recently, Optimizely released a Conventions API for manging how various fields on your CMS content are indexed by the Graph. This is an extremely useful update as it allows us to much more easily manage what gets indexed and how it gets indexed: https://docs.developers.optimizely.com/content-management-system/docs/conventions-api.

Generally speaking, you manage this in the application Configure method in Startup.cs. According to the documentation, you create a service scope, get the conventions repository, and configure the fields on a given block or page.

using (var serviceScope = app.ApplicationServices.CreateScope())
{
var services = serviceScope.ServiceProvider;
var conventionRepo = services.GetRequiredService<ConventionRepository>();
conventionRepo.ForInstancesOf<StandardPage>()
.ExcludeField(p => p.ContentAreaItem1) //exclude a field
.IncludeField(p => p.TermsAndConditions()) //add a dynamic field
//set indexing type for specific properties
.Set(p => p.Price, IndexingType.Queryable)
.Set(p => p.Heading, IndexingType.Searchable)
.Set(p => p.Quantity, IndexingType.OnlyStored);

conventionRepo.ExcludeContentType<StartPage>(); //exclude specific content types

conventionRepo.ExcludeAllContentTypes() //exclude all content types except a few
.Except<OrderBlock>();

conventionRepo
.IncludeAbstract<MyAbstractPage2>() //add interface and abstract types to schema
.IncludeAbstract<MyAbstractPage>()
.IncludeInterface<ISearchPage>();
}

And this is excellent functionality. Fine grained control over my Graph indexing.

The problem arises when we start to think of this in the context of a large site. Are we going to add hundreds of lines of code to our Startup.cs? Do we have to touch Startup.cs each time we want to adjust our conventions? This all seems like a maintenance issue. We want to make this whiole process much easier to maintain. Specifically:

Our code is organized in feature folders. Can we organize our conventions in this way as well?
How can we add new pages or blocks, as well as the relevant conventions, without having to touch a whole bunch of code every time?
How can we adjust existing pages or blocks and their relevant conventions and ensure our changes don't break anything?

Our initial idea was to manage these conventions similar to how Entity Framework manages conventions (https://learn.microsoft.com/en-us/ef/core/modeling/) using IEntityTypeConfiguration. We want our convention classes to be pulled into the Graph conventions automatically, so that if we make a new file of conventions, it will automatically be included, and we dont have to worry about missing a step.

Create an Interface

The first step is to create an interface that all of my conventions will use. Then we can do some work on any class that implements this interface.

/// <summary>
/// Interface for conventions for each type
/// </summary>
public interface IGraphTypeConventions
{
/// <summary>
/// Method for adding the conventions
/// </summary>
/// <param name="conventionRepository">The graph conventions repository</param>
public void Configure(ConventionRepository conventionRepository);
}

Any class we create that contains conventions must implement this interface. An example implementaion might look like this:

/// <summary>
/// Conventions for the accordion blocks
/// </summary>
public class AccordionGraphConventions : IGraphTypeConventions
{
/// <summary>
/// Adds conventions for the accordion blocks
/// </summary>
/// <param name="conventionRepository">The conventions repository</param>
public void Configure(ConventionRepository conventionRepository)
{
// Ensure we have the repository
ArgumentNullException.ThrowIfNull(conventionRepository);

// Configure the accordion grouping block
conventionRepository?.ForInstancesOf<AccordionGroupingBlock>()?
.Set(p => p.Title, IndexingType.Searchable)
.Set(p => p.Description, IndexingType.OnlyStored)
.Set(p => p.IsFaq, IndexingType.Queryable)
.Set(p => p.Items, IndexingType.OnlyStored)
.ExcludeField(p => p.UniqueId);

// Configure the accordion item block
conventionRepository?.ForInstancesOf<AccordionItemBlock>()?
.Set(p => p.Title, IndexingType.Searchable)
.Set(p => p.Text, IndexingType.OnlyStored)
.ExcludeField(p => p.UniqueId);
}
}

Where we:

Check that we have the repository
Configure the AccordionGroupingBlock
Configure the AccordionItemBlock

In a large site, we would expect to have at least one implementation of IGraphTypeConventions for each feature.

Register Instances of the Interface

In Startup.cs, in ConfigureServices, we want to add all of our conventions to the Depdency Injection container. So, right after we configure the graph, we call a new ServiceCollection extension method called RegisterAllGraphConventions where we get the current assembly, get all implementations of IGraphConvention from the assembly, and add them to the DI container.

*Note: This is predicated on our architecture, where everything is in a single DLL. If your solution is spread out over multiple DLLs youi may need to adjust this to ensure you pick up all the IGraphTypeConventions.

/// <summary>
/// Extension method to register all graph convention classes
/// </summary>
public static class ServiceCollectionExtensions
{
/// <summary>
/// Register all instances of IGraphTypeConventions
/// </summary>
/// <param name="services"></param>
public static void RegisterAllGraphConventions(this IServiceCollection services)
{
// Get the current assembly - everything is in a single assembly - this aassembly
var currentAssembly = Assembly.GetExecutingAssembly();

// Get all graph convention classes from the assembly
var typesFromAssembly =
currentAssembly.DefinedTypes.Where(x => x.GetInterfaces().Contains(typeof(IGraphTypeConventions)));

// Loop through the types
foreach (var type in typesFromAssembly)
{
// Register them in the DI container
services.Add(new ServiceDescriptor(typeof(IGraphTypeConventions), type, ServiceLifetime.Transient));
}
}
}

The advantage here is that if we add new conventions, they will automatically get registered. We can then easily call this from Startup.cs:

// Add graph conventions to the DI container
services.RegisterAllGraphConventions();

Add Conventions to the Conventions Repository

Lastly, we want to actually add these conventions to the ConventionsRepository. We do this in the application Configure method in Startup.cs. We create an extention method on IApplicationBuilder that will actually perform the registeration. In that method, we get the service provider and then get the ConventionRepository, as described in their documentation. But then we get all instances of IGraphTypeConventions that we registered in the DI container, loop through all of them and call the Configure method on each instance.

/// <summary>
/// Application builder extensions to register all graph conventions
/// </summary>
public static class GraphConventions
{
/// <summary>
/// Add all graph conventions to the convention repository
/// </summary>
/// <param name="app"></param>
public static void AddGraphConventions(this IApplicationBuilder app)
{
// Get the scope
using var serviceScope = app.ApplicationServices.CreateScope();

// Get the service provider
var services = serviceScope.ServiceProvider;

// Get the convention repository
var conventionRepository = services.GetRequiredService<ConventionRepository>();

// If we don't have the repository
if (conventionRepository == null)
{
// Just move on
return;
}

// Get all the graph conventions
var graphConventions = services.GetAllInstances<IGraphTypeConventions>();

// Loop through the conventions
foreach (var graphConvention in graphConventions)
{
// Call the configure method on each graph convention
graphConvention.Configure(conventionRepository);
}
}
}

This will ensure that all conventions are registered, and it makes adding new conventions pretty easy. This would be added in Configure like this:

// Configure graph sync
app.AddGraphConventions();

Testing

Lastly, I want to be able to test these conventions so that if they get changed in the future, the test will fail until the test is also updated, ensuring we are adding conventions correctly. For testing, I am using XUnit, NSubstitute and FluentAssertions, so if you use different tools, the syntax of these tests may be different, but the concept should remain the same.

Create a Substitute of the ConventionsRepository
Create an instance of you conventions class
Call the configure method
Get the field conventions for this particular content type
Review the conventions

[Fact]
public void Configure_ConfigureAccordionGroupingBlock_ConfigurationIsSet()
{
// Arrange
var conventionRepository = Substitute.For<ConventionRepository>();
var accordionGraphConventions = new AccordionGraphConventions();

// Act
accordionGraphConventions.Configure(conventionRepository);

// Assert
var fieldConventions = conventionRepository.GetFieldConventions(typeof(AccordionGroupingBlock));

foreach (var conventionType in fieldConventions)
{
var excludedFields = conventionType.GetExcludedFields();
var excludedFieldsArray = excludedFields as string[] ?? excludedFields.ToArray();
excludedFieldsArray.Length.Should().Be(1);
excludedFieldsArray.FirstOrDefault().Should().Be(nameof(AccordionGroupingBlock.UniqueId));

var indexedFields = conventionType.GetFieldsWithIndexingSetting();
var indexedFieldsArray = indexedFields as string[] ?? indexedFields.ToArray();
indexedFieldsArray.Length.Should().Be(4);
indexedFieldsArray.Should().Contain(nameof(AccordionGroupingBlock.Title));
indexedFieldsArray.Should().Contain(nameof(AccordionGroupingBlock.Description));
indexedFieldsArray.Should().Contain(nameof(AccordionGroupingBlock.IsFaq));
indexedFieldsArray.Should().Contain(nameof(AccordionGroupingBlock.Items));

conventionType.GetIndexingType(nameof(AccordionGroupingBlock.Title)).Should().Be(IndexingType.Searchable);
conventionType.GetIndexingType(nameof(AccordionGroupingBlock.Description)).Should().Be(IndexingType.OnlyStored);
conventionType.GetIndexingType(nameof(AccordionGroupingBlock.IsFaq)).Should().Be(IndexingType.Queryable);
conventionType.GetIndexingType(nameof(AccordionGroupingBlock.Items)).Should().Be(IndexingType.OnlyStored);
}
}

So, we can bu sure that any of the following will break the test, requring you to examine your changes to ensure they are correct:

Changing the number and/or field that is excluded from convetions
Change the number and/or field included in conventions
Change the indexing type for a given field

Conclusions

All in all, the Conventions API is a nice feature from Optimizely to help us manage how the Graph indexes our content. Using the mthod outlined above will result in easy to maintain conventions that scale along with your solution.

Roll Your Own Security Headers

Wed, 21 Feb 2024 19:49:23 GMT

Proper security headers are a must for your Optimizely driven website. There are a variety of tools out there that will help with this, but when possible I prefer to roll my own solution, especially for such a low level feature as security headers. No need to keep a NuGet package up to date. No need to worry about constant version updates. Its all self contained in the code base that I control. I have done this with some custom middleware that can be set up in Startup.cs. The headers this could add include:

X-Content-Type-Options
X-Frame-Options
Server
Strict-Transport-Security
X-XSS-Protection
Referrer-Policy
Permissions-Policy
Content-Security-Policy
X-Download-Options

The first thing I need to do is create some constants classes that contain all the header names and values I will need. Each class contains a string of the header name and strings of any options. Content Security Policy and Permissions Policy, being a little more complex, also needs a enum to cover some options.

X-Content-Type-Options

/// <summary>
/// X-Content-Type-Options-related constants.
/// </summary>
public static class ContentTypeOptionsConstants
{
    /// <summary>
    /// Header value for X-Content-Type-Options
    /// </summary>
    public static readonly string Header = "X-Content-Type-Options";

    /// <summary>
    /// Disables content sniffing
    /// </summary>
    public static readonly string NoSniff = "nosniff";
}

In this case I only have the nosniff options because that is what I will be using.

X-Frame-Options

/// <summary>
/// X-Frame-Options-related constants.
/// </summary>
public static class FrameOptionsConstants
{
    /// <summary>
    /// The header value for X-Frame-Options
    /// </summary>
    public static readonly string Header = "X-Frame-Options";

    /// <summary>
    /// The page cannot be displayed in a frame, regardless of the site attempting to do so.
    /// </summary>
    public static readonly string Deny = "DENY";

    /// <summary>
    /// The page can only be displayed in a frame on the same origin as the page itself.
    /// </summary>
    public static readonly string SameOrigin = "SAMEORIGIN";

    /// <summary>
    /// The page can only be displayed in a frame on the specified origin. {0} specifies the format string
    /// </summary>
    public static readonly string AllowFromUri = "ALLOW-FROM {0}";
}

Server

/// <summary>
/// Server headery-related constants.
/// </summary>
public static class ServerConstants
{
    /// <summary>
    /// The header value for X-Powered-By
    /// </summary>
    public static readonly string Header = "Server";
}

Strict-Transportat-Security

/// <summary>
/// Strict-Transport-Security-related constants.
/// </summary>
public static class StrictTransportSecurityConstants
{
    /// <summary>
    /// Header value for Strict-Transport-Security
    /// </summary>
    public static readonly string Header = "Strict-Transport-Security";

    /// <summary>
    /// Tells the user-agent to cache the domain in the STS list for the provided number of seconds {0} 
    /// </summary>
    public static readonly string MaxAge = "max-age={0}";

    /// <summary>
    /// Tells the user-agent to cache the domain in the STS list for the provided number of seconds {0} and include any subdomains.
    /// </summary>
    public static readonly string MaxAgeIncludeSubdomains = "max-age={0}; includeSubDomains";

    /// <summary>
    /// Tells the user-agent to remove, or not cache the host in the STS cache.
    /// </summary>
    public static readonly string NoCache = "max-age=0";
}

X-XSS-Protection

/// <summary>
/// X-XSS-Protection-related constants.
/// </summary>
public static class XssProtectionConstants
{
    /// <summary>
    /// Header value for X-XSS-Protection
    /// </summary>
    public static readonly string Header = "X-XSS-Protection";

    /// <summary>
    /// Enables the XSS Protections
    /// </summary>
    public static readonly string Enabled = "1";

    /// <summary>
    /// Disables the XSS Protections offered by the user-agent.
    /// </summary>
    public static readonly string Disabled = "0";

    /// <summary>
    /// Enables XSS protections and instructs the user-agent to block the response in the event that script has been inserted from user input, instead of sanitizing.
    /// </summary>
    public static readonly string Block = "1; mode=block";

    /// <summary>
    /// A partially supported directive that tells the user-agent to report potential XSS attacks to a single URL. Data will be POST'd to the report URL in JSON format. 
    /// {0} specifies the report url, including protocol
    /// </summary>
    public static readonly string Report = "1; report={0}";
}

Referrer-Policy

/// <summary>
/// Referrer Policy related constants
/// </summary>
public static class ReferrerPolicyConstants
{
    /// <summary>
    /// Header value for Referrer-Policy
    /// </summary>
    public static readonly string Header = "Referrer-Policy";

    public static readonly string NoReferrer = "no-referrer";

    public static readonly string NoReferrerWhenDowngrade = "no-referrer-when-downgrade";

    public static readonly string SameOrigin = "same-origin";

    public static readonly string Origin = "origin";

    public static readonly string StrictOrigin = "strict-origin";

    public static readonly string OriginWhenCrossOrigin = "origin-when-cross-origin";

    public static readonly string StrictOriginWhenCrossOrigin = "strict-origin-when-cross-origin";

    public static readonly string UnsafeUrl = "unsafe-url";
}

Permissions-Policy

/// <summary>
/// Permissions Policy related constants
/// </summary>
public static class PermissionsPolicyConstants
{
    /// <summary>
    /// Header value for Permissions-Policy
    /// </summary>
    public static readonly string Header = "Permissions-Policy";
}

When setting permissions policy, there are a variety of functions that you can set permissions for. The various functions I have put into an enum:

/// <summary>
/// Enum of some permission policies
/// </summary>
public enum PermissionPolicy
{
    [EnumSelectionDescription(Text = "Accelerometer", Value = "accelerometer")]
    Accelerometer = 1,

    [EnumSelectionDescription(Text = "Camera", Value = "camera")]
    Camera = 2,

    [EnumSelectionDescription(Text = "Geolocation", Value = "")]
    Geolocation = 3,

    [EnumSelectionDescription(Text = "Gyroscope", Value = "gyroscope")]
    Gyroscope = 4,

    [EnumSelectionDescription(Text = "Magnetometer", Value = "magnetometer")]
    Magnetometer = 5,

    [EnumSelectionDescription(Text = "Microphone", Value = "microphone")]
    Microphone = 6,

    [EnumSelectionDescription(Text = "Payment", Value = "payment")]
    Payment = 7,

    [EnumSelectionDescription(Text = "Usb", Value = "usb")]
    Usb = 8
}

Content-Security-Policy

/// <summary>
/// Permissions Policy related constants
/// </summary>
public static class ContentSecurityPolicyConstants
{
    /// <summary>
    /// Header value for Permissions-Policy
    /// </summary>
    public static readonly string Header = "Content-Security-Policy";

}

Content Security Policy needs to be set for a variety of types of content. I control these with an enum also:

public enum ContentSecurityPolicy
{
    [EnumSelectionDescription(Text = "DefaultSource", Value = "default-src 'self'")]
    DefaultSource = 1,

    [EnumSelectionDescription(Text = "ConnectSource", Value = " connect-src * 'self' data: https:")]
    ConnectSource = 2,

    [EnumSelectionDescription(Text = "FontSource", Value = " font-src 'self' data: https:")]
    FontSource = 3,

    [EnumSelectionDescription(Text = "FrameSource", Value = " frame-src 'self' data: https:")]
    FrameSource = 4,

    [EnumSelectionDescription(Text = "ImageSource", Value = "  img-src * 'self' data: https: blob:")]
    ImageSource = 5,

    [EnumSelectionDescription(Text = "ScriptSource", Value = " script-src 'self' 'nonce-{nonceValue}' 'strict-dynamic' ")]
    ScriptSource = 6,

    [EnumSelectionDescription(Text = "StyleSource", Value = " style-src 'self' 'unsafe-inline' *")]
    StyleSource = 7,

    [EnumSelectionDescription(Text = "FormAction", Value = " form-action 'self' data: https:")]
    FormAction = 8,

    [EnumSelectionDescription(Text = "MediaSource", Value = " media-src 'self' data: https: blob:")]
    MediaSource = 9
}

X-Download-Options

/// <summary>
/// Permissions Policy related constants
/// </summary>
public static class XDownloadOptionsConstants
{
    /// <summary>
    /// Header value for Permissions-Policy
    /// </summary>
    public static readonly string Header = "X-Download-Options";

    public static readonly string NoOpen = "noopen";
}

The real work I do is in a builder class, SecurityHeadersBuilder. This builder has a variety of methods for setting the different header values. I then create a method that builds up the security policy. You could conceptually have a variety of policies. I only need one, so I have a default method that creates all of my headers. It stores them in a policy class.

First the policy class. Its pretty straight forward, it just has an add and remove method for setting headers.

/// <summary>
/// The security headers policy
/// </summary>
public class SecurityHeadersPolicy
{
    /// <summary>
    /// Headers to add
    /// </summary>
    public IDictionary<string, string> SetHeaders { get; }
        = new Dictionary<string, string>();

    /// <summary>
    /// Headers to remove
    /// </summary>
    public ISet<string> RemoveHeaders { get; }
        = new HashSet<string>();
}

It stores these values in a dictionary.

The builder then adds the headers to this policy:

/// <summary>
/// Middle ware to create the desired security headers
/// </summary>
public class SecurityHeadersBuilder
{
    private readonly SecurityHeadersPolicy _policy = new();

    /// <summary>
    /// The number of seconds in one year
    /// </summary>
    public const int OneYearInSeconds = 60 * 60 * 24 * 365;

    private CompositeFormat FrameOptionsAllowFromUri { get; set; } = CompositeFormat.Parse(FrameOptionsConstants.AllowFromUri);

    private CompositeFormat XssProtectionConstantsReport { get; set; } = CompositeFormat.Parse(XssProtectionConstants.Report);

    private CompositeFormat StrictTransportSecurityConstantsMaxAge { get; set; } = CompositeFormat.Parse(StrictTransportSecurityConstants.MaxAge);

    private CompositeFormat StrictTransportSecurityConstantsMaxAgeIncludeSubdomains { get; set; } = CompositeFormat.Parse(StrictTransportSecurityConstants.MaxAgeIncludeSubdomains);

    /// <summary>
    /// Add default headers in accordance with most secure approach
    /// </summary>
    public SecurityHeadersBuilder AddDefaultSecurePolicy()
    {
        this.AddXssProtectionBlock();
        this.AddStrictTransportSecurityMaxAge();
        this.AddPermissionsPolicy();
        this.AddXssProtectionBlock();
        this.AddContentTypeOptionsNoSniff();
        this.AddReferrerPolicyStrictOriginWhenCrossOrigin();
        this.AddXDownloadOptionsNoOpen();

        return this;
    }

    /// <summary>
    /// Add X-Frame-Options DENY to all requests.
    /// The page cannot be displayed in a frame, regardless of the site attempting to do so
    /// </summary>
    public SecurityHeadersBuilder AddFrameOptionsDeny()
    {
        this._policy.SetHeaders[FrameOptionsConstants.Header] = FrameOptionsConstants.Deny;
        return this;
    }

    /// <summary>
    /// Add X-Frame-Options SAMEORIGIN to all requests.
    /// The page can only be displayed in a frame on the same origin as the page itself.
    /// </summary>
    public SecurityHeadersBuilder AddFrameOptionsSameOrigin()
    {
        this._policy.SetHeaders[FrameOptionsConstants.Header] = FrameOptionsConstants.SameOrigin;
        return this;
    }

    /// <summary>
    /// Add X-Frame-Options ALLOW-FROM {uri} to all requests, where the uri is provided
    /// The page can only be displayed in a frame on the specified origin.
    /// </summary>
    /// <param name="uri">The uri of the origin in which the page may be displayed in a frame</param>
    public SecurityHeadersBuilder AddFrameOptionsSameOrigin(string uri)
    {
        this._policy.SetHeaders[FrameOptionsConstants.Header] = string.Format(CultureInfo.InvariantCulture, this.FrameOptionsAllowFromUri, uri);
        return this;
    }


    /// <summary>
    /// Add X-XSS-Protection 1 to all requests.
    /// Enables the XSS Protections
    /// </summary>
    public SecurityHeadersBuilder AddXssProtectionEnabled()
    {
        this._policy.SetHeaders[XssProtectionConstants.Header] = XssProtectionConstants.Enabled;
        return this;
    }

    /// <summary>
    /// Add X-XSS-Protection 0 to all requests.
    /// Disables the XSS Protections offered by the user-agent.
    /// </summary>
    public SecurityHeadersBuilder AddXssProtectionDisabled()
    {
        this._policy.SetHeaders[XssProtectionConstants.Header] = XssProtectionConstants.Disabled;
        return this;
    }

    /// <summary>
    /// Add X-XSS-Protection 1; mode=block to all requests.
    /// Enables XSS protections and instructs the user-agent to block the response in the event that script has been inserted from user input, instead of sanitizing.
    /// </summary>
    public SecurityHeadersBuilder AddXssProtectionBlock()
    {
        this._policy.SetHeaders[XssProtectionConstants.Header] = XssProtectionConstants.Block;
        return this;
    }

    /// <summary>
    /// Add X-XSS-Protection 1; report=http://site.com/report to all requests.
    /// A partially supported directive that tells the user-agent to report potential XSS attacks to a single URL. Data will be POST'd to the report URL in JSON format.
    /// </summary>
    public SecurityHeadersBuilder AddXssProtectionReport(string reportUrl)
    {
        this._policy.SetHeaders[XssProtectionConstants.Header] =
            string.Format(CultureInfo.InvariantCulture, this.XssProtectionConstantsReport, reportUrl);
        return this;
    }

    /// <summary>
    /// Add Strict-Transport-Security max-age=<see cref="maxAge"/> to all requests.
    /// Tells the user-agent to cache the domain in the STS list for the number of seconds provided.
    /// </summary>
    public SecurityHeadersBuilder AddStrictTransportSecurityMaxAge(int maxAge = OneYearInSeconds)
    {
        this._policy.SetHeaders[StrictTransportSecurityConstants.Header] =
            string.Format(CultureInfo.InvariantCulture, this.StrictTransportSecurityConstantsMaxAge, maxAge);
        return this;
    }

    /// <summary>
    /// Add Strict-Transport-Security max-age=<see cref="maxAge"/>; includeSubDomains to all requests.
    /// Tells the user-agent to cache the domain in the STS list for the number of seconds provided and include any subdomains.
    /// </summary>
    public SecurityHeadersBuilder AddStrictTransportSecurityMaxAgeIncludeSubDomains(int maxAge = OneYearInSeconds)
    {
        this._policy.SetHeaders[StrictTransportSecurityConstants.Header] =
            string.Format(CultureInfo.InvariantCulture, this.StrictTransportSecurityConstantsMaxAgeIncludeSubdomains, maxAge);
        return this;
    }

    /// <summary>
    /// Add Strict-Transport-Security max-age=0 to all requests.
    /// Tells the user-agent to remove, or not cache the host in the STS cache
    /// </summary>
    public SecurityHeadersBuilder AddStrictTransportSecurityNoCache()
    {
        this._policy.SetHeaders[StrictTransportSecurityConstants.Header] =
            StrictTransportSecurityConstants.NoCache;
        return this;
    }

    /// <summary>
    /// Add X-Content-Type-Options nosniff to all requests.
    /// Can be set to protect against MIME type confusion attacks.
    /// </summary>
    public SecurityHeadersBuilder AddContentTypeOptionsNoSniff()
    {
        this._policy.SetHeaders[ContentTypeOptionsConstants.Header] = ContentTypeOptionsConstants.NoSniff;
        return this;
    }

    /// <summary>
    /// Removes the Server header from all responses
    /// </summary>
    public SecurityHeadersBuilder RemoveServerHeader()
    {
        this._policy.RemoveHeaders.Add(ServerConstants.Header);
        return this;
    }

    /// <summary>
    /// Add the XDownload option headers
    /// </summary>
    /// <returns></returns>
    public SecurityHeadersBuilder AddXDownloadOptionsNoOpen()
    {
        this._policy.SetHeaders[XDownloadOptionsConstants.Header] = XDownloadOptionsConstants.NoOpen;
        return this;

    }

    /// <summary>
    /// Adds a custom header to all requests
    /// </summary>
    /// <param name="header">The header name</param>
    /// <param name="value">The value for the header</param>
    /// <returns></returns>
    public SecurityHeadersBuilder AddCustomHeader(string header, string value)
    {
        if (string.IsNullOrEmpty(header))
        {
            throw new ArgumentNullException(nameof(header));
        }

        this._policy.SetHeaders[header] = value;
        return this;
    }

    /// <summary>
    /// Remove a header from all requests
    /// </summary>
    /// <param name="header">The to remove</param>
    /// <returns></returns>
    public SecurityHeadersBuilder RemoveHeader(string header)
    {
        if (string.IsNullOrEmpty(header))
        {
            throw new ArgumentNullException(nameof(header));
        }

        this._policy.RemoveHeaders.Add(header);
        return this;
    }

    /// <summary>
    /// Add referrer policy header of NoReferrer
    /// </summary>
    /// <returns></returns>
    public SecurityHeadersBuilder AddReferrerPolicyNoReferrer()
    {
        this._policy.SetHeaders[ReferrerPolicyConstants.Header] = ReferrerPolicyConstants.NoReferrer;
        return this;
    }

    /// <summary>
    /// Add referrer policy header of NoReferrer
    /// </summary>
    /// <returns></returns>
    public SecurityHeadersBuilder AddReferrerPolicyStrictOriginWhenCrossOrigin()
    {
        this._policy.SetHeaders[ReferrerPolicyConstants.Header] = ReferrerPolicyConstants.StrictOriginWhenCrossOrigin;
        return this;
    }

    /// <summary>
    /// Add the permissions policy
    /// </summary>
    /// <returns></returns>
    public SecurityHeadersBuilder AddPermissionsPolicy()
    {
        // Get all permissions policies
        var permissionPolicies = Enum.GetValues<PermissionPolicy>();

        // Loop through the policies
        var policy = (from permissionPolicy in permissionPolicies
                      select permissionPolicy.Value() into value
                      where !string.IsNullOrEmpty(value)
                      select $"{value}=()").ToList();

        this._policy.SetHeaders[PermissionsPolicyConstants.Header] = string.Join(',', policy.ToArray());
        return this;
    }

    /// <summary>
    /// Builds a new <see cref="SecurityHeadersPolicy"/> using the entries added.
    /// </summary>
    /// <returns>The constructed <see cref="SecurityHeadersPolicy"/>.</returns>
    public SecurityHeadersPolicy Build() => this._policy;
}

Breaking down whats happening here:

First I create the policy:

private readonly SecurityHeadersPolicy _policy = new();

Then I create a constant to store 1 year in seconds (For the Strinct Transport Security header, I set a max age, which should be a year)

/// <summary>
/// The number of seconds in one year
/// </summary>
public const int OneYearInSeconds = 60 * 60 * 24 * 365;

Next, I have a few header values that need string replacement. For each of these I create a CompositeFormat object by parsing the header value. Creating the CompositeFormat caches the parsing of this string, adding a small performance boost on subsequent calls. The replacement will happen later:

private CompositeFormat FrameOptionsAllowFromUri { get; set; } = CompositeFormat.Parse(FrameOptionsConstants.AllowFromUri);

private CompositeFormat XssProtectionConstantsReport { get; set; } = CompositeFormat.Parse(XssProtectionConstants.Report);

private CompositeFormat StrictTransportSecurityConstantsMaxAge { get; set; } = CompositeFormat.Parse(StrictTransportSecurityConstants.MaxAge);

private CompositeFormat StrictTransportSecurityConstantsMaxAgeIncludeSubdomains { get; set; } = CompositeFormat.Parse(StrictTransportSecurityConstants.MaxAgeIncludeSubdomains);

In this case, if you look above, you can see that FrameOptionsConstants.AllowFromUri equals "ALLOW-FROM {0}". When I set this header, I will replace '{0}' with the url.

Next I create a method for setting each header value. For example, for FrameOptions, I have three methods for setting the different values:

/// <summary>
/// Add X-Frame-Options DENY to all requests.
/// The page cannot be displayed in a frame, regardless of the site attempting to do so
/// </summary>
public SecurityHeadersBuilder AddFrameOptionsDeny()
{
    this._policy.SetHeaders[FrameOptionsConstants.Header] = FrameOptionsConstants.Deny;
    return this;
}

/// <summary>
/// Add X-Frame-Options SAMEORIGIN to all requests.
/// The page can only be displayed in a frame on the same origin as the page itself.
/// </summary>
public SecurityHeadersBuilder AddFrameOptionsSameOrigin()
{
    this._policy.SetHeaders[FrameOptionsConstants.Header] = FrameOptionsConstants.SameOrigin;
    return this;
}

/// <summary>
/// Add X-Frame-Options ALLOW-FROM {uri} to all requests, where the uri is provided
/// The page can only be displayed in a frame on the specified origin.
/// </summary>
/// <param name="uri">The uri of the origin in which the page may be displayed in a frame</param>
public SecurityHeadersBuilder AddFrameOptionsSameOrigin(string uri)
{
    this._policy.SetHeaders[FrameOptionsConstants.Header] = string.Format(CultureInfo.InvariantCulture, this.FrameOptionsAllowFromUri, uri);
    return this;
}

Each method sets the header to the desired value. Using the policy object I created, it adds the header using the constant of the header name from our constants classes, and then the constant of the desired value.

Removing the server header is common, so I have a specific method for this:

/// <summary>
/// Removes the Server header from all responses
/// </summary>
public SecurityHeadersBuilder RemoveServerHeader()
{
    this._policy.RemoveHeaders.Add(ServerConstants.Header);
    return this;
}

For permission policy, I want to allow all possible permissions of features, so I just iterate over the enum and add all the values.

/// <summary>
/// Add the permissions policy
/// </summary>
/// <returns></returns>
public SecurityHeadersBuilder AddPermissionsPolicy()
{
    // Get all permissions policies
    var permissionPolicies = Enum.GetValues<PermissionPolicy>();

    // Loop through the policies
    var policy = (from permissionPolicy in permissionPolicies
                  select permissionPolicy.Value() into value
                  where !string.IsNullOrEmpty(value)
                  select $"{value}=()").ToList();

    this._policy.SetHeaders[PermissionsPolicyConstants.Header] = string.Join(',', policy.ToArray());
    return this;
}

For your needs, you might need to create a different version of this method that only sets the permissions you need.

I have a specific method that creates our default policy:

/// <summary>
/// Add default headers in accordance with most secure approach
/// </summary>
public SecurityHeadersBuilder AddDefaultSecurePolicy()
{
    this.AddXssProtectionBlock();
    this.AddStrictTransportSecurityMaxAge();
    this.AddPermissionsPolicy();    
    this.AddContentTypeOptionsNoSniff();
    this.AddReferrerPolicyStrictOriginWhenCrossOrigin();
    this.AddXDownloadOptionsNoOpen();

    return this;
}

Here I am only calling the methods I want/need to make my policy. Notice Content Security Policy is missing here. I will come back to that.

Lastly I have a 'build' method that returns the policy:

/// <summary>
/// Builds a new <see cref="SecurityHeadersPolicy"/> using the entries added.
/// </summary>
/// <returns>The constructed <see cref="SecurityHeadersPolicy"/>.</returns>
public SecurityHeadersPolicy Build() => this._policy;

Middleware

The next piece I need is the actual middleware to create and use these headers. Middleware requires an invoke method that does the work. That is, it takes the policies created in the builder and adds them as actual headers. Additionally, this is where I add the Content Security Policy.

using System.Globalization;
using EPiServer.Framework.ClientResources;
using Hero.OptimizelyCMS.Foundation.Extensions;
using System.Web;
using Hero.OptimizelyCMS.Foundation.Utilities;

namespace Hero.OptimizelyCMS.Foundation.SecurityPolicy.SecurityMiddleware;

/// <summary>
/// Middleware for setting security headers
/// </summary>
public class SecurityHeadersMiddleware
{
    private readonly RequestDelegate _next;
    private readonly SecurityHeadersPolicy _policy;
    private readonly ICspNonceService _cspNonceService;

    public SecurityHeadersMiddleware(RequestDelegate next, SecurityHeadersPolicy policy, ICspNonceService cspNonceService)
    {
        this._next = next;
        this._policy = policy;
        this._cspNonceService = cspNonceService;
    }

    /// <summary>
    /// Add and remove desired headers
    /// </summary>
    /// <param name="context">The current HttpContext</param>
    /// <returns></returns>
    public async Task Invoke(HttpContext context)
    {
        // Get existing headers
        var headersDictionary = context.Response.Headers;

        // If we should add Csp
        if (ShouldAddCsp(context))
        {
            // Add CSP
            headersDictionary[ContentSecurityPolicyConstants.Header] = this.GetContentSecurityPolicy();

            // Frame options
            headersDictionary[FrameOptionsConstants.Header] = FrameOptionsConstants.SameOrigin;
        }

        // Loop through headers to add
        foreach (var headerValuePair in this._policy.SetHeaders)
        {
            // Add each header
            headersDictionary[headerValuePair.Key] = headerValuePair.Value;
        }

        // Loop through headers to remove
        foreach (var header in this._policy.RemoveHeaders)
        {
            // Remove the header
            headersDictionary.Remove(header);
        }

        await this._next(context);
    }

    /// <summary>
    /// Determine if we should add Csp
    /// </summary>
    /// <param name="context"></param>
    /// <returns></returns>
    private static bool ShouldAddCsp(HttpContext context)
    {
        // Get the current url
        var currentUrl = context.Request.Url();
        var path = currentUrl.PathAndQuery;
        var segments = path.Split('/', StringSplitOptions.RemoveEmptyEntries);

        // Get the first segment
        var segmentZero = segments.ElementAtOrDefault(0);

        // If there is no segment zero, we are on the home page
        if (string.IsNullOrEmpty(segmentZero))
        {
            return true;
        }

        // If the segment is one of these, we should not add CSP
        return segmentZero.ToLower(CultureInfo.InvariantCulture) switch
        {
            "error" => false,
            "episerver" => false,
            "util" => false,
            "cleaner" => false,
            "redirectmanager" => false,
            _ => true,
        };
    }

    /// <summary>
    /// Create the Csp
    /// </summary>
    /// <returns></returns>
    public string GetContentSecurityPolicy()
    {
        var policy = new List<string>();

        // Get Csp Enum values
        var contentSecurityPolicies = Enum.GetValues<ContentSecurityPolicy>();

        // Loop through each policy
        foreach (var contentSecurityPolicy in contentSecurityPolicies)
        {
            // Get the policy value
            var value = contentSecurityPolicy.Value();

            // Add the nonce to the policy
            if (string.IsNullOrEmpty(value))
            {
                continue;
            }

            var nonce = this._cspNonceService.GetNonce();
            nonce = HttpUtility.JavaScriptStringEncode(nonce);
            value = value.Replace("{nonceValue}", nonce);
            policy.Add(value);
        }

        // Return the policy
        return string.Join(';', policy.ToArray());
    }
}

And lets break down whats happening here:

I inject the RequestDelegate. This is how the middleware will move on to the next piece of middleware once done here. I add our header policy, and an instance of ICspNonceService, for adding a content security policy nonce (More on this in a bit) .

When Invoke is called, I get the current headers dictionary, I determine if I should add the Content Security Policy, and then I loop through all the appropriate headers in our policy and add them to the response, and remove any headers that should be removed.

I found that adding the Content Security Policy while inside the CMS broke a lot of CMS functionality. So I look at the path and I don't add the security policy if I am in the CMS. This includes the normal cms paths (episerver, util) as well as some custom urls for custom admin tools. You might need to include other paths, depending on any custom tools or third party add ons you have installed.

/// <summary>
/// Determine if we should add Csp
/// </summary>
/// <param name="context"></param>
/// <returns></returns>
private static bool ShouldAddCsp(HttpContext context)
{
    // Get the current url
    var currentUrl = context.Request.Url();
    var path = currentUrl.PathAndQuery;
    var segments = path.Split('/', StringSplitOptions.RemoveEmptyEntries);

    // Get the first segment
    var segmentZero = segments.ElementAtOrDefault(0);

    // If there is no segment zero, we are on the home page
    if (string.IsNullOrEmpty(segmentZero))
    {
        return true;
    }

    // If the segment is one of these, we should not add CSP
    return segmentZero.ToLower(CultureInfo.InvariantCulture) switch
    {
        "error" => false,
        "episerver" => false,
        "util" => false,
        "cleaner" => false,
        "redirectmanager" => false,
        _ => true,
    };
}

If I need to actually build the policy, I loop through the Enum I set up and add these values.

/// <summary>
/// Create the Csp
/// </summary>
/// <returns></returns>
public string GetContentSecurityPolicy()
{
    var policy = new List<string>();

    // Get Csp Enum values
    var contentSecurityPolicies = Enum.GetValues<ContentSecurityPolicy>();

    // Loop through each policy
    foreach (var contentSecurityPolicy in contentSecurityPolicies)
    {
        // Get the policy value
        var value = contentSecurityPolicy.Value();

        // Add the nonce to the policy
        if (string.IsNullOrEmpty(value))
        {
            continue;
        }

        var nonce = this._cspNonceService.GetNonce();
        nonce = HttpUtility.JavaScriptStringEncode(nonce);
        value = value.Replace("{nonceValue}", nonce);
        policy.Add(value);
    }

    // Return the policy
    return string.Join(';', policy.ToArray());
}

There is one small thing to call out here. I want to use a nonce with scripts. A nonce is a hash that is unique for each request. If a script tag doesnt have the nonce, the browser will treat is as suspicious and wont run the script. A script tag with a nonce might look like this:

<script src="/dist/main.min.js?t=638433482440000000" nonce="wm+Z3Sws/IkrrJUnTulrX4M0Lez8VY49of/BSW8vyOw="></script>

I created a custom implementation of this service and I use this to generate the nonce and string replace it in the ScriptSource attribute of the Content Security Policy.

/// <summary>
/// Concrete implementation of nonce service for generating the nonce
/// </summary>
public class CspNonceService : ICspNonceService
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public CspNonceService(IHttpContextAccessor httpContextAccessor) => this._httpContextAccessor = httpContextAccessor;

    // Cache key
    public const string Key = "csp-nonce";

    /// <summary>
    /// Get the current nonce
    /// </summary>
    /// <returns></returns>
    public string GetNonce()
    {
        // Get the cache
        var items = this._httpContextAccessor.HttpContext?.Items;

        // If we have no items and the key is not in the cache
        if (items != null && !items.ContainsKey(Key))
        {
            // Generate the nonce and add it to cache
            items.Add(Key, GenerateNonce());
        }

        // Get the nonce from cache
        var nonce = items != null ? items[Key] : GenerateNonce();

        // Return the nonce
        return nonce?.ToString();
    }

    /// <summary>
    /// Generate a new nonce
    /// </summary>
    /// <returns></returns>
    private static string GenerateNonce()
    {
        // Generate a new nonce
        var numArray = new byte[32];
        using (var randomNumberGenerator = RandomNumberGenerator.Create())
        {
            randomNumberGenerator.GetBytes(numArray);
        }

        // Convert it to base 64 string
        return Convert.ToBase64String(numArray);
    }
}

Startup

The last step is to register any resources I need, and add the middleware to the pipeline.

In Startup.cs, I register the nonce service in the ConfigureServices method:

// Add nonce service
services.AddScoped<ICspNonceService>(sp => new CspNonceService(sp.GetRequiredService<IHttpContextAccessor>()));

Optimizely can add this to its own script blocks once this is registered (https://docs.developers.optimizely.com/content-management-system/docs/content-security-policy).

NOTE: Using the nonce is an all or nothing proposition. If you implement this, any script tags added to pages will need the nonce. This will require you to manually set it using the ICspNonceService implementation.

Next I create an extension method to make this policy easier to set.

/// <summary>
/// Method for implementing security header middleware
/// </summary>
public static class MiddlewareExtensions
{
    public static IApplicationBuilder UseSecurityHeadersMiddleware(this IApplicationBuilder app, SecurityHeadersBuilder builder)
    {
        var policy = builder.Build();
        return app.UseMiddleware<SecurityHeadersMiddleware>(policy);
    }
}

Lastly I add the middleware to the pipeline, also in Startup.cs in the configure method. I add it early in the pipeline so all requests get it:

// Add security headers
app.UseSecurityHeadersMiddleware(new SecurityHeadersBuilder()
    .AddDefaultSecurePolicy()
    .RemoveHeader("X-Powered-By")
);

This can be customized easily to your specific needs.

NOTE: I am running locally and you can see that the server header is still there. The Server header for Kestrel has to be removed in a different way, when you configure Kestrel in your code.

Now when I go to my site I can see all of my headers:

And I can see if I log in to the CMS, the Content Security Policy is not being added:

Lastly, if I scan a site using this configuration, I can see that my headers are set up appropriately:

Potential Future Enhancement: With Content Security Policy, here I have constructed a fairly permissive policy. You can actually include specific urls for the various parts of the policy. This would probably best be maintained an appsettings, and then retrieved and added to the policy.

Unit Testing Optimizely - How to deal with the ServiceLocator

Wed, 14 Feb 2024 18:54:09 GMT

Unit testing with Optimizely can be challenging. One of those challenges is Optimizely's use of the ServiceLocator pattern. ServiceLocator is generally considered to be an anti-pattern (https://blog.ploeh.dk/2010/02/03/ServiceLocatorisanAnti-Pattern/). One of the reasons for this is the difficulty it causes with unit tests. We, as developers can avoid this pattern, but it is still baked into a lot of Optimizely's code. So, testing code that relies on Optimizely classes can run into a problem because the ServiceLocator used in those Optimizely classes doesnt have anything registered in the context of a unit test. Here is a way around this problem.

For this blog post, Im using Xunit for tests, and NSubstitute for mocking things. The method described below should conceptually work with any testing and mocking framework, but the syntax may vary.

Scope

Xunit, at the time of this post, does not have a built in way to run some code once prior to all tests. Luckily, someone named Daniel Cazzulino has created a NuGet package that will allow us to do exactly this: https://www.cazzulino.com/assembly-fixtures.html. Xunit calls classes that maintain things accross tests in a single test a 'fixture'. This package allows for the creation of an assembly fixture, a fixture that maintains a lifecycle accross all test. You can use it by having your test class implement IAssemblyFixture, a generic interface that requires an actual fixture class.

The Fixture

For this case, we need an fixture that mimics the functionalty of the service locator.

using EPiServer;
using EPiServer.ServiceLocation;
using EPiServer.Web;
using EPiServer.Web.Templating;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.AspNetCore.Mvc.ViewEngines;
using Microsoft.Extensions.DependencyInjection;
using NSubstitute;

namespace MyProject.Tests.Infrastructure;

/// <summary>
/// Mock service locator for tests
/// </summary>
public class ServiceLocatorFixture : IDisposable
{
    /// <summary>
    /// Add items to DI on constructor
    /// </summary>
    public ServiceLocatorFixture()
    {
        this.Providing<IContentLoader>();        
        this.Providing<ICompositeViewEngine>();
        this.Providing<IModelTemplateTagResolver>();
        this.Providing<IHtmlHelper>();
        this.Providing<IContextModeResolver>();        
    }

    /// <summary>
    /// Encapsulated service provider
    /// </summary>
    private IServiceProvider _serviceProvider;

    /// <summary>
    /// Public accessor for service locator
    /// </summary>
    public IServiceProvider ServiceProvider
    {
        get
        {
            // If it already exists, just return it            
            if (this._serviceProvider != null)
            {
                return this._serviceProvider;
            }
            // Create new service provider
            this._serviceProvider = Substitute.For<IServiceProvider>();
            ServiceLocator.SetServiceProvider(this._serviceProvider);
            return this._serviceProvider;
        }
    }

    /// <summary>
    /// Add item to service locator
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <returns></returns>
    public T Providing<T>() where T : class
    {
        var obj = Substitute.For<T>();
        this.ServiceProvider.GetService<T>().Returns(obj);
        this.ServiceProvider.GetRequiredService<T>().Returns(obj);
        return obj;
    }

    /// <summary>
    /// Add item to service locator
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="instance"></param>
    /// <returns></returns>
    public T Providing<T>(T instance) where T : class
    {
        this.ServiceProvider.GetService<T>().Returns(instance);
        this.ServiceProvider.GetRequiredService<T>().Returns(instance);
        return instance;
    }    

    public void Dispose()
    {
        this.Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    { }
}

Reviewing whats going on here:

This fixture has a property of IServiceProvider. This is what underlies the ServiceLocator. The first time it is called, it checks if the underlying field _serviceProvider has value. If not, it creates a substitute for the service provider, and then assigns it to the ServiceLocator:

public IServiceProvider ServiceProvider
{
	get
	{
		// If it already exists, just return it            
		if (this._serviceProvider != null)
		{
			return this._serviceProvider;
		}
		// Create new service provider
		this._serviceProvider = Substitute.For<IServiceProvider>();
		ServiceLocator.SetServiceProvider(this._serviceProvider);
		return this._serviceProvider;
	}
}

This fixture offers two ways to add things to the service provider with the methods 'Providing'. The first method just takes a type as generic attribute:

public T Providing<T>() where T : class
{
	var obj = Substitute.For<T>();
	this.ServiceProvider.GetService<T>().Returns(obj);
	this.ServiceProvider.GetRequiredService<T>().Returns(obj);
	return obj;
}

Notice that it implements GetService and GetRequiredService. Items can be registered simply:

this.Providing<IContentLoader>();

This specific content loader will be available in any test class implementing this fixture.

The other version of providing allows you to register a specific implementation of a class or substitute:

public T Providing<T>(T instance) where T : class
{
	this.ServiceProvider.GetService<T>().Returns(instance);
	this.ServiceProvider.GetRequiredService<T>().Returns(instance);
	return instance;
}

Notice that this also implements GetService and GetRequiredService. Also notice that using NSubstitute, we can make this return a specific implementation.

var contentTypeRepository = Substitute.For<IContentTypeRepository>();
contentTypeRepository.List().Returns(new List<ContentType> { testBlockType, new() { Name = "TestPage", ID = 2 } });
contentTypeRepository.Load(1).Returns(testBlockType);
this.Providing(contentTypeRepository);

So using the ServiceLocator to get the content type repository will return this specific implementation. Lastly, in the constructor we register all the things we might need from the ServiceLocator in tests.

Usage

To use this fixture, we need to have our test class implement IAssemblyFixture, and to inject the ServiceLocatorFixture in the test class constructor.

public class MyClassTests : IAssemblyFixture<ServiceLocatorFixture>
{
    private readonly ServiceLocatorFixture _serviceLocatorFixture;

    public MyClassTests(ServiceLocatorFixture serviceLocatorFixture) => this._serviceLocatorFixture = serviceLocatorFixture;
}

And then we can start writing some tests. For a class that requires something from the DI container, we can get it from the fixture:

[Fact]
public void Build_NormalDefaults_ViewModelPopulated()
{
    var contentLoader = this._fixture.ServiceProvider.GetRequiredService<IContentLoader>();
    var logger = Substitute.For<ILogger<TestBlockViewModelBuilder>>();

    var builder = new TestBlockViewModelBuilder(contentLoader, logger);
    var viewModel = builder.Build(new TestBlock());

    builder.CurrentContent.Should().NotBeNull();
    viewModel.Should().NotBeNull();
    viewModel.CurrentBlock.Should().NotBeNull();
}

But we can also make use of Optimizely classes that rely on the ServiceLocator, even if we dont need direct access to the ServiceLocator from the test:

[Fact]
public void BuildStandardLoaderOptions_NoCulture_ReturnsOptions()
{
    var loaderOptionsService = new LoaderOptionsService();

    var options = loaderOptionsService.BuildStandardLoaderOptions();

    options.Should().NotBeNull();
}

Loader Options Service is a class we created to streamline creating LoaderOptions for calls to get content. If I look at the BuildStandardLoaderOptions method, if I do not provide a CultureInfo, it uses ContentLanguage.PreferredCulture, an Optimizely method for getting the current culture. This method relies on IContentLanguageAccessor. So for this test to work, I need to register IContentLanguageAccessor in the constructor of my fixture:

var contentLanguageAccessor = Substitute.For<IContentLanguageAccessor>();
contentLanguageAccessor.Language.Returns(new CultureInfo("en"));
this.Providing(contentLanguageAccessor);

For this project, we wanted the default language to be "en", so this will always return that. So, this test will work.

Test Lifetime

One thing to watch out for. When running unit tests in Visual Studio, running tests in Debug means each test is run in serial, one after the other. But if I just run tests all at once, they are on multiple threads. So, something done to something in the ServiceLocator could affect multiple tests. A symptom of this is that debugging all tests, the tests might pass, but if you just run all tests, they may fail because the ServiceLocator might return unexpected results.

In order to deal with this, you might need to combine this service locator fixture with specific Substitutes in the test. In particular, if you test returns specific content items that you need to test against, you might need to do this.

Example:

In my ServiceLocator I have registered a IContentLoader. But, for a specific test, I need that repository to return some content specific for this test. So, even though my test class implements IAssemblyFixture, in my test I create a specific substitute of IContentLoader just for this test.

public class ContentLoaderExtensionsTests : TestBase, IAssemblyFixture<ServiceLocatorFixture>
{
    private readonly ServiceLocatorFixture _fixture;

    public ContentLoaderExtensionsTests(ServiceLocatorFixture fixture) => this._fixture = fixture;

    [Fact]
    public void GetFirstChild_WhenCalled_ReturnsFirstChild()
    {
        var contentLoader = Substitute.For<IContentLoader>();

        var page1 = new TestPage();
        page1.Property.Add("PageLink", new PropertyContentReference(1));
        page1.Property.Add("PageTypeID", new PropertyNumber(100));
        page1.Property.Add("PageStartPublish", new PropertyDate(DateTime.Now.AddDays(-1)));
        page1.Property.Add("PageStopPublish", new PropertyDate(DateTime.Now.AddDays(1)));

        var page2 = new TestPage();
        page2.Property.Add("PageLink", new PropertyContentReference(2));
        page2.Property.Add("PageTypeID", new PropertyNumber(100));
        page2.Property.Add("PageStartPublish", new PropertyDate(DateTime.Now.AddDays(-1)));
        page2.Property.Add("PageStopPublish", new PropertyDate(DateTime.Now.AddDays(1)));
        page2.Property.Add("ParentLink", new PropertyContentReference(1));

        var page3 = new TestPage();
        page3.Property.Add("PageLink", new PropertyContentReference(3));
        page3.Property.Add("PageTypeID", new PropertyNumber(100));
        page3.Property.Add("PageStartPublish", new PropertyDate(DateTime.Now.AddDays(-1)));
        page3.Property.Add("PageStopPublish", new PropertyDate(DateTime.Now.AddDays(1)));
        page3.Property.Add("ParentLink", new PropertyContentReference(1));

        var securable = page1 as IContentSecurable;
        var securityDescriptor = securable?.GetContentSecurityDescriptor();
        securityDescriptor?.AddEntry(new AccessControlEntry("test", AccessLevel.FullAccess, SecurityEntityType.User));

        var securable2 = page2 as IContentSecurable;
        var securityDescriptor2 = securable2?.GetContentSecurityDescriptor();
        securityDescriptor2?.AddEntry(new AccessControlEntry("test", AccessLevel.FullAccess, SecurityEntityType.User));

        var securable3 = page3 as IContentSecurable;
        var securityDescriptor3 = securable3?.GetContentSecurityDescriptor();
        securityDescriptor3?.AddEntry(new AccessControlEntry("test", AccessLevel.FullAccess, SecurityEntityType.User));

        var principal = Substitute.For<IPrincipal>();
        principal?.Identity?.Name.Returns("test");
        PrincipalInfo.CurrentPrincipal.Returns(principal);

        var templateResolver = this._fixture.ServiceProvider.GetRequiredService<ITemplateResolver>();

        var type = page1.GetOriginalType();
        const TemplateTypeCategories categories = TemplateTypeCategories.Request;
        var list = Enumerable.Empty<string>();
        templateResolver.ResolveAll(page1, type, categories, list)
            .Returns(new List<TemplateModel> { new() });

        var type2 = page2.GetOriginalType();
        templateResolver.ResolveAll(page2, type2, categories, list)
            .Returns(new List<TemplateModel> { new() });

        var type3 = page3.GetOriginalType();
        templateResolver.ResolveAll(page3, type3, categories, list)
            .Returns(new List<TemplateModel> { new() });

        var publishedStateAssessor = this._fixture.ServiceProvider.GetRequiredService<IPublishedStateAssessor>();
        publishedStateAssessor.IsPublished(Arg.Any<IContent>()).Returns(true);

        contentLoader.GetChildren<TestPage>(Arg.Any<ContentReference>(), Arg.Any<LoaderOptions>()).Returns(new List<TestPage> { page2, page3 });

        var child = contentLoader.GetFirstChild<TestPage>(page1.ContentLink);
        child.Should().NotBeNull();
        child.Should().BeOfType<TestPage>();
    }
}

You can see that the class implements the IAssemblyFixture, but in the test, we create a specific IContentLoader substitute:

var contentLoader = Substitute.For<IContentLoader>();

And then we explicitly set what it should return:

contentLoader.GetChildren<TestPage>(Arg.Any<ContentReference>(), Arg.Any<LoaderOptions>()).Returns(new List<TestPage> { page2, page3 });

And we are confident that GetChildren will only return these two pages in thuis specific test.

Summary

Writing unit tests for Optimizely is a challenge. Implementing a test replacement for ServiceLocator allows us to test a whole bunch of code that still relies on ServiceLocator in the Optimizely code base.