Blog posts by Mark Stott2025-04-09T08:23:00.0000000Zhttps://world.optimizely.com/blogs/mark-stott/Optimizely WorldAnnouncing Stott Security Version 3.0<p>I'm proud to announce the release of version 3 of Stott Security for Optimizely PAAS CMS. This release has been developed over several months owing to a significant new feature among other quality of life changes.</p>
<div>
<div>To see the full release notes you can head over to the discussion page on <a title="Github - Stott Security v3.0.0" href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/278">GitHub.</a></div>
<div> </div>
<h2>Permissions-Policy Support</h2>
<p>The <strong>Permissions-Policy</strong> HTTP header (formerly <strong>Feature-Policy</strong>) allows developers to control which web features and APIs can be used in the browser, and by which origin. This header can improve security and performance by restricting access to sensitive capabilities such as the camera, microphone, and geolocation.</p>
<p>Currently, support for the <strong>Permissions-Policy</strong> header is mixed. It is well-supported by Chromium-based browsers like Chrome and Edge, but not yet implemented in Firefox or Safari. This naturally raises the question: why invest time in implementing a feature that isn’t universally supported?</p>
<p>According to the latest <a title="browser market share data" href="https://gs.statcounter.com/browser-market-share">browser market share data</a>, over 70% of users are on browsers that support this header. Additionally, unsupported browsers simply ignore the header, without causing any issues. While I've yet to see a penetration test flag the absence of this header as a vulnerability, I’m increasingly seeing clients request its inclusion as part of their CMS security requirements.</p>
<p>To support this, I’ve added a new <strong>Permissions Policy</strong> screen to Stott Security. This interface allows administrators to enable or disable the <strong>Permissions-Policy</strong> header globally with a single toggle. It also includes a filter bar for quickly narrowing directives by source (URL) or current configuration (e.g., *Disabled*, *Allow None*, *Allow All Sites*, etc.).</p>
<p><img src="/link/83b55fc2cfae462eb112c8cdcaaf50e2.aspx?1744186114798" alt="The Permission Policy listing for Stott Security" width="3420" height="1276" /></p>
<p>Clicking the <strong>Edit</strong> button for a directive opens a modal where the configuration for that specific directive can be adjusted.</p>
<p><img src="/link/3fc3a110a51d401bad8d7fc98a2734b6.aspx?1744186158433" alt="The Permission Policy modal for a single directive within Stott Security" width="2280" height="842" /></p>
<p>Available options include:</p>
<ul>
<li>Disabled (Omitted this directive from the policy)</li>
<li>Allow None</li>
<li>Allow All Sites</li>
<li>Allow Just This Website</li>
<li>Allow This Website and Specific Third Party Websites</li>
<li>Allow Specific Third Party Websites</li>
</ul>
<p>For configurations involving third-party origins, administrators can specify one or more sources. Input is strictly validated to require only protocol and domain. Wildcards are supported, but only as the first segment after the protocol (e.g. <em>https://*.example.com</em>).</p>
<p>All changes to the Permissions Policy are fully audited. Additionally, import/export functionality has been extended to include this new feature.</p>
<h2>Small Features</h2>
<h3>.NET 9 Support</h3>
<div>
<div>If you're building an Optimizely PaaS solution targeting <strong>.NET 9</strong>, you can now integrate Stott Security into your project, regardless of whether your solution is headed, headless, or hybrid.</div>
<br />
<div>Stott Security leverages Entity Framework for database access and operations such as migrations. Since each major release of Entity Framework often introduces breaking changes aligned with specific .NET versions, the Stott Security package has been updated to include build targets for <strong>.NET 6</strong>, <strong>.NET 8</strong>, and <strong>.NET 9</strong>, each using the appropriate version of Entity Framework under the hood.</div>
<h3>Import Settings Tool</h3>
<p>In previous versions, the import tool required that CSP, CORS, and Response Headers configurations all be present in the import file. To support backwards compatibility with export files created in version 2.x, validation in version 3.x has been relaxed. Now, settings are only applied if they contain a non-null value. This allows for partial imports; if your import file includes only the CSP configuration, then only the CSP settings will be updated, leaving all other settings unchanged.</p>
<h3>X-XSS-Protection Header Warning</h3>
<div>
<div>The <strong>X-XSS-Protection</strong> header was originally introduced to instruct browsers to enable their built-in XSS filters, aiming to protect users from cross-site scripting attacks. However, the feature introduced its own set of issues. When configured with <code>X-XSS-Protection: 1; mode=block</code>, malicious actors could exploit it to trigger denial-of-service conditions by injecting scripts that caused legitimate content to be blocked. Alternatively, when simply enabled without blocking (<code>X-XSS-Protection: 1</code>), the header became susceptible to <strong>XS-Search</strong> attacks this is where an attacker submits crafted XSS payloads to probe for differences in application behavior, potentially exposing sensitive data in applications that would otherwise be considered secure.</div>
<br />
<div>Although Stott Security continues to support the <strong>X-XSS-Protection</strong> header, it should <strong>only</strong> be set to <strong>disabled</strong> or <strong>omitted entirely</strong>. To help guide users, explanatory notes have been added to the UI outlining current best practices.</div>
<br />
<div>It’s worth noting that Chromium-based browsers already ignore this header entirely, but some other browsers have yet to follow suit.</div>
<h3>Content Security Policy Source Updates</h3>
<p>Validation has been enhanced to support the <strong>'inline-speculation-rules'</strong> keyword within Content Security Policy (CSP) directives. Speculation rules enable the browser to preload potential navigation targets based on user behavior, improving perceived performance by initiating page loads slightly before user interaction (e.g., clicks).</p>
<p>The <strong>CSP Edit Source</strong> modal in Stott Security has also been updated to ensure that special keywords such as <strong>'unsafe-inline'</strong>, <strong>'unsafe-eval'</strong>, and <strong>'inline-speculation-rules'</strong> can only be added to directives where they are valid. These are typically limited to <strong>script-src</strong>, <strong>style-src</strong>, and their more specific variants.</p>
<p><img src="/link/743f539570f24afdaac612ad801523b0.aspx?1744186454614" alt="Content Security Policy Edit Source modal for Stott Security" width="2280" height="850" /></p>
<div>
<h3>CMS Editor Gadget Removed</h3>
<p>In version 2, I introduced a CMS Editor gadget that displayed the HTTP headers generated when rendering a specific page. This was intended to support the feature allowing users to extend the Content Security Policy (CSP) for individual content items by specifying additional sources.</p>
<p>However, over time it became clear that this approach had several drawbacks:</p>
<ul>
<li>The gadget was read-only and appeared automatically for all CMS administrators, even if the page-specific CSP feature wasn't in use. In most cases, this meant the gadget was visible but offered little to no value.</li>
<li>Some developers experienced installation issues with the AddOn. Specifically, in projects where the <code>.csproj</code> excluded the <code>modules\_protected</code> folder; often done to avoid conflicts with other third-party AddOns that add files to the solution multiple times. This resulted in the Stott Security <strong>module.config</strong> being be removed and not re-added. This in turn causes an error during the start up of the solution that could only be resovled by manually adding the into source control and project.</li>
</ul>
<p>Given the minimal benefit provided by the gadget and the friction it caused in certain build pipelines, I’ve decided to remove it entirely in version 3.</p>
<div>
<h3>Obsolete Code Removed</h3>
<div>
<div>If your solution has been using Stott Security since version 1 then you may find that you are using some obsoleted code. As part of packaging up version 3, the following items have been removed:</div>
<br />
<div>
<ul>
<li>SecurityServiceExtensions.AddCspManager(...)
<ul>
<li>Replaced by SecurityServiceExtensions.AddStottSecurity(...)</li>
</ul>
</li>
<li>SecurityServiceExtensions.UseCspManager()
<ul>
<li>Replaced by SecurityServiceExtensions.UseStottSecurity()</li>
</ul>
</li>
<li>CspReportingViewComponent
<ul>
<li>Replaced by Report-Uri and Report-To within the CSP.</li>
</ul>
</li>
</ul>
<div>
<h3>Report To Endpoint Fixes</h3>
<div>
<div>The <strong>report-uri</strong> directive has been deprecated within the content security policy. The specification for this endpoint was for it to receive a single CSP Report per request with a content type of <code>application/csp-report</code>. With the introduction of the <strong>report-to</strong> directive, browsers are now meant to send a collection of CSP Reports in an array with a content type of <code>application/reports+json</code>. The intent being to reduce the number of requests being made to any reporting endpoint.</div>
<br />
<div>Some browsers appear to have simply started sending their <strong>report-uri</strong> payload to the <strong>report-to</strong> endpoint on a per report basis instead of matching the specification. The result is a lot of bad requests being returned and a host of reports being lost. I have updated the <strong>report-to</strong> endpoint so that it can handle both payloads based on their respective content types.</div>
<h2>Get It Now</h2>
<div>Stott Security v3.0 is free to use and is available on all the usual nuget feeds:</div>
<div>
<ul>
<li><a href="https://nuget.optimizely.com/?q=stott&s=Popular&r=10&f=All">https://nuget.optimizely.com</a></li>
<li><a href="https://api.nuget.optimizely.com/?q=stott&s=Popular&r=10&f=All">https://api.nuget.optimizely.com</a></li>
<li><a href="https://www.nuget.org">https://www.nuget.org</a></li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a> </p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>2025-04-09T08:23:00.0000000ZBlog postOpti ID with Secure Cookies And Third Party AddOns<p>Opti ID has revolutionised access to the Optimizely One suite and is now the preferred authentication method on all PAAS CMS websites that I build. However there are a couple of gotchas that always need to be taken care, outlined below are the solutions to both.</p>
<h2>Secure Cookies</h2>
<p>Any penetration test that you perform on your website will always advise that your cookies are set to be Secure, HTTP Only with a SameSite mode of Strict. Setting these is simple enough until you realise that the Opti ID cookies are third party and therefore for need a SameSite mode of None. If you have used Microsoft Entra (Formerly Azure AD) as the authentication method for a CMS, then this problem will be very familiar to you.<br /><br />The challenge we have is:</p>
<ul>
<li>We don't want all cookies to have a SameSite mode of None</li>
<li>Optimizely cookies are not in our direct control</li>
<li>Writing verbose custom cookie code everywhere is messy</li>
</ul>
<p>In the following solution I have used the app.UseCookiePolicy(...) method to set all of the cookies to be Secure, Http Only with a default SameSite mode of None by default. I then provide a handler for the OnAppendCookie event that will set cookies to use a SameSite mode of Strict provided they do not match one of the following cookie name patterns:</p>
<ul>
<li><strong>oid-</strong> : These are cookies which Opti ID uses for authentication</li>
<li><strong>.AspNetCore </strong>: These are cookies NET Core uses for Authentication</li>
</ul>
<pre class="language-csharp"><code>public static IApplicationBuilder UseSecureCookies(this IApplicationBuilder app)
{
// Set the default cookie policy
app.UseCookiePolicy(new CookiePolicyOptions
{
HttpOnly = HttpOnlyPolicy.Always,
Secure = CookieSecurePolicy.Always,
MinimumSameSitePolicy = SameSiteMode.None,
OnAppendCookie = context =>
{
if (!context.CookieName.StartsWith("oid-") &&
!context.CookieName.StartsWith(".AspNetCore"))
{
// Any cookie that is not an authentication cookie should have a SameSite mode of Strict
context.CookieOptions.SameSite = SameSiteMode.Strict;
}
}
});
return app;
}</code></pre>
<h2>Configuring AddOns To Use Opti ID</h2>
<p>In Optimizely CMS 11, dependency setup relied upon <strong>Initialisation Modules</strong>. In CMS 12 and .NET core, all of this is now handled in <strong>Startup.cs</strong>. Some commonly used AddOns include a service extension that is intended to be consumed within a startup.cs. Some go as far as to provide a custom authorization policy so that you can customise access to the AddOn to specific roles rather than granting full admin access to the CMS for users who just need that functionality. Here are a few AddOns and the roles that you might want to use:</p>
<ul>
<li>Stott Security - CmsAdmins, SecurityAdmins, DataAnalytics</li>
<li>Stott Robots Handlers - CmsAdmins, SeoAdmins</li>
<li>Geta NotFound Handler - CmsAdmins, SeoAdmins</li>
<li>Geta Sitemaps - CmsAdmins, SeoAdmins</li>
</ul>
<p class="code-line">Here is the challenge: These modules will not allow you to access them when using Opti Id unless you specify the <strong>Opti ID SchemeName</strong> in the authorizarion policy for each AddOn.</p>
<p class="code-line">Take this configuration for the <strong>Stott Security AddOn</strong> as an example; this AddOn allows you to segment the data for the AddOn into a separate database and it allows you to define an authorization policy. In this scenario it is a simple matter of making sure the Opti ID Scheme Name is added to the policy:</p>
<pre class="language-csharp"><code>public static IServiceCollection AddSecurityAddOn(this IServiceCollection services)
{
services.AddStottSecurity(
options =>
{
options.ConnectionStringName = "EPiServerDB";
},
authorization =>
{
authorization.AddPolicy(CspConstants.AuthorizationPolicy, policy =>
{
// Use the Opti ID scheme Name
policy.AddAuthenticationSchemes(OptimizelyIdentityDefaults.SchemeName);
policy.RequireRole(Roles.CmsAdmins, "SecurityAdmins");
});
});
return services;
}</code></pre>
<h2>Service Collection Extension Pattern</h2>
<p>In both of these examples above, I am following the <a title="Service Collection Extension Pattern" href="https://dotnetfullstackdev.medium.com/service-collection-extension-pattern-in-net-core-with-item-services-6db8cf9dcfd6">Service Collection Extension Pattern</a>. I highly recomment this pattern as it allows you to modularise your configuration code and to keep your startup.cs clean and easy to understand or rearrange. </p>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-12-09T13:07:46.0000000ZBlog postCreating an Optimizely Addon - Best Practices<p>In <a href="/link/38b1217b7fdc41238ed62f1f31907605.aspx">Part One</a>, <a href="/link/c29176d530e64067b29392113b435547.aspx">Part Two</a> and <a href="/link/59fdc24a290e4471bd32fcbb87d6454d.aspx">Part Three</a>, I have outlined the steps required to create an AddOn for Optimizely CMS, from architecture to packaging at as a NuGet package. In this part I will be covering some best practices that will help you succeed as an AddOn developer. You can view examples from across this series within the this <a href="https://github.com/GeekInTheNorth/OptimizelyAddOnTemplate">Optimizely AddOn Template</a> that I have been creating.</p>
<div class="markdown-heading">
<h2>Unit Tests</h2>
</div>
<p>As a solo developer managing multiple AddOns, my ability to release updates regularly relies heavily on having extensive unit tests. For instance, <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">Stott Security</a> includes over 1,500 unit tests that run whenever a pull request is made to merge a feature branch into the develop branch. This level of coverage ensures that functionality remains consistent across releases.</p>
<p>As well as writing unit tests for your business logic, you can also write additional unit tests that validate the security of your controllers. I would consider adding these tests to be an essential part of ensuring the security of your system as they ensure the following:</p>
<ul>
<li>Controller actions explicitly allow only the intended HTTP methods, ensuring endpoints respond only to the correct verbs.</li>
<li>Controller actions are secured with the Authorization attribute or marked with AllowAnonymous if security isn’t required. This enforces clear security requirements for each endpoint.</li>
<li>Controller actions are defined with specific routes, preventing conflicts with other modules or the consuming application’s routing.</li>
</ul>
<pre class="language-csharp"><code>[TestFixture]
public sealed class ControllerStandardsTests
{
[Test]
[TestCaseSource(typeof(ControllerStandardsTestCases), nameof(ControllerStandardsTestCases.PageControllerActionTestCases))]
public void ControllersShouldHaveHttpMethodAttributes(string controllerName, string methodName, MethodInfo methodInfo)
{
// Act
var hasHttpMethodAttribute = methodInfo.GetCustomAttributes(typeof(HttpMethodAttribute)).Any();
// Assert
// Controllers should only respond in intended Verbs and should respond with method not allowed on unintended verbs.
// This will prevent posting of malicious payloads to methods not intended to retrieve of deal with these payloads.
// First raised by a penetration test where an attempt to post files to a content end point returned a 200 instead of a 405
Assert.That(hasHttpMethodAttribute, Is.True, $"{controllerName}.{methodName} should be decorated with a http method attribute.");
}
[Test]
[TestCaseSource(typeof(ControllerStandardsTestCases), nameof(ControllerStandardsTestCases.PageControllerActionTestCases))]
public void ControllerMethodsShouldEitherHaveAuthorizeOrAllowAnonymousAttributes(string controllerName, string methodName, MethodInfo methodInfo)
{
// Act
var hasAuthorizeAttribute = methodInfo.GetCustomAttributes(typeof(AuthorizeAttribute)).Any();
var hasAllowAnonymousAttribute = methodInfo.GetCustomAttributes(typeof(AllowAnonymousAttribute)).Any();
var controllerHasAuthorizeAttribute = methodInfo.DeclaringType?.GetCustomAttributes(typeof(AuthorizeAttribute)).Any() ?? false;
var hasAttribute = hasAuthorizeAttribute || hasAllowAnonymousAttribute || controllerHasAuthorizeAttribute;
// Assert
// Controller actions should be protected with an Authorization attribute or an intentional AllowAnonymous attribute.
// This will ensure your controllers are secure by default and that you have to explicitly allow anonymous access.
Assert.That(hasAttribute, Is.True, $"{controllerName}.{methodName} should be decorated directly or indirectly with an Authorize or AllowAnonymous attribute.");
}
[Test]
[TestCaseSource(typeof(ControllerStandardsTestCases), nameof(ControllerStandardsTestCases.PageControllerActionTestCases))]
public void ControllerMethodsShouldHaveRouteAttributes(string controllerName, string methodName, MethodInfo methodInfo)
{
// Act
var hasRouteAttribute = methodInfo.GetCustomAttributes(typeof(RouteAttribute)).Any();
var controllerHasRouteAttribute = methodInfo.DeclaringType?.GetCustomAttributes(typeof(RouteAttribute)).Any() ?? false;
var hasAttribute = hasRouteAttribute || controllerHasRouteAttribute;
// Assert
// Controller actions should have a fixed route attribute so as to not have clashes with routes declared by other modules.
Assert.That(hasAttribute, Is.True, $"{controllerName}.{methodName} should be decorated directly with a Route attribute.");
}
}</code></pre>
<p>These tests use a Test Case Source method which uses reflection to identify all controllers within your solution. This means as you add new controllers, you will not forget to secure them.</p>
<pre class="language-csharp"><code>public static class ControllerStandardsTestCases
{
public static IEnumerable<TestCaseData> PageControllerActionTestCases
{
get
{
var assembly = Assembly.GetAssembly(typeof(SettingsLandingPageController));
if (assembly == null)
{
yield break;
}
var controllers = assembly.GetTypes()
.Where(t => (t.BaseType?.Name.StartsWith("Controller") ?? false)
|| (t.BaseType?.Name.StartsWith("BaseController") ?? false))
.ToList();
foreach (var controller in controllers)
{
var actions = controller.GetMethods()
.Where(x => x.DeclaringType == controller && x.IsPublic)
.ToList();
foreach (var methodInfo in actions)
{
if (methodInfo.ReturnType == typeof(IActionResult) || methodInfo.ReturnType == typeof(Task<IActionResult>))
{
yield return new TestCaseData(controller.Name, methodInfo.Name, methodInfo);
}
}
}
}
}
}</code></pre>
<div class="markdown-heading">
<h2>Test System</h2>
</div>
<p>If you have followed this series to create an AddOn, you'll note that the sample site for developing the AddOn does not use nuget to consume the AddOn code and instead uses a project reference. This will allow you to develop efficiently, however it does mean that you are not testing your code in a production-like manner.</p>
<p>Create a separate repository with it's own Optimizely CMS solution. Import your AddOn as a NuGet package directly into this solution. This will allow you to test your AddOn in the same way that another developer will be experiencing your AddOn for the first time. If you are able to generate a developer cloud license on <a href="https://license.episerver.com/">EPiServer License Centre</a>, then I would recommend you deploy this test system into an Azure WebApp running on Linux with .NET 6.0 or 8.0 so that you can validate your AddOn inside of a deployed environment.</p>
<p>As part of my go live cycle I perform the following:</p>
<ul>
<li>Create a beta version of my nuget package</li>
<li>Upload the beta package to nuget.org</li>
<li>Update my test system to use the beta package</li>
<li>Deploy my test system to Azure</li>
<li>Delist my beta version on nuget.org</li>
<li>Test my AddOn in my test system</li>
<li>Create a production version of my nuget package</li>
<li>Upload the production package to nuget.optimizely.com</li>
<li>Wait for the package to be approved by Optimizely's QA team</li>
<li>Upload the production package to nuget.org</li>
<li>Announce the release</li>
</ul>
<div class="markdown-heading">
<h2>Performance and Caching</h2>
</div>
<p>Optimizely's default settings for Azure SQL Server typically support around 120 simultaneous database connections, suggesting the use of an S2 SQL Database (or equivelent) for production. This configuration, combined with efficient caching by the Optimizely CMS code allows smaller databases to perform effectively for websites with high traffic.</p>
<p>If you're using Microsoft Entity Framework, be aware that each <code>DbContext</code> instance opens a new database connection. Failing to manage these connections can lead to server instability due to connection limits. Therefore, it's advisable to follow Optimizely's approach by extensively using caching. To implement this, consider the following steps:</p>
<ul>
<li>Use a Custom Cache Wrapper that consumes Optimizely's <code>ISynchronizedObjectInstanceCache</code> and uses it's own master key to allow you to purge your cache effectively.</li>
<li>Inject your DbContext as a scoped object to limit the number of instances to 1 per request.</li>
<li>Lazy Load dependencies that require a Db Context so that they are not instantiated if not consumed.</li>
<li>Handle data loading in the following order:
<ul>
<li>Attempt to retrieve and return data from cache first.</li>
<li>Attempt to retrieve and return data from the database second.
<ul>
<li>Push the data into a cache before returning it.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>The following is an example of a cache wrapper that consumes the <code>ISynchronizedObjectInstanceCache</code>.</p>
<pre class="language-csharp"><code>public sealed class CacheWrapper : ICacheWrapper
{
private readonly ISynchronizedObjectInstanceCache _cache;
private const string MasterKey = "My-OptimizelyAddOn-MasterKey";
public CacheWrapper(ISynchronizedObjectInstanceCache cache)
{
_cache = cache;
}
public void Add<T>(string cacheKey, T? objectToCache)
where T : class
{
if (string.IsNullOrWhiteSpace(cacheKey) || objectToCache == null)
{
return;
}
try
{
var evictionPolicy = new CacheEvictionPolicy(
TimeSpan.FromHours(12),
CacheTimeoutType.Absolute,
Enumerable.Empty<string>(),
new[] { MasterKey });
_cache.Insert(cacheKey, objectToCache, evictionPolicy);
}
catch (Exception exception)
{
// Add logging here
}
}
public T? Get<T>(string cacheKey)
where T : class
{
return _cache.TryGet<T>(cacheKey, ReadStrategy.Wait, out var cachedObject) ? cachedObject : default;
}
public void RemoveAll()
{
try
{
_cache.Remove(MasterKey);
}
catch (Exception exception)
{
// Add logging here
}
}
}</code></pre>
<p>In order to use Lazy Loaded dependencies, you first need to define the Lazy variant within your service extension method:</p>
<pre class="language-csharp"><code>services.AddScoped<IMyDataContext, MyDataContext>();
services.AddScoped<Lazy<IMyDataContext>>(provider => new Lazy<IMyDataContext>(() => provider.GetRequiredService<IMyDataContext>()));</code></pre>
<p>You can then declare your dependencies as Lazy in your constructors and consume them as per the example below. In this scenario, the <code>IMyDataContext</code> is instantiated once, but that is deferred until it is used by the <code>GetData()</code> method:</p>
<pre class="language-csharp"><code>internal sealed class MyRepository : IMyRepository
{
private readonly Lazy<IMyDataContext> _context;
public MyRepository(Lazy<IMyDataContext> context)
{
_context = context;
}
public async Task<IList<string>> GetData()
{
return await _context.Value.MyData.ToListAsync();
}
} </code></pre>
<p>A service can then consume both the <code>IMyRepository</code>and <code>ICacheWrapper</code> and make performant calls to retrieve data that has not changed. In the following example we attempt to retrieve the data from the cache first, then if it is null or empty we then attempt to load the data from the repository, push that data into cache before returning it. If the <code>Delete</code> method is called within the service, we call <code>RemoveAll()</code> on the cache wrapper to invalidate cache entries based on a master key:</p>
<pre class="language-csharp"><code>internal sealed class MyService : IMyService
{
private readonly IMyRepository _repository;
private readonly ICacheWrapper _cache;
private const string CacheKey = "Unique.Cache.Key";
public MyService(IMyRepository repository, ICacheWrapper cache)
{
_repository = repository;
_cache = cache;
}
public async Task<IList<string>> GetDate()
{
var data = _cache.Get<IList<string>>(CacheKey);
if (data is not { Count: >0 })
{
data = await _repository.GetData();
_cache.Add(CacheKey, data);
}
return data;
}
public async Task Delete(string data)
{
await _repository.Delete(data);
_cache.RemoveAll();
}
}</code></pre>
<p>Note how we don't need to lazy load the repository as the database context is already lazy loaded by the repository itself, however you may choose to lazy load the repository as it is not used if the cache is populated.</p>
<div class="markdown-heading">
<h2>Summary</h2>
</div>
<ul>
<li>Ensure all key business logic is covered by a unit test.</li>
<li>Use unit tests to enforce standards such as:
<ul>
<li>Controller actions have correct HTTP method attributes.</li>
<li>Controllers have secure actions with authorization or explicit anonymous access.</li>
<li>Controllers have defined routes to avoid conflicts.</li>
</ul>
</li>
<li>Test your AddOn in a separate production-like environment.</li>
<li>Use caching to optimize database access.</li>
<li>Implement lazy loading and scoped dependencies.</li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-10-24T12:32:06.0000000ZBlog postCreating an Optimizely Addon - Packaging for NuGet<p>In <a href="/link/38b1217b7fdc41238ed62f1f31907605.aspx">Part One</a> and <a href="/link/c29176d530e64067b29392113b435547.aspx">Part Two</a> of this series; I covered topics from having a great idea, solution structure, extending the menus and adding gadgets to the editor interface. In this part I will be covering the challenges of creating and submitting your AddOn as a NuGet package into the Optimizely NuGet feed. You can view examples from across this series within the this <a href="https://github.com/GeekInTheNorth/OptimizelyAddOnTemplate">Optimizely AddOn Template</a> that I have been creating.</p>
<div class="markdown-heading">
<h2>Defining What to Package</h2>
</div>
<p>Each project within your solution must be created as a NuGet package if it is deemed to be the primary project or a dependency for the primary project. Consider the following solution as an example:</p>
<ul>
<li>MySolution.sln
<ul>
<li>MyAddOn.Admin.csproj</li>
<li>MyAddOn.Core.csproj</li>
<li>MyAddOn.Test.csproj</li>
</ul>
</li>
</ul>
<p>In this scenario, the administrator interface for the AddOn is separated from its core shared functionality. This design enables a consuming site to incorporate MyAddOn.Admin into their Optimizely website project and to reference MyAddOn.Core within any project in their solution structure. Consequently, MyAddOn.Admin has a direct dependency on MyAddOn.Core. To publish MyAddOn.Admin as a NuGet package, MyAddOn.Core must also be published as a NuGet package. It should be noted that MyAddOn.Admin only requires MyAddOn.Core as a project dependency during development; this dependency will be converted into a package dependency during the packaging process.</p>
<div class="markdown-heading">
<h2>Defining NuGet Properties</h2>
</div>
<p>If you are using Visual Studio, right click on the project you want to package and select properties to show the project properties screen. Under the Package section you can define all of the properties for your NuGet package.</p>
<p><img src="/link/82eb39f7e54044f2944d4c45f7385832.aspx" /></p>
<p>I would recommend you complete the following:</p>
<ul>
<li><strong>Package Id :</strong> This will need to be globally unique name within nuget.org and nuget.optimizely.com. If you use the <code>$(AssemblyName)</code> variable, then this will match the name of the project.</li>
<li><strong>Title :</strong> Visual Studio describes this as the name of the package used in UI displays such as Package Manager, but this largely does not get used.</li>
<li><strong>Package Version : </strong>This should be a semantic version number with three or four parts and an optional alpha or beta tag. For Example:
<ul>
<li>1.0.0</li>
<li>1.0.0.0</li>
<li>0.1.1-alpha</li>
<li>0.2.2.0-beta</li>
</ul>
</li>
<li><strong>Authors : </strong>This should contain the names of the primary people who will own the AddOn / Repository.</li>
<li><strong>Company :</strong> This should contain the name of the business that is behind creating the Addon. If this is individually owned, then seting this to <code>$(Authors)</code> will mirror the value from the Authors property.</li>
<li><strong>Description :</strong> This should be a short description about your Addon, this will be visible within the NuGet package feed and within the Plugin Manager screen within Optimizely CMS.</li>
<li><strong>Copyright : </strong>This should contain the name of the owner and the year. You get copyright protection automatically when creating software and you do not have to apply or pay a fee. There isn’t a register of copyright works in the UK. There are however organisations which will provide extra protection for a fee for validating your copyright. You can read more about copyright here: <a href="https://www.gov.uk/copyright">How copyright protects your work</a>. It is however worth you performing your own research into the matter within the country you live in.</li>
<li><strong>Project Url : </strong>This should point either to the repository for your Addon or an appropriate project page. Developers will use this to find out more about your Addon or to report issues that may need resolving.</li>
<li><strong>Readme : </strong>I have set this to the readme.md for my repositories, this will be visible to developers within the NuGet platform.
<ul>
<li>Do ensure assets such as images have absolute paths as this readme will be visible outside of the context of your repository and relative paths will result in images not being found.</li>
</ul>
</li>
<li><strong>Repository Url :</strong> This should point to the repository for your Addon, assuming that your Addon is Open Source.</li>
<li><strong>Tags :</strong> This is a delimited set of tags that make your package easier to find within the NuGet feeds.</li>
<li><strong>License File :</strong> This should reference the license within your repository. Careful consideration should be given to the type of license for your AddOn. Certain licenses may require your users to make their code open source to utilize your package, so think carefully about the permissiveness or restrictiveness of your license. It is noteworthy that some highly popular AddOns employ an MIT or Apache license.
<ul>
<li>I am utilizing an MIT license due to its permissive nature and lack of warranty. While I do engage with my users and address any issues that are raised, my AddOns are free and are maintained in my free time.</li>
</ul>
</li>
<li><strong>Require License Acceptance :</strong> If you tick this, the consumer will have to accept the license as they install the package. If you are using an MIT license, you may want to tick this to encourage the consumer to accept the warranty free nature of your AddOn.</li>
</ul>
<p>If you are using Visual Studio Code instead of Visual Studio, then you can edit the .csproj directly and add the package properties directly as XML values at the top of the csproj file. You can also add these properties into a .nuspec instead, when you package your project, the values from the .csproj and .nuspec are merged into a new .nuspec that is contained in the root of the compiled .nupkg file. I personnally prefer to put the NuGet properties directly into the .csproj.</p>
<pre class="language-markup"><code><Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
<Version>1.1.0.0</Version>
<RepositoryUrl>https://example.com/</RepositoryUrl>
<PackageProjectUrl>https://example.com/</PackageProjectUrl>
<PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
<Authors>Your Name</Authors>
<Description>Your Package Summary</Description>
<Copyright>Your Name 2024</Copyright>
<PackageTags>TagOne TagTwo</PackageTags>
<PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
<AssemblyVersion>1.1.0.0</AssemblyVersion>
<GeneratePackageOnBuild>True</GeneratePackageOnBuild>
<PackageReleaseNotes>A short release summary.</PackageReleaseNotes>
<Nullable>enable</Nullable>
<Title>Package Name</Title>
</PropertyGroup></code></pre>
<div class="markdown-heading">
<h2>NuGet Package Structure</h2>
</div>
<p>A NuGet Package is simply a zip file containing a structured set of files. If you rename a .nupkg to a .zip, you can extract it and explore it's structure. This will have a structure similar to the following:</p>
<ul>
<li>package
<ul>
<li>services
<ul>
<li>metadata
<ul>
<li>core-properties</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>build
<ul>
<li>project.name.targets</li>
</ul>
</li>
<li>contentFiles
<ul>
<li>additional.file.txt</li>
</ul>
</li>
<li>lib
<ul>
<li>net6.0
<ul>
<li>my.project.dll</li>
</ul>
</li>
<li>net8.0
<ul>
<li>my.project.dll</li>
</ul>
</li>
<li>my.project.nuspec</li>
</ul>
</li>
<li>_rels</li>
<li>[Content_Types].xml</li>
<li>readme.md</li>
<li>license.txt</li>
</ul>
<p>Folders such as build, contentFiles and the target folders under lib will vary depending on your code and deployable files. The readme.md and license.txt files referenced in your .csproj or .nuspec are copied to the root of the NuGet package.</p>
<div class="markdown-heading">
<h2>Packaging for Multiple Frameworks</h2>
</div>
<p>.NET Core is backwards compatible, meaning that if you build your package for .NET 6, it can be installed into .NET 6, 7, and 8. For most AddOns, compiling directly for .NET 6 ensures maximum compatibility.</p>
<p>However, there may be instances where you need to compile your application in multiple framework versions. For example, if you are using Entity Framework and Migrations, there is a breaking change between .NET 6 and .NET 8. Fortunately, no code changes are required, but you will need to set your dependencies separately for .NET 6 and .NET 8. To accomplish this, you must make two modifications.</p>
<ol>
<li>Change the <code>TargetFramework</code> node in your .csproj to be <code>TargetFrameworks</code> and separate your target frameworks with a semicolon. e.g. <code>net6.0;net8.0</code>.</li>
<li>Add a separate <code>ItemGroup</code> per framework version to contain framework specific dependencies and add a condition to the ItemGroup to target the specific framework. e.g. <code>Condition="'$(TargetFramework)' == 'net6.0'"</code>.</li>
</ol>
<pre class="language-markup"><code><Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="6.0.6" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.1" />
</ItemGroup></code></pre>
<p>This will double the size of your NuGet package as it will contain separate folders for each target framework containing your code compiled for that framework.</p>
<div class="markdown-heading">
<h2>Packaging Additional Files For The Protected Modules Folder</h2>
</div>
<p>If your package contains an <code>IFrameComponent</code> or other files needed to extend the Editor Interface. A <code>module.config</code> file and those files will need to be deployed to the <code>modules/_protected/my_project</code> folder within the target website.</p>
<p>First you will need to tell the .csproj file that we want to copy these files into the <code>contentFiles</code> folder of the NuGet package. This is as simple as setting the build output for those files to be <code>None</code> and to set the <code>PackagePath</code> to be inside of the <code>contentFiles</code> folder.</p>
<pre class="language-markup"><code><ItemGroup>
<None Include="module.config">
<Pack>true</Pack>
<PackagePath>contentFiles\module.config</PackagePath>
</None>
</ItemGroup></code></pre>
<p>You will then need to create a .targets file that instructs the NuGet package installer how to handle those files. The example below is taken straight from my own Addons where I am doing the same thing.</p>
<p>The <code>ItemGroup</code> tells the .targets file where the specific files are within the NuGet package structure. The <code>$(MSBuildThisFileDirectory)</code> variable in this case is a reference to the directory the .targets file sits in. As this is in a build folder, I have used the <code>$(MSBuildThisFileDirectory)</code> variable in combination with the relative path to my module.config file.</p>
<p>The <code>Target</code> node is then performing an action that is configured to execute on <code>BeforeBuild</code>. This then performs a <code>Copy</code> action that will take my module.config file from the contentFiles folder in the nuget package to the <code>modules\_protected\my_project</code> folder within the target website. This means that when you first install the package, the module.config file and folder will not exist within the protected modules folder. When you first build the solution they will be copied into this location.</p>
<pre class="language-markup"><code><?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
<ItemGroup>
<MyFiles Include="$(MSBuildThisFileDirectory)..\contentFiles\module.config" />
</ItemGroup>
<Target Name="CopyFiles" BeforeTargets="BeforeBuild">
<Copy SourceFiles="@(MyFiles)" DestinationFolder="$(MSBuildProjectDirectory)\modules\_protected\my_project\" />
</Target>
</Project></code></pre>
<p>In order to make sure the .targets file can be executed, we also need to make sure that it is copied into the NuGet package file. This is as simple as editing your .csproj file and configuring the build output for the .targets file to be <code>None</code> and to set the <code>PackagePath</code> to be inside of the <code>build</code> folder.</p>
<pre class="language-markup"><code><ItemGroup>
<None Include="msbuild\copyfiles.targets">
<Pack>true</Pack>
<PackagePath>build\$(MSBuildProjectName).targets</PackagePath>
</None>
</ItemGroup></code></pre>
<div class="markdown-heading">
<h2>Submitting Your Package</h2>
<p>Before submitting your AddOn to the Optimizely NuGet package feed, it is essential to ensure that your package installs successfully both in your local environment and within a CI/CD pipeline. To expedite this process, consider publishing your package as an alpha or beta build to <a href="https://www.nuget.org/">nuget.org</a> first. After publishing, your package will be indexed and available for retrieval within a few minutes.</p>
<p>To designate your package as an alpha or beta release, you should modify the <code>version</code> property within your `.csproj` file to include a trailing <code>-alpha</code> or <code>-beta</code>. NuGet will automatically recognize this as a pre-release version and will generally filter these versions out by default. Developers can view these pre-release versions by selecting the option to display pre-release versions within their IDE’s NuGet package tool.</p>
<pre class="language-markup"><code><Version>2.0.0.2-beta</Version></code></pre>
<p>Upon publishing the alpha or beta version of your package to nuget.org and confirming its successful installation both locally and in a CI/CD pipeline, you will be prepared to submit the live version of your package to Optimizely.</p>
<p>Ensure that you have an <a href="/link/6c9478a8761c41d88dfc32e9ef56e714.aspx">Optimizely World</a> account. You can create a new account by visiting <a href="/link/6c9478a8761c41d88dfc32e9ef56e714.aspx">Optimizely World</a> and following the registration link located in the top right corner. This account will also provide access to the Optimizely NuGet feeds. Optimizely maintains two NuGet feeds:</p>
<ul>
<li><a href="https://nuget.optimizely.com/">https://nuget.optimizely.com</a> (v2 NuGet feed)</li>
<li><a href="https://api.nuget.optimizely.com/">https://api.nuget.optimizely.com</a> (v3 NuGet feed)</li>
</ul>
<p>Packages uploaded to the v2 NuGet feed are automatically synchronized to the v3 NuGet feed. Therefore, it is advisable to upload your packages to the v2 NuGet feed. Once Optimizely receives your package, it will undergo an approval process conducted by Optimizely's QA team. During this process, the QA team will verify that your AddOn functions correctly with the CMS. Including test guidance in the readme for your repository can be very beneficial for the QA team. This review process may take one or more business days, and there is currently no feedback mechanism to inform you of the status or outcome of the testing. You may periodically check the NuGet feed to determine if your package has been accepted. Given that Optimizely validates all packages uploaded to their NuGet feed, it is recommended to download AddOn updates directly from Optimizely and distribute your own package in this manner. Should you need to release a hotfix promptly, you may consider uploading it to nuget.org.</p>
<p>It is advisable to upload your package to nuget.org at least once in addition to the Optimizely NuGet feed. This ensures that the package name is reserved on nuget.org, avoiding potential conflicts in package names across the main feeds that could affect your consumers.</p>
<p><em>Please note that as of the time of writing, there was an issue with packages uploaded directly to the v3 NuGet feed not being synchronized back to the v2 NuGet feed. Until this issue is resolved, the Upload link on the v3 NuGet feed redirects users to the v2 NuGet feed. Optimizely is actively working to resolve this issue.</em></p>
</div>
<div class="markdown-heading">
<h2>Summary</h2>
</div>
<ul>
<li>Build your package for .NET 6 for maximum compatability
<ul>
<li>Build your package for both .NET 6 & 8 if you have compatability issues between both frameworks.</li>
</ul>
</li>
<li>Use a Razor Class Library so you can package your UI and C# code together.</li>
<li>Think very carefully about which license you will use for your package.</li>
<li>Use a build targets file to put files into specific folders within a consuming application.</li>
<li>Test your package installs and works as an alpha/beta on nuget.org before submitting to the Optimizely NuGet feed.</li>
<li>Upload your package to <a href="https://nuget.optimizely.com/">nuget.optimizely.com</a> when it is ready.</li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-09-16T08:17:11.0000000ZBlog postCreating an Optimizely CMS Addon - Adding an Editor Interface Gadget<p>In <a href="/link/38b1217b7fdc41238ed62f1f31907605.aspx">Part One</a> of this series, I covered getting started with creating your own AddOn for Optimizely CMS 12. This covered what I consider to be an ideal solution structure, best practices for your JavaScript and Styles, extending the menu interface and authentication. In Part Two, I will be covering adding an additional editor interface gadget. You can view examples from across this series within the this <a href="https://github.com/GeekInTheNorth/OptimizelyAddOnTemplate">Optimizely AddOn Template</a> that I have been creating.</p>
<div class="markdown-heading">
<h2>Adding a Gadget to the Editor Interface</h2>
</div>
<p>You can easily turn a standard MVC Controller into a CMS Editor Gadget by decorating it with the <code>[IFrameComponent]</code> attribute. The primary properties of the attributes are as follows:</p>
<ul>
<li><strong>Title </strong>: The name of the gadget, visible in the Gadget selector.</li>
<li><strong>Description </strong>: A brief description of the gadget, also visible in the Gadget selector. It is recommended to keep this to one sentence.</li>
<li><strong>Categories </strong>: The appropriate category for the gadget. For content-specific gadgets, this should be set to "content" or "cms"</li>
<li><strong>Url </strong>: The route corresponding to your controller action.</li>
<li><strong>PlugInAreas </strong>: The location within the system where the component should be made available.</li>
<li><strong>ReloadOnContextChange </strong>: Enables the UI to reload the gadget each time a different content item is selected within the CMS interface.</li>
</ul>
<p>Optimizely will automatically identify these controllers and use the properties of the <code>[IFrameComponent]</code> attribute to populate the Add Gadgets window within the CMS Editor interface: </p>
<p><img src="/link/4e76e725f84b403881ffa86520d11db1.aspx?1725023534237" alt="Gadget Selector in Optimizely CMS 12 Editor Interface" width="1308" height="1013" /></p>
<p>When the editor interface loads your gadget, it will include an <code>id</code> query string parameter containing a versioned content reference in string format (e.g., 123_456). The number on the left represents the permanent identity of the content, while the number on the right denotes the specific version of that content item. This information can be used to load the specific version of a content item and incorporate it into your gadget's model.</p>
<p>Below is an example of the minimum required setup for your controller. Note the inclusion of the [Authorize] attribute on the controller and the [HttpGet] attribute on the action. These ensure that the user is authenticated and that the interface cannot be accessed using an unexpected HTTP verb. Note how I use the <code>id</code> query string parameter to load the specific version of the page the user has selected within the CMS Editor interface to provide context specific information to the user.</p>
<pre class="language-csharp"><code>[Authorize(Policy = OptimizelyAddOnConstants.AuthorizationPolicy)]
[IFrameComponent(
Url = "/optimizely-addon/gadget/index/",
Title = "Example Gadget",
Description = "An example gadget for the CMS Editor Interface.",
Categories = "content",
PlugInAreas = "/episerver/cms/assets",
MinHeight = 200,
MaxHeight = 800,
ReloadOnContextChange = true)]
public sealed class GadgetController : Controller
{
private readonly IContentLoader _contentLoader;
public GadgetController(IContentLoader contentLoader)
{
_contentLoader = contentLoader;
}
[HttpGet]
[Route("~/optimizely-addon/gadget/index")]
public IActionResult Index()
{
var model = new GadgetViewModel
{
Page = GetPageData(Request),
ContentId = Request.Query["Id"].ToString()
};
return View("~/Views/OptimizelyAddOn/Gadget/Index.cshtml", model);
}
private PageData? GetPageData(HttpRequest request)
{
var contentReferenceValue = request.Query["Id"].ToString() ?? string.Empty;
if (string.IsNullOrWhiteSpace(contentReferenceValue))
{
return null;
}
var contentReference = new ContentReference(contentReferenceValue);
if (_contentLoader.TryGet<PageData>(contentReference, out var pageData))
{
return pageData;
}
return null;
}
}</code></pre>
<p>In the gadget I developed for <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">Stott Security</a>, I focus exclusively on rendering a preview of the security headers for the currently selected page. I added this feature as Stott Security supports extending the Content Security Policy for any given page. To ensure the user can be clear on the context for the header preview, I load the page using the same helper method and add it to the view model for my Gadget.</p>
<div class="markdown-heading">
<h2><img src="/link/4d30cc76c02042a19babb4b0a96e6982.aspx" /></h2>
<h2>Extending IFrameComponent</h2>
<p>When your user logs into the CMS, they will be given your new Gadget by default. Now you can ensure that only specific roles have access to the Gadget by setting the <code>AllowedRoles</code> property within the <code>[IFrameComponent]</code> declaration. If your AddOn allows the developer to define a custom security policy for accessing your module, you cannot simply specify the roles within the attribute. For next version of the Stott Security AddOn, I have created a <code>SecureIFrameComponentAttribute</code> that inherits the <code>IFrameComponentAttribute</code> and dynamically resolves the roles that are allowed access to the Gadget based on that security profile.</p>
<pre class="language-csharp"><code>[AttributeUsage(AttributeTargets.Class)]
public sealed class SecureIFrameComponentAttribute : IFrameComponentAttribute
{
public SecureIFrameComponentAttribute() : base()
{
try
{
var authorizationOptions = ServiceLocator.Current.GetService(typeof(IOptions<AuthorizationOptions>)) as IOptions<AuthorizationOptions>;
var policy = authorizationOptions?.Value?.GetPolicy(CspConstants.AuthorizationPolicy);
var roles = policy?.Requirements?.OfType<RolesAuthorizationRequirement>().ToList();
var roleNames = roles?.SelectMany(x => x.AllowedRoles).ToList() ?? new List<string> { Roles.WebAdmins, Roles.CmsAdmins, Roles.WebAdmins };
AllowedRoles = string.Join(',', roleNames);
}
catch(Exception)
{
}
}
}</code></pre>
<h2>Telling the CMS Editor Interface About Our AddOn</h2>
</div>
<p>There are two steps to enable the Editor Interface to recognize our AddOn. The first step is to declare our assembly in a <code>module.config</code> file. Personnally this doesn't feel like it should be a requirement as all of the information is provided in the <code>[IFrameComponent]</code> attribute, though it appears that a validation during application startup mandates that this configuration file exists. I suspect this is a requirement tied to much deeper integrations with the UI. E.g. custom DOJO editor code etc.</p>
<p>Below is an example of a <code>module.config</code> file. Note the inclusion of an Authorization Policy as an attribute of the module node; this should correspond to the policy required by your AddOn. Additionally, ensure that the full name of the assembly containing your gadget is listed within the assemblies node.</p>
<pre class="language-markup"><code><?xml version="1.0" encoding="utf-8" ?>
<module loadFromBin="true" clientResourceRelativePath="" viewEngine="Razor" authorizationPolicy="MyAddOn:Policy" moduleJsonSerializerType="None" prefferedUiJsonSerializerType="Net">
<assemblies>
<add assembly="MyAddOnAssemblyName" />
</assemblies>
<clientModule>
<moduleDependencies>
<add dependency="CMS" />
</moduleDependencies>
</clientModule>
</module></code></pre>
<div class="markdown-heading">
<p>If you are simply adding a gadget to a specific Optimizely CMS build, the assembly declaration can be included in the <code>module.config</code> file located at the root of your website application. However, in the context of an AddOn, this declaration should be placed within a protected modules folder, using a path such as <code>[MyCmsWebsite]/modules/_protected/[MyAddOn]/module.config</code>. There are some extra steps required to achieve this when creating a NuGet package and I address these in Part Three of this series which is focused entirely on the NuGet package process.</p>
<p>The second step that is needed to inform the CMS of our AddOn is to ensure that is included within the <code>ProtectedModuleOptions</code>. This can be achieved within a service extensions method that you call within your <code>startup.cs</code> as follows: </p>
<pre class="language-csharp"><code>public static class OptimizelyAddOnServiceExtensions
{
public static IServiceCollection AddOptimizelyAddOn(this IServiceCollection services)
{
services.Configure<ProtectedModuleOptions>(
options =>
{
if (!options.Items.Any(x => string.Equals(x.Name, "MyAddOnAssemblyName", StringComparison.OrdinalIgnoreCase)))
{
options.Items.Add(new ModuleDetails { Name = "MyAddOnAssemblyName" });
}
});
return services;
}
}</code></pre>
<h2>Summary</h2>
</div>
<ul>
<li>Add the <code>[IFrameComponent]</code> attribute to your controller to define the gadget for the CMS Editor Interface.</li>
<li>Add the <code>[Authorize]</code> attribute to your controller to secure it.</li>
<li>Add HTTP verb attributes such as <code>[HttpGet]</code> to your controller actions to prevent unexpected access attempts.</li>
<li>Add a <code>module.config</code> file to the <code>[MyCmsWebsite]/modules/_protected/[MyAddOn]/module.config</code> folder so that CMS can validate your gadget assembly.</li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-08-30T15:43:33.0000000ZBlog postCreating an Optimizely AddOn - Getting Started<p>When Optimizely CMS 12 was launched in the summer of 2021, I created my first AddOn for Optimizely CMS and talked about some of the lessons I learned in my article <a href="/link/aa901c2390b44fce99cfd6b8838262d5.aspx">Custom Admin Pages in Optimizely 12</a>. Three years on, I have two highly refined Optimizely AddOns and have had to resolve numerous challenges. In this new series of articles I will be covering how to create an Optimizely AddOn, how to solve the same challenges I have encountered as well as what I consider to be best practices. You can view examples from across this series within the this <a href="https://github.com/GeekInTheNorth/OptimizelyAddOnTemplate">Optimizely AddOn Template</a> that I have been creating.</p>
<div class="markdown-heading">
<h2>Having a Great Idea</h2>
</div>
<p>The biggest hurdle to getting started with creating an AddOn is having a good idea. But here is the secret to having a great idea; it doesn't have to be great and it doesn't have to be original. My first AddOn was a very simple UI for managing robots.txt content within CMS 12 and I already knew a package existed for CMS 11 that had not been updated for a number of years. I've now met Mark Everard (the original AddOn author) a number of times and my AddOn has had nearly 200k downloads.</p>
<p>Your AddOn does not need to be pretty, your end user is a CMS editor or administrator, it needs to be easy to understand and it needs to be functional.</p>
<p>Finally, whatever idea you come up with, you need to be passionate about it as it will consume a lot of your time. I average roughly a commit per hour, based on this I have spent 145 hours on Stott Robots Handler and 587 hours on Stott Security. When converted to an average working day, that is 19 and 78 days respectively. You may also never make a single penny, there are many great AddOns out there that are open source, running on an MIT license without a license fee.</p>
<div class="markdown-heading">
<h2>Solution Structure</h2>
</div>
<p>When creating an AddOn for Optimizely CMS, I recommend that you package it as a single <a href="https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-8.0&tabs=visual-studio">Razor Class Library (RCL)</a>. This simplifies the process by consolidating all classes, controllers, razor files, and static content into one NuGet package. This can reduce administrative tasks and potential upgrade issues for users. An RCL also allows consuming websites to override your Razor files if needed, providing flexibility for UI modifications. However, you must carefully manage file paths to avoid conflicts, the best way to do this is to organize all of your Razor files into a specific path within the Views folder, e.g. <code>~/Views/MyAddOn/LandingPage.cshtml</code>.</p>
<p>In the <a href="https://github.com/GeekInTheNorth/OptimizelyAddOnTemplate">Optimizely AddOn Template</a> repository, the structure of my projects looks like this:</p>
<ul>
<li>Sample <em><strong>(Contains just the CMS to test against)</strong></em>
<ul>
<li>SampleCms.sln</li>
<li>nuget.config</li>
<li>SampleCms
<ul>
<li>SampleCms.csproj <em><strong>(Web Project)</strong></em></li>
<li>... Other folders and files for just the Sample CMS</li>
</ul>
</li>
</ul>
</li>
<li>src <em><strong>(contains the source code for the AddOn)</strong></em>
<ul>
<li>OptimizelyAddOn.sln</li>
<li>nuget.config</li>
<li>OptimizelyAddOn
<ul>
<li>OptimizelyAddOn.csproj <em><strong>(Razor Class Library)</strong></em></li>
<li>Views
<ul>
<li>OptimizelyAddOn
<ul>
<li>Administration
<ul>
<li>Index.cshtml</li>
</ul>
</li>
<li>Gadget
<ul>
<li>Index.cshtml</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>... Other folders and files that make up the AddOn functionality</li>
</ul>
</li>
<li>OptimizelyAddOn.Tests
<ul>
<li>OptimizelyAddOn.Tests.csproj <em><strong>(Test Class Library)</strong></em></li>
<li>... Other folders and files for organised unit tets.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>Please note that there is a one-to-one relationship between projects and NuGet packages; each project you add will require its own NuGet package. Lets say you have one project called MyAddOn.Core and a second project called MyAddOn.Optimizely, you will end up with two NuGet packages: MyAddOn.Core.nupkg and MyAddOn.Optimizely.nupkg. When developing these, you can use project references and when you package them into nuget files, the project references will automatically be converted into package dependencies.</p>
<div class="markdown-heading">
<h2>JavaScript and Stylesheets In Secure Systems</h2>
</div>
<p>When I initially developed the user interface for the <a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler">Stott Robots Handler</a> AddOn, I utilized externally hosted JQuery and Bootstrap JavaScript (JS) and CSS resources. This approach reduced the complexity of launching my AddOn and enabled a rapid entry to the market. I later undertook a comprehensive refactoring of the UI, rebuilding it with React and delivering optimized JS and CSS files directly packaged with the AddOn. This transition ensured that the UI adhered to best architectural and security practices.</p>
<p>When designing a UI for your own AddOn, you will likely encounter similar JavaScript (JS) and stylesheet (CSS) requirements. Both of these elements come with inherent security concerns, particularly in environments governed by a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP">Content Security Policy (CSP)</a>. A CSP serves as an allowlist of domains and specifies their permissions on your site. To ensure compatibility and maintain robust security, consider the following guidelines:</p>
<p>Ideally, you should build and distribute optimized and compiled JS and CSS files within your AddOn package within the <code>wwwroot</code> folder of your <a href="https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-8.0&tabs=visual-studio">Razor Class Library (RCL)</a>. This approach enables the CSP to utilize the <code>'self'</code> source directive, allowing your scripts and styles to be safely executed and applied.</p>
<p>Avoid using inline style attributes and JavaScript event handlers. Instead, attach styles and behaviors through classes defined within your JS and CSS files. This practice aligns more closely with CSP standards and significantly enhances security. It is important to note that inline Style attributes and JavaScript event attributes cannot be secured using a <code>nonce</code>.</p>
<p>Ensure that the <code>nonce</code> attribute of all <code>script</code> and <code>style</code> elements are populated with a value provided by Optimizely CMS’s <code>ICspNonceService</code> interface. For further information, refer to Optimizely's <a href="https://docs.developers.optimizely.com/content-management-system/docs/content-security-policy">Content Security Policy</a> documentation. Additionally, security AddOns, such as <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">Stott Security</a>, automatically configure the <code>ICspNonceService</code> and integrate it into the CSP for you.</p>
<p>If you choose to utilize JS and CSS resources hosted by third parties, additional precautions are necessary. Ensure that your script and link tags include a <a href="https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity">Subresource Integrity</a> (SRI) attribute. This attribute enables the browser to verify that the files have not been tampered with by checking them against a specified checksum. Bear in mind that each external resource you employ may require the site consuming your AddOn to adjust its CSP settings to accommodate these resources. Consequently, allowing third-party resources for your AddOn UI could inadvertently permit those resources site-wide.</p>
<p><em>Please note that at the time of writing, Optimizely does not support the <code>nonce</code> attribute for it's Editor or Admin interface, but there is an intention to correct this. Please do not be the developer that stops this from being adopted further down the line.</em></p>
<div class="markdown-heading">
<h2>Extending The Menu</h2>
</div>
<p>If your AddOn has it's own interface, then you will want to expose that interface to your users by creating a class that inherits <code>IMenuProvider</code> that is also decorated with <code>[MenuProvider]</code> attribute. Optimizely will automatically identify these classes and use them to extend the menu.</p>
<p>In the following example, I am returning a single <code>UrlMenuItem</code> which takes three parameters: the name of the link within the menu, the path within the menu and the MVC controller route for where my interface exists. I am then extending this to say that it is always available and sorting this to the end of the list of menu items. I am also defining the authorization policy required to access this menu item.</p>
<pre class="language-csharp"><code>[MenuProvider]
public sealed class ExampleMenuProvider : IMenuProvider
{
public IEnumerable<MenuItem> GetMenuItems()
{
return new UrlMenuItem(
"My AddOn",
"/global/cms/my.addon",
"/my-addon-controller-route/")
{
IsAvailable = context => true,
SortIndex = SortIndex.Last + 1,
AuthorizationPolicy = "required.security.policy"
};
}
}</code></pre>
<p>If you start the menu path with <code>global</code> then your AddOn will become visible within the module selector. If you start it with <code>global/cms</code>, then your AddOn will become visible under AddOns in the left hand menu of the CMS.</p>
<p><img src="/link/551d4511819d481e9ad7ee4d5ebf49f3.aspx?1725023387612" alt="Left Hand Menu in Optimizely CMS" width="412" height="680" /></p>
<p>If you have multiple menu items that you want to present in a hierarchial fashion, then you can simply return multiple UrlMenuItems, making sure to define the paths for the child menu items under their parent.</p>
<pre class="language-csharp"><code>[MenuProvider]
public class ExampleMenuProvider : IMenuProvider
{
public IEnumerable<MenuItem> GetMenuItems()
{
yield return new UrlMenuItem(
"My Addon Parent",
"/global/cms/myaddon.menu.example",
"/my-addon-controller-route/parent/")
{
IsAvailable = context => true,
SortIndex = SortIndex.Last + 1,
AuthorizationPolicy = "required.security.policy"
};
yield return new UrlMenuItem(
"My Addon Child One",
"/global/cms/myaddon.menu.example/child.one",
"/my-addon-controller-route/child-one/")
{
IsAvailable = context => true,
SortIndex = SortIndex.Last + 1,
AuthorizationPolicy = "required.security.policy"
};
yield return new UrlMenuItem(
"My Addon Child Two",
"/global/cms/myaddon.menu.example/child.two",
"/my-addon-controller-route/child-two/")
{
IsAvailable = context => true,
SortIndex = SortIndex.Last + 2,
AuthorizationPolicy = "required.security.policy"
};
}
}</code></pre>
<p>Parent and child menu items will manifest as it's own menu when it opens and this adopts the same style as the administrator interface. Please note that this consumes an additional 120 pixels of horizonal real estate and you may want to override the styles on your pages. If your interface is built as a single page application, then you can set the child menus to have the same URL as the parent but with anchor tags and toggle UI visibility based on this.</p>
<p><img src="/link/bf620391c58a4404b5e7fd12c644859f.aspx?1725023398544" alt="Left Hand Menu in Optimizely CMS" width="1050" height="512" /></p>
<div class="markdown-heading">
<h2>Handling Authentication</h2>
</div>
<p>If your AddOn UI is intended to be accessible to editors, then you can decorate your controllers with the <code>[Authorize(Roles = Roles.CmsEditors)]</code> attribute. Likewise if you want to make the UI available to CMS Administrators, then you can decorate your controller with <code>[Authorize(Roles = Roles.CmsAdmins)]</code>.</p>
<p>Depending on the Domain of your AddOn, you may wish to provide your consumers with the ability to fine tune access to your AddOn. For <a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler">Stott Robots Handler</a> and <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">Stott Security</a> I wanted to give consumers the ability to grant access to the AddOns to specific users such as an SEO Adminstrator or a Developer without granting that user access to the CMS Administrator interface. In order to do this, you will want to include the ability to define the authentication policy for your AddOn within your service extension:</p>
<pre class="language-csharp"><code>public static IServiceCollection AddMyAddOn(
this IServiceCollection services,
Action<AuthorizationOptions>? authorizationOptions = null)
{
// Authorization
if (authorizationOptions != null)
{
services.AddAuthorization(authorizationOptions);
}
else
{
var allowedRoles = new List<string> { "CmsAdmins", "Administrator", "WebAdmins" };
services.AddAuthorization(authorizationOptions =>
{
authorizationOptions.AddPolicy("My.AddOn.Policy.Name", policy =>
{
policy.RequireRole(allowedRoles);
});
});
}
return services;
}</code></pre>
<p>If you have made this optional, then the consumer can choose to use your defaults or define the policy themselves within their startup.cs:</p>
<pre class="language-csharp"><code>// Use Default Authentication Policy
services.AddMyAddOn();
// Use Custom Authentication Policy
services.AddMyAddOn(authorizationOptions =>
{
authorizationOptions.AddPolicy("My.AddOn.Policy.Name", policy =>
{
// This line is required if you are using Opti Id
policy.AddAuthenticationSchemes(OptimizelyIdentityDefaults.SchemeName);
// This defines the roles required for this policy
policy.RequireRole("WebAdmins", "SeoAdmins");
});
});</code></pre>
<p>All of your controllers should then instead be decorated with the <code>[Authorize(Policy = "My.AddOn.Policy.Name")]</code> attribute and menu items within your <code>IMenuProvider</code> should also be created with the same policy name.</p>
<div class="markdown-heading">
<h2>Summary</h2>
</div>
<ul>
<li>Your AddOn does not need to be unique or grand.</li>
<li>You will need to be passionate about your AddOn.</li>
<li>Do try to contain your AddOn into a single Razor Class Library to make installs and updates easier.</li>
<li>Do try to support a stricter Content Security Policy by:
<ul>
<li>Compiling and package your JavaScript and Stylesheets as part of the AddOn.</li>
<li>Attach styles and events using classes referenced by your JavaScript and Stylesheets.</li>
<li>Use <code>ICspNonceService</code> to add a <code>nonce</code> attribute to your script and style elements.</li>
</ul>
</li>
<li>Add items into the menu by implementing <code>IMenuProvider</code> and decorating it with <code>[MenuProvider]</code></li>
<li>Do secure all of your controllers to ensure users have to have access to the CMS Interface.
<ul>
<li>Consider using your own Authentication Policy if you want consumers to be able to apply more specific restrictions.</li>
</ul>
</li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-08-28T11:55:55.0000000ZBlog postStott Security Version 2 So Far<p>In December 2023, I unveiled the initial version of Stott Security version 2. Although I typically announce each version I release on LinkedIn and the GitHub repository, these announcements have often been concise, lacking in-depth explanations. Let’s delve into that now.</p>
<h2>Cross-Origin Resource Sharing Headers</h2>
<p>Cross-Origin Resource Sharing (CORS) headers serve as your web server’s means of specifying which domains, other than its own, are permitted to access its APIs. If you aim to bolster your website’s security, implementing both CORS and CSP is advisable, as they safeguard your website from different angles. The UI for managing CORS within Stott Security can be seen below:</p>
<p><img src="/link/3b63cc6b882c41749f2265f95670c04b.aspx" /></p>
<p>Interestingly, integrating a CMS-editable CORS policy turned out to be simpler than anticipated. In the .NET Core framework, there exists a default implementation of the <strong>ICorsPolicyProvider</strong> interface, which is automatically injected unless a custom implementation is provided. Leveraging this, my implementation extends the default provider and its interface. Upon a request, if a specific policy has been applied to the route, it’s loaded using the default implementation. Conversely, when no policy name is specified, the CORS policy defined by the module is loaded. The invocation of the custom implementation adheres to the standard protocol within .NET Core.</p>
<p>For further insights into the original CORS implementation within Stott Security, refer to <a href="/link/a539beae799741f886a37cb0f383aec3.aspx">Adding CORS Management to Optimizely CMS 12</a>. Notably, this functionality has been updated to accommodate both fixed CORS policies in the code and the globally utilized policy by Stott Security.</p>
<h2>Improved Source and Violation Filtering</h2>
<p>When I initially developed Stott Security, I didn’t foresee the sheer volume of sources that would be added to each site. It’s become apparent that some implementations contain upwards of 50 sources or more, making the list difficult to navigate. Additionally, the CSP Violation List can become overwhelming with potentially hundreds of violated sources.</p>
<p>To enhance user experience on these tabs, I’ve introduced the option to filter the list based on partial matches in the Source URL and the desired Directive. This feature aims to streamline navigation and improve usability for users dealing with extensive lists. The free text filter will filter the list of sources to just those sources that contain the term entered. The drop down will filter the sources to just those which have been granted access to the specifically chosen directive; this can make it a lot easier to see which sources can perform a specific action.</p>
<p><img src="/link/7a393ff5c583480bafd200ba47dd2a86.aspx" /></p>
<h2>Language Updates</h2>
<p>I decided to rename the feature formerly known as “Remote CSP Whitelist” to “Remote CSP Allowlist”. This choice reflects a shift towards more inclusive and descriptive terminology, opting for terms like Allowlist and Blocklist which are more overt in their meaning.</p>
<p>There is a lot of history to the terms “Whitelist” and “Blacklist” and often it is claimed that these have origins in trust and criminality respectively. Blacklisting however has a darker history where it was used as a means of oppression with individuals being unable to gain employment for performing acts that were either not approved of by their employers (such as striking) essentially leading to them being pushed into poverty. Overall in the english language, where “White” is used in a term it is often associated with “Good” while “Black” is associated with “Bad”. Irrespective of the origin of these terms, the continued use of these terms is a form of micro-aggression that continues to reinforce racial divides and systemic racism. I do not pretend to be in a position of Authority on subject matters like this. How can I be when I am not the victim of racism? How can I tell you how that makes another person feel? What I want to do here is continue to learn and to try to show my fellow humans the respect they deserve while making my software as user friendly and intiuitive as possible.</p>
<p>The switch to Allowlist and Blocklist is a good move in terms of clarity. The terms Whitelist and Blacklist may not be immediately comprehensible to those unfamiliar with them as they rely on simple color prefixes. In a casual discussion with a lay-person, I found that while the concept of a Blacklist was quickly grasped, the Whitelist prompted confusion and required explanation. On the other hand, when I asked about Allowlist and Blocklist, they swiftly understood their meanings without ambiguity or prior knowledge.</p>
<p>Microsoft has already embraced the language of Allowlist and Blocklist. This is immediately apparant in articles such as <a href="https://learn.microsoft.com/en-us/deployedge/microsoft-edge-security-endpoints">Allow list for Microsoft Edge endpoints</a> and <a href="https://learn.microsoft.com/en-gb/azure/azure-sql/database/firewall-configure?view=azuresql">Azure SQL Database and Azure Synapse IP firewall rules</a>. Google is another one of the big players that have started to use this newer language as we can see from their documentation such as <a href="https://support.google.com/a/answer/60752?hl=en">Allowlists, denylists, and approved senders</a>.</p>
<h2>Customisable Reporting Endpoints</h2>
<p>Stott Security has provided support for internal reporting endpoints since its inception, but the development journey for this feature has taken various paths. Initially, it employed a view component that generated a JavaScript tag to intercept browser events and transmit violations to the module’s endpoint. Later, I modified this to align with standard definitions for the report-uri and report-to schema.</p>
<p>The community using the module requested the ability to deactivate internal endpoints and define external ones. As a result, the option to disable internal endpoints was introduced. While this reduces traffic to the CMS instance, it also prevents any further updates to the violation report screen and renders the Agency Allowlist functionality inactive. Additionally, the functionality to specify external endpoints for report-uri and report-to was added, although this data remains unused by the module.</p>
<p>I’m interested in exploring options to integrate the violation report screen with external endpoints. However, this may necessitate the creation of a distinct reporting service.</p>
<h2>CSP NONCE Support</h2>
<p>A nonce is defined as a word or phrase that is meant to be used exactly once. For a Content Security Policy, the nonce is a code that should be used once. The browser will limit the execution of a script tag or style tag to just once per nonce value. This can protect the website and it’s users from replay attacks.</p>
<p>Stott Security was designed to protect the entire CMS website (both front and back end). The Optimizely CMS interface is however incompatabile with nonce values and the use of a nonce within the CMS interface will outright block the entire UI. In version 1.x of Stott Security, the nonce functionality was omitted for this reason. In version 2.3 of Stott Security, the nonce functionality was added into the solution. However due to a continued lack of support for nonce in the CMS interface, the Content Security Policy is instead generated both with and without a nonce depending on whether you are visiting a content page or attempting to visit the CMS interface.</p>
<h2>Preview Headers</h2>
<p>One downside of designing a UI for administrator ease of use is that it hides the fully compiled list of headers from the administrator. To address this, a new tab has been added to the interface, displaying the compiled list of HTTP Headers included with each request. This allows technical administrators to review the generated headers more thoroughly. Additionally, the same API powering this tab can be accessed for headless solutions.</p>
<p>Excluding the Cross Origin Resource Sharing (CORS) headers from this list was a deliberate choice for two primary reasons. Firstly, I defer to the underlying framework to generate these headers dynamically in response to requests, rather than manually generating them. Secondly, certain headers are exclusively visible during pre-flight requests and may vary depending on the origin of the request.</p>
<h2>Import & Export Functionality</h2>
<p>The user base for the module requested the ability to import and export configurations, with a common scenario being the need to transfer CSP configurations from a Preproduction environment to Production. Users may also wish to export settings before making and testing changes and have the option to revert to the last known good configuration.</p>
<p>This feature allows exporting all configurations as a JSON file, which can be downloaded and subsequently uploaded into the desired environment. Similar to any changes made directly within the user interface, the import process is fully audited as it may involve various actions:</p>
<ul>
<li>Creating or updating Content Security Policy settings</li>
<li>Creating, updating, or deleting Content Security Policy sources</li>
<li>Creating or updating Cross Origin Resource Policy settings</li>
<li>Creating or updating miscellaneous response headers.</li>
</ul>
<h2>Improved Performance</h2>
<p>I received a report concerning performance issues occurring in production with the Stott Security module. Notable stability concerns were raised regarding the instantiation of numerous DB Contexts, resulting in connection limit breaches. Optimizely typically configures the Production environment with the most conservative setup initially, scaling up as necessary. This strategy is to keep the costs down on the DXP platform. However, in this instance, the limit of around 100 concurrent connections was surpassed, indicating that the database may be scaled too low for a large client. In response, Optimizely temporarily resolved the issue by scaling up the database instance.</p>
<p>Upon receiving this report, I introduced additional logging into the DB context and key repositories to monitor instantiation frequency. Swiftly, I pinpointed areas for significant performance enhancement:</p>
<ul>
<li>Implemented caching for the CSP Settings Service.</li>
<li>Replaced usages of the CSP Settings Repository with the Service.
<ul>
<li>The repository handles data access while the service coordinates with the caching layer and repository.</li>
</ul>
</li>
<li>Extended cache duration from 1 hour to 12.</li>
<li>Implemented lazy instantiation for select repositories and the DB Context.
<ul>
<li>This prevented unnecessary instantiation of the DB Context unless needed.</li>
</ul>
</li>
</ul>
<p>In testing, there was a minimum reduction of 95% in all DB Context instantiation and database query calls. Deployment of these enhancements to the affected client resolved the stability issues. Within a week of resolving this issue, a second report surfaced, and I promptly advised the client to update the module within their solution.</p>
<h2>Release Notes</h2>
<ul>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/157">Version 2.1</a></li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/171">Version 2.2</a></li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/178">Version 2.3</a></li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/181">Version 2.4</a></li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/201">Version 2.5</a></li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/207">Version 2.6</a></li>
</ul>
<hr />
<p>You can find all of my content collated on <a href="https://www.stott.pro/">https://www.stott.pro/</a></p>2024-05-22T09:18:31.0000000ZBlog postWorking Programmatically With List Block properties<p>Recently I encountered some issues with a third party plugin with the latest version of Optimizely CMS 12. As the Go Live clock was ticking down fast for a client, we couldn't afford to wait for a fix to the third party plugin and I re-modelled the content to use a block list property instead. Unfortunatley there were a significant number of instances of the content type that needed to be remodelled so it was decided that we would have to migrate the client's content for them rather than have the client bear the burden.</p>
<p>The built in Optimizely Migration Step functionality is really good for when you want to do something like rename a content type or property, but if that property is an entirely different type, then you have to manage this change yourself.</p>
<p>As I wanted to migrate the old property onto the new property and the old property was a complex object, I chose to hide the old property rather than remove it so I would have full access to it's structure. To do this I added the <strong>[ScaffoldColumn(false)]</strong> attribute to the property which tells the CMS Interface not to render the property to the CMS Editor. I also added the <strong>[Obsolete] </strong>attribute, technically I didn't need to, but it highlights to other developers that the property should be removed and it shows up in tools such as SonarCloud as a reminder to remove the property later on.</p>
<pre class="language-csharp"><code>[Display(Name = "New Field Name")]
[MaxElements(20)]
public virtual IList<MyNewBlock>? NewField { get; set; }
[Obsolete("Remove this property after deployment to prod has migrated this property to 'New Field Name'.")]
[ScaffoldColumn(false)]
public virtual ThirdPartyPackageProperty? OldField { get; set; }</code></pre>
<p>I then created a Migration Step class that inherits the Optimizely <strong>MigrationStep </strong>and I added an override for the <strong>AddChanges()</strong> method. When making a Migration Step, I typically keep this method small and focused around catching and handling errors. When the application starts up, Optimizely attempts to perform the migration step before it creates any new property types; this means that the first time this migration step is executed will result in a failure. By catching and swallowing the error I can allow the first start up of the site to succeed and generate the new properties before triggering a second application restart so that the actual migration can take place.</p>
<pre class="language-csharp"><code>public sealed class MyMigrationStep : MigrationStep
{
public override void AddChanges()
{
try
{
MigratePages();
}
catch (Exception ex)
{
var logger = ServiceLocator.Current.GetInstance<ILogger<MyMigrationStep>>();
logger.LogError(ex, "Failure encountered when attempting to migrate the content type.");
}
}
}</code></pre>
<p>The <strong>MigratePages()</strong> method then uses the <strong>IContentTypeRepository</strong> to load the <strong>ContentType</strong> definition for the content type I want to perform the migration on. I then pass this into an instance of <strong>IContentModelUsage</strong> which will then return a complete list of every language and version of that content type in a content usage model. I want to convert all versions of every instance of my page type to allow for CMS Editors to compare across historical versions of the content as they will no longer be able to access the old property. I then loop through each content usage and load the full content version using the TryGet method of the <strong>IContentRepository</strong>.</p>
<pre class="language-csharp"><code>private static void MigratePages()
{
var contentTypeRepository = ServiceLocator.Current.GetInstance<IContentTypeRepository>();
var contentModelUsage = ServiceLocator.Current.GetInstance<IContentModelUsage>();
var contentRepository = ServiceLocator.Current.GetInstance<IContentRepository>();
var contentType = contentTypeRepository.Load(typeof(ExistingPageToChange));
var usages = contentModelUsage.ListContentOfContentType(contentType);
foreach (var contentUsage in usages)
{
if (contentRepository.TryGet<ExistingPageToChange>(
contentUsage.ContentLink,
new CultureInfo(contentUsage.LanguageBranch),
out var ExistingPageToChange))
{
MigratePage(contentRepository, ExistingPageToChange);
}
}
}</code></pre>
<p>The <strong>MigratePage </strong>method starts off with a little protection to make sure that if the new property is only updated if the new property does not have a value and the old property does have a value. As this migration might run multiple times, you may want to add a boolean to your content type which indicates if a migration has already been performed, but in my case I already had a plan to remove the old properties and the migration step in a rapid follow up release.</p>
<p>When you retrieve a piece of content from IContentLoader or IContentRepository, the object model is in a read only state. In order to edit a piece of content, you first have to create a writeable clone by calling the <strong>CreateWriteableClone()</strong> method against content item. This method exists upon the <strong>PageData</strong><strong> </strong>object and clones the content item in a writable state, but the method has a return type of <strong>PageData </strong>so you will have to recast it as the type you are editing. I then have a method called ConvertProperty that takes the old collection property and generates the new block list property. To avoid casting issues when saving, I implicitly set the variable as an <strong>IList<NewPropertyBlock></strong> before setting the property.</p>
<pre class="language-csharp"><code>private static void MigratePage(IContentRepository contentRepository, ExistingPageToChange instance)
{
var requiresMigration = instance.NewListBlockProperty.IsNullOrEmpty() && !instance.OldThirdPartyProperty.IsNullOrEmpty();
if (!requiresMigration)
{
return;
}
var editableVersion = (ExistingPageToChange)instance.CreateWritableClone();
// The variable has to be an IList<> in order to avoid a casting error.
IList<NewPropertyBlock> list = ConvertProperty(contentRepository, instance.ContentLink, editableVersion.OldThirdPartyProperty).ToList();
editableVersion.NewListBlockProperty = list;
contentRepository.Save(editableVersion, SaveAction.Patch, AccessLevel.NoAccess);
}</code></pre>
<p>Even though <strong>IList<Block></strong> properties are saved as part of the <strong>PageData </strong>and not as separate content, it's still important to use the Content Repository to set up a default writable instance of the blocks within the collection. If you just instantiate them as <strong>new NewPropertyBlock()</strong> then you will get an error when saving the block list against the page.</p>
<pre class="language-csharp"><code>private static IEnumerable<NewPropertyBlock> ConvertProperty(
IContentRepository contentRepository,
ContentReference parentReference,
ThirdPartyPackageProperty? oldPropertyList)
{
if (oldPropertyList is not { Count: > 0 })
{
yield break;
}
foreach (var oldProperty in oldPropertyList)
{
var NewPropertyBlock = contentRepository.GetDefault<NewPropertyBlock>(parentReference);
NewPropertyBlock.Link = new LinkItem
{
Href = oldProperty.Href,
Title = oldProperty.Title,
Target = oldProperty.Target,
Text = oldProperty.Text
};
NewPropertyBlock.HoverImage = oldProperty.HoverImage;
yield return NewPropertyBlock;
}
}</code></pre>
<p>The final step after finishing your edits to the content is to save the content back to the database. Because I was aiming to update all content versions to the new model without creating new content versions I had to call the save function as follows:</p>
<pre class="language-csharp"><code>contentRepository.Save(editableVersion, SaveAction.Patch, AccessLevel.NoAccess);</code></pre>
<p>SaveAction.Patch updates the existing version of the content without creating a new version or triggering any validation. As the save is being performed outside of the context of a user action, I had to pass in AccessLevel.NoAccess as the minimum access rights needed for the save to complete. Had I passed in AccessLevel.Publish, then the save action would have to take place as part of a user action where the user had "publish" permissions to the content.</p>
<h2>Summary</h2>
<ul>
<li>If you are changing the name of a property because it's type is the same
<ul>
<li>Create a MigrationStep and add a line to the AddChanges() method like this:
<ul>
<li>ContentType(nameof(MyContentType)).Property(nameof(MyContentType.NewPropertyName)).UsedToBeNamed("OldPropertyName");</li>
</ul>
</li>
</ul>
</li>
<li>If you are changing the type of the property:
<ul>
<li>Give the new property an entirely new name, this will prevent casting issues with the property on the content type.</li>
<li>Create a MigrationStep for handling the property type change.
<ul>
<li>Use IContentTypeRepository to get the content type</li>
<li>Use IContentModelUsage to get all instances of the content type </li>
<li>Use IContentRepository to create default instances of content types before creating new instances of a content type.</li>
<li>Use MyContentType.CreateWriteableClone() to get an editable version of the content you are changing.</li>
<li>Make sure you cast properties to the correct types when assigning them.</li>
</ul>
</li>
</ul>
</li>
</ul>2023-11-23T13:05:54.0000000ZBlog postAdding CORS Management to Optimizely CMS 12<p>In December 2021, I started working on a new add-on for Optimizely CMS 12. This add-on introduced a new way to manage the Content Security Policy within the CMS that was designed to be more accessible to non-technical people. This Add-on allowed the CMS Administrator to define on an origin-by-origin basis what origin was allowed to do what action with the website with every change being fully audited. This Add-on is now live on a number of Optimizely CMS websites and has gone through a number of penetration tests.</p>
<p>I planned the next evolution of this Add-on to include the ability to manage Cross-origin Resource Sharing (CORS) headers from within the CMS administration interface. CORS allows an API or Website to define what third parties can consume the resource as well as how they can consume the resource. This can be an important security requirement if you are building a Headed or Hybrid CMS that exposes endpoints to be consumed by another website.</p>
<p>The intent for this update to the Stott Security add-on was to allow the CMS editor to set all of the following headers in an easy to manage interface:</p>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials">Access-Control-Allow-Credentials</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers">Access-Control-Allow-Headers</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods">Access-Control-Allow-Methods</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin">Access-Control-Allow-Origin</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers">Access-Control-Expose-Headers</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age">Access-Control-Max-Age</a></li>
</ul>
<p>I have introduced a new tab into the Stott Security Add-on named “CORS” that allows you to edit and save all of these headers together.</p>
<p><img src="https://geekinthenorth.github.io/assets/StottSecurityCorsUi.png" alt="CORS Interface within the Stott Security Add-on" /></p>
<p>If the “Enable Cross-Origin Resource Sharing (CORS)” option is turned off, when a request is made to the website from third party, the response will be treated as if CORS is fully disallowed. If the option is turned on, then the default behaviour is to allow all Origins; It isn’t until an entry is added to Allowed Origins that other origins will be denied access again. The same behaviour applies for headers and HTTP methods, all are considered allowed until specific methods or headers are defined as being allowed.</p>
<p>There has been a distinct challenge in making the UI responsive and to reveal enough information to the user without overloading them with information. There are plenty of online resources on websites such<span> </span><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers">MDN Web Docs</a><span> </span>that describe CORS and the various CORS headers that more detailed descriptions were deemed as too much for this UI.</p>
<h2>Implementing CORS</h2>
<p>Once I had the UI for managing CORS and the tables sorted to store the configuration, I was able to start looking at how I could implement the behaviour. At first, I attempted to build my own middleware to manage this, and it quickly dawned on me that this would be very complex to achieve. The<span> </span><code class="language-plaintext highlighter-rouge">Access-Control-Allow-Origin</code><span> </span>header for example could only ever contain<span> </span><code class="language-plaintext highlighter-rouge">*</code>, the origin of the site making the request or being absent entirely. This prevents a website from revealing to third-parties who can consume them, only that the third-party website is allowed to consume them or not.</p>
<p>In an attempt to understand a better way of handling this, I added CORS to my sample website using the standard microsoft libraries by calling the<span> </span><code class="language-plaintext highlighter-rouge">AddCors()</code><span> </span>and<span> </span><code class="language-plaintext highlighter-rouge">UseCors()</code><span> </span>methods within my<span> </span><code class="language-plaintext highlighter-rouge">startup.cs</code>.</p>
<p>By navigating to the decompiled version of<span> </span><code class="language-plaintext highlighter-rouge">UseCors()</code><span> </span>I was able to see the<span> </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsMiddleware.cs">CorsMiddleware</a><span> </span>that was implemented by microsoft and see that it used an implementation of<span> </span><code class="language-plaintext highlighter-rouge">ICorsPolicyProvider</code><span> </span>to retrieve a<span> </span><code class="language-plaintext highlighter-rouge">CorsPolicy</code><span> </span>object and an implementation of<span> </span><code class="language-plaintext highlighter-rouge">ICorsService</code><span> </span>to evaluate the<span> </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsPolicy.cs">CorsPolicy</a><span> </span>itself. Looking at the decompiled code for<span> </span><code class="language-plaintext highlighter-rouge">AddCors()</code><span> </span>I could see that the dependency injection calls for<span> </span><code class="language-plaintext highlighter-rouge">ICorsPolicyProvider</code><span> </span>and<span> </span><code class="language-plaintext highlighter-rouge">ICorsService</code><span> </span>were using TryAdd which only adds the default implementations of these interfaces if they have not already been declared.</p>
<pre class="language-csharp"><code>/// <summary>
/// Adds cross-origin resource sharing services to the specified <see cref="IServiceCollection" />.
/// </summary>
/// <param name="services">The <see cref="IServiceCollection" /> to add services to.</param>
/// <returns>The <see cref="IServiceCollection"/> so that additional calls can be chained.</returns>
public static IServiceCollection AddCors(this IServiceCollection services)
{
if (services == null)
{
throw new ArgumentNullException(nameof(services));
}
services.AddOptions();
services.TryAdd(ServiceDescriptor.Transient<ICorsService, CorsService>());
services.TryAdd(ServiceDescriptor.Transient<ICorsPolicyProvider, DefaultCorsPolicyProvider>());
return services;
}</code></pre>
<p><span>Implementation then appeared to be relatively simple. Create a custom Implementation of </span><code class="language-plaintext highlighter-rouge">ICorsPolicyProvider</code><span> that consumed the data saved by my Add-On to create an instance of </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsPolicy.cs">CorsPolicy</a><span> to be consumed by the default implementations of </span><code class="language-plaintext highlighter-rouge">ICorsService</code><span>. The interface of </span><code class="language-plaintext highlighter-rouge">ICorsPolicyProvider</code><span> contained just a single method for me to implement.</span></p>
<pre class="language-csharp"><code>/// <summary>
/// A type which can provide a <see cref="CorsPolicy"/> for a particular <see cref="HttpContext"/>.
/// </summary>
public interface ICorsPolicyProvider
{
/// <summary>
/// Gets a <see cref="CorsPolicy"/> from the given <paramref name="context"/>
/// </summary>
/// <param name="context">The <see cref="HttpContext"/> associated with this call.</param>
/// <param name="policyName">An optional policy name to look for.</param>
/// <returns>A <see cref="CorsPolicy"/></returns>
Task<CorsPolicy?> GetPolicyAsync(HttpContext context, string? policyName);
}</code></pre>
<p><span>To minimise performance issues, my data storage is a single table with a very flat record that is transformed into a domain object with multiple properties and collections. To reduce further round trips to the SQL Server and constructing the domain object and then mapping that over to the </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsPolicy.cs">CorsPolicy</a><span> object, I also stored the compiled </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsPolicy.cs">CorsPolicy</a><span> object into Optimizely’s </span><code class="language-plaintext highlighter-rouge">ISynchronizedObjectInstanceCache</code><span> which would then be invalidated on any subsequent update of the CORS policy.</span></p>
<pre class="language-csharp"><code>public async Task<CorsPolicy?> GetPolicyAsync(HttpContext context, string? policyName)
{
var policy = _cache.Get<CorsPolicy>(CacheKey);
if (policy == null)
{
policy = await LoadPolicy();
_cache.Add(CacheKey, policy);
}
return policy;
}</code></pre>
<p>The end result is a fully functioning CMS editable CORS Policy that can be updated and can take effect immediately without requiring any code changes or deployments. To learn more about how CORS is implemented within .NET Core, you can read<span> </span><a href="https://andrewlock.net/a-deep-dive-in-to-the-asp-net-core-cors-library/">A deep dive into the ASP.NET Core CORS library</a><span> </span>written by<span> </span><a href="https://andrewlock.net/about/">Andrew Lock</a><span> </span>and view the open-source code for the<span> </span><a href="https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/CORS/src/Infrastructure/CorsMiddleware.cs">CorsMiddleware</a><span> </span>on GitHub.</p>
<h2>In Beta</h2>
<p>I’m classing version 2.0.0 of this Add-on as being in beta until one or more CMS websites are live and consuming the CORS configuration and any raised issues are either prioritised or fixed. If you’d like to use the 2.0.0 beta version, do feel free to go ahead and install it into your Optimizely CMS 12 website and join the<span> </span><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/143">discussion</a><span> </span>page on the<span> </span><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely/discussions/143">GitHub Repository</a>.</p>2023-10-09T11:14:38.0000000ZBlog postAdding Block Specific JavaScript and CSS to the body and head of the page<p>A common requirement for CMS implementations includes the ability to embed third party content into a website as if it formed part of the website itself. Sometimes this takes the form of a full page embed like a campaign page and in other cases this can be smaller artefacts within an embed block placed between differing blocks within the flow of a page. Often these embeds come with additional JavaScript and Stylesheet content, which in turn can lead to a Content Security Policy being opened up for an entire site for a single embed on a single page.</p>
<p>The following block provides three separate properties:</p>
<ul>
<li>Embed Code: A text area that will be rendered in it's raw state on a razor file.</li>
<li>Hosted JavaScript File: A content reference for an optimized production JavaScript file that has been uploaded to the CMS to be used by this block and rendered at the bottom of the body of the page.</li>
<li>Hosted CSS File: A content reference for an optimized production stylesheet file that has been uploaded to the CMS to be used by this block and rendered within the head element of the page.</li>
</ul>
<pre class="language-csharp"><code>[ContentType(
DisplayName = "Embed Block",
GUID = "0de2bdc7-9fc1-407d-8a60-2c2fb0e0b85a",
Description = "Allows the content editor to embed third party code snippets.",
GroupName = SystemTabNames.Content)]
public class EmbedBlock : BlockData
{
[Display(
Name = "Embed Code",
Description = "Please paste the full snippet of code to included within the HTML for the page and block.",
GroupName = SystemTabNames.Content,
Order = 10)]
[UIHint(UIHint.Textarea)]
[Required]
public virtual string? EmbedCode { get; set; }
[Display(
Name = "Hosted JavaScript File",
Description = "A CMS Hosted JavaScript file to be rendered at the bottom of the 'body' element.",
GroupName = GroupNames.Content,
Order = 20)]
[AllowedTypes(typeof(JavaScriptContent))]
[CultureSpecific]
public virtual ContentReference? JavaScriptFile { get; set; }
[Display(
Name = "Hosted CSS File",
Description = "A CMS Hosted Cascading Style Sheet file to be rendered at the bottom of the 'head' element.",
GroupName = GroupNames.Content,
Order = 40)]
[AllowedTypes(typeof(CssContent))]
public virtual ContentReference? CssFile { get; set; }
}</code></pre>
<p>When a block is rendered within a content area, any attempt to render the sources for the JavaScript and CSS files will end up being rendered within the container for the block. If you are using the standard razor rendering method for pages within the website, you will have used <strong>@Html.RequiredClientResources(RenderingTags.Header)</strong> to render Optimizely generated styles within the header of the page and scripts within the footer of the body. In this case we can consume the built in Client Resources functionality and register our files to be placed appropriately within the document.</p>
<pre class="language-csharp"><code>public sealed class EmbedBlockViewComponent : BlockComponent<EmbedBlock>
{
private readonly IUrlResolver _urlResolver;
public EmbedBlockViewComponent(IUrlResolver urlResolver)
{
_urlResolver = urlResolver;
}
protected override IViewComponentResult InvokeComponent(EmbedBlock currentContent)
{
if (!ContentReference.IsNullOrEmpty(currentContent.JavaScriptFile))
{
ClientResources.RequireScript(_urlResolver.GetUrl(currentContent.JavaScriptFile)).AtFooter();
}
if (!ContentReference.IsNullOrEmpty(currentContent.CssFile))
{
ClientResources.RequireStyle(_urlResolver.GetUrl(currentContent.CssFile)).AtHeader();
}
return View(currentContent);
}
}</code></pre>
<p>The <strong>ClientResources.RequireScript</strong> and <strong>ClientResources.RequireStyle</strong> methods will ensure that the resources are rendered once per unique file name. This means that if you have two blocks which reference the same JavaScript file, then that JavaScript file is rendered once within the HTML document. Now this is great, but what if you need to defer these embedded resources in order to improve your website performance?</p>
<p>Both of these methods come with additional overrides that allow you to define the name for the resource, it's dependencies and it's additional attributes. For example, the following call:</p>
<pre class="language-csharp"><code>ClientResources.RequireScript(
_urlResolver.GetUrl(currentContent.JavaScriptFile),
currentContent.JavaScriptFile.ID.ToString(), // A nominated unique name for the javascript file
new List<string>(0), // Dependencies
new Dictionary<string, string> { { "defer", "defer" } } // Additional Attributes
).AtFooter();</code></pre>
<p>Will result in the follow script tag being rendered:</p>
<pre class="language-markup"><code><script defer="defer" src="/globalassets/embeds/test.js"></script></code></pre>
<p>You can extend this same functionality to render externally hosted files with additional attributes, which could include cross origin and subresource integrity hashes like the following example</p>
<pre class="language-csharp"><code>var externalJavaScript = "https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js";
var externalJavaScriptSri = "sha384-C6RzsynM9kWDrMNeT87bh95OGNyZPhcTNXj1NW7RuBCsyN/o0jlpcV8Qyq46cDfL";
var attributes = new Dictionary<string, string>
{
{ "defer", "defer" },
{ "crossorigin", "anonymous" },
{ "integrity", externalJavaScriptSri }
};
ClientResources.RequireScript(
externalJavaScript,
externalJavaScript, // A nominated unique name for the javascript file
new List<string>(0), // Dependencies
attributes
).AtFooter();</code></pre>
<p>Which would then render like so:</p>
<pre class="language-markup"><code><script crossorigin="anonymous" defer="defer" integrity="sha384-C6RzsynM9kWDrMNeT87bh95OGNyZPhcTNXj1NW7RuBCsyN/o0jlpcV8Qyq46cDfL" src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script></code></pre>
<h2>In Summary</h2>
<p>When constructing an Optimizely CMS website that allows the embedding of JavaScript and CSS resources, leverage the use of the static <strong>ClientResources.RequireScript</strong> and <strong>ClientResources.RequireStyle</strong> static methods within your controllers and view components to register your resources in order to:</p>
<ul>
<li>Ensure that Stylesheet resources are rendered correctly within the header</li>
<li>Ensure that JavaScript resources are rendered correctly at the bottom of the body</li>
<li>Ensure that all resources are rendered uniquely</li>
<li>Ensure that all resources are rendered with standard attributes for performance.</li>
</ul>2023-10-03T08:54:17.0000000ZBlog postExtending Geta Optimizely Sitemaps to Include Image Sitemaps<h2>The Requirement</h2>
<p><span>One of our Optimizely CMS 12 clients has a media heavy site and part of our SEO brief was to include an Image XML Sitemap to improve visibility of media to search engines such as google. For all of our CMS 12 builds, we like to use the Geta Optimizely Sitemaps plugin as this puts a lot of power into the hands of content editors and SEO specialists. Unfortunately for this particular client, the plugin does not handle image sitemaps.</span></p>
<h3>Image XML Sitemap Format</h3>
<p><span>There are a few reasons why you might want to use an image XML sitemap. Perhaps images on your site are not easily indexable by search engines due to the way they are loaded into the browser, possibly from a separate javascript event so that they do not form part of the initially rendered HTML. Perhaps your site is mobile optimized and only optimized versions of your images are available in your HTML and you want to expose the original images to search engines. So you decide that you do in fact want to use an image XML sitemap, but then there are two separate ways to do implement this.</span></p>
<h4>Image only XML Sitemap</h4>
<p><span>In this format, the image (image:image) node exists as a child of the urlset node and exists once per image within your site:</span></p>
<pre class="language-markup"><code><?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<image:image>
<image:loc>https://www.example.com/image-1.jpg</image:loc>
<image:caption>Everything you need to know about Images</image:caption>
<image:geo_location>London, United Kingdom</image:geo_location>
<image:title>Image Sitemap Example</image:title>
<image:license>Creator: Acme, Credit Line: Acme SEO, Copyright Notice: Free to Use</image:licence>
</image:image>
</urlset></code></pre>
<p><span>Initially I thought that the level of information packaged with the image was excellent as it added a lot of context. However as of May 2022, all nodes except </span><strong>image:image</strong><span> and </span><strong>image:loc</strong><span> were deprecated and are no longer consumed by google. I also tied setting up a sitemap within Geta Optimizely Sitemaps that used an image asset node as it’s root and this included decorating the image content types with the sitemap configuration properties, however this just resulted in an empty sitemap.xml.</span></p>
<h4>Standard XML Sitemap with images</h4>
<p><span>In this format, the image nodes exist as a child of the url node and exists once per image that should be associated with that page:</span></p>
<pre class="language-markup"><code><?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
<url>
<loc>https://example.com/sample1.html</loc>
<lastmod>2023-07-03T16:29:07+01:00</lastmod>
<changefreq>weekly</changefreq>
<priority>0.5</priority>
<image:image>
<image:loc>https://example.com/image.jpg</image:loc>
</image:image>
<image:image>
<image:loc>https://example.com/photo.jpg</image:loc>
</image:image>
</url>
<url>
<loc>https://example.com/sample2.html</loc>
<image:image>
<image:loc>https://example.com/picture.jpg</image:loc>
</image:image>
</url>
</urlset></code></pre>
<p><span>In this format, the context of an image is directly related to the page, but other than defining that the image exists, no additional context is provided. This format did have the benefit of being able to follow the content tree which simplified the extending of the Geta Optimizely Sitemap solution.</span></p>
<h2>The Solution</h2>
<p>The core generation functionality for XML sitemaps within Geta Optimizely Sitemaps comes down to one primary abstract class called<span> </span><a href="https://github.com/Geta/geta-optimizely-sitemaps/blob/master/src/Geta.Optimizely.Sitemaps/XML/SitemapXmlGenerator.cs">SitemapXmlGenerator</a><span> </span>and all the XML Sitemap formats all inherit and extend this class by overriding specific methods. The core logic has been split out into lots of different methods, each with a single responsibility that has been marked as virtual to allow for them to be overridden.</p>
<p>The first step was to make our own implementation of<span> </span><a href="https://github.com/Geta/geta-optimizely-sitemaps/blob/master/src/Geta.Optimizely.Sitemaps/XML/IStandardSitemapXmlGenerator.cs">IStandardSitemapXmlGenerator</a><span> </span>that inherits the<span> </span><a href="https://github.com/Geta/geta-optimizely-sitemaps/blob/master/src/Geta.Optimizely.Sitemaps/XML/SitemapXmlGenerator.cs">SitemapXmlGenerator</a><span> </span>and to then override the dependency injection to replace Geta’s implementation with our own:</p>
<pre class="language-csharp"><code>public class StandardAndImageSitemapXmlGenerator : SitemapXmlGenerator, IStandardSitemapXmlGenerator
{
public StandardAndImageSitemapXmlGenerator(
ISitemapRepository sitemapRepository,
IContentRepository contentRepository,
IUrlResolver urlResolver,
ISiteDefinitionRepository siteDefinitionRepository,
ILanguageBranchRepository languageBranchRepository,
IContentFilter contentFilter,
IUriAugmenterService uriAugmenterService,
ISynchronizedObjectInstanceCache objectCache,
IMemoryCache cache,
ILogger<StandardSitemapXmlGenerator> logger)
: base(
sitemapRepository,
contentRepository,
urlResolver,
siteDefinitionRepository,
languageBranchRepository,
contentFilter,
uriAugmenterService,
objectCache,
cache,
logger)
{
}
}</code></pre>
<pre class="language-csharp"><code>public static class GetaOptimizelySitemapsServiceExtension
{
public static IServiceCollection AddGetaOptimizelySitemapsHandler(this IServiceCollection serviceCollection)
{
serviceCollection.AddSitemaps();
// Geta injects the generators as Transient, so maintain the same scoping:
serviceCollection.AddTransient<IStandardSitemapXmlGenerator, StandardAndImageSitemapXmlGenerator>();
return serviceCollection;
}
}</code></pre>
<p><span>The first method that needed to be overridden is called GenerateRootElement and this is responsible for creating the urlset node and adding the standard namespace for an XML sitemap. In our case we need to add an additional namespace for the image sitemaps:</span></p>
<pre class="language-csharp"><code>public class StandardAndImageSitemapXmlGenerator : SitemapXmlGenerator, IStandardSitemapXmlGenerator
{
private readonly ILogger<StandardSitemapXmlGenerator> _logger;
private readonly XNamespace _imageNamespace;
private readonly XAttribute _imageAttribute;
public StandardAndImageSitemapXmlGenerator(...) : base(...)
{
_logger = logger;
_imageNamespace = XNamespace.Get("http://www.google.com/schemas/sitemap-image/1.1");
_imageAttribute = new XAttribute(XNamespace.Xmlns + "image", _imageNamespace.NamespaceName);
}
protected override XElement GenerateRootElement()
{
var rootElement = new XElement(SitemapXmlGenerator.SitemapXmlNamespace + "urlset", _imageAttribute);
if (this.SitemapData.IncludeAlternateLanguagePages)
rootElement.Add((object)new XAttribute(XNamespace.Xmlns + "xhtml", (object)SitemapXmlGenerator.SitemapXhtmlNamespace));
return rootElement;
}
}</code></pre>
<p>This overridden method is a clone of the base method. In order for the image namespace to be rendered correctly within the XML document, we have to create the image attribute as a direct child of the urlset node at the point in time the node is created. Attempting to use the base method and then appending the XAttribute led to undesired prefixing of namespaces within the parent node.</p>
<p>The next step was to make sure content types had a common method that could be used to identify images that should be included with the page in the XML sitemap. This could easily be a property that allows the CMS Editor to have full control of said images. This would also need to be identifiable to the generation logic, so I added an interface that could be used to identify pages with images:</p>
<pre class="language-csharp"><code>public interface ISitePageWithSitemapImages : IContent
{
IList<ContentReference> SitemapImages { get; }
}
public class SitePageData : PageData, ISitePageWithSitemapImages
{
public virtual IList<ContentReference> GetSitemapImages()
{
var images = new List<ContentReference>();
// Image resolution logic goes here and is overridden for different content types
return images;
}
}</code></pre>
<p><span>The final part of the puzzle is then to override the GenerateSiteElement method within the </span><a href="https://github.com/Geta/geta-optimizely-sitemaps/blob/master/src/Geta.Optimizely.Sitemaps/XML/SitemapXmlGenerator.cs">SitemapXmlGenerator</a><span>. This method’s responsibility is to create the URL node and all of it’s child elements. In this case I was able to leverage the base method and extend it to parse and add image nodes only if the page implemented my interface:</span></p>
<pre class="language-csharp"><code>public class StandardAndImageSitemapXmlGenerator : SitemapXmlGenerator, IStandardSitemapXmlGenerator
{
private readonly ILogger<StandardSitemapXmlGenerator> _logger;
private readonly XNamespace _imageNamespace;
private readonly XAttribute _imageAttribute;
// Constructor and GenerateRootElement go here
protected override XElement GenerateSiteElement(IContent contentData, string url)
{
var pageElement = base.GenerateSiteElement(contentData, url);
var urlResolverArgs = new UrlResolverArguments { ForceAbsolute = true };
if (contentData is ISitePageWithSitemapImages pageData)
{
try
{
foreach (var sitemapImage in pageData.GetSitemapImages())
{
var imageUrl = UrlResolver.GetUrl(sitemapImage, "en", urlResolverArgs);
var image = new XElement(_imageNamespace + "loc", (object)imageUrl);
pageElement.Add(new XElement(_imageNamespace + "image", image));
}
}
catch (Exception ex)
{
_logger.LogError(ex, "Oh No!");
}
}
return pageElement;
}
}</code></pre>
<p><span>The final generated XML Sitemap looks like this (please note I’ve sanitised the URLs generated here):</span></p>
<pre class="language-markup"><code><?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://www.example.com/en/test-page-one/</loc>
<lastmod>2023-07-03T16:29:07+01:00</lastmod>
<changefreq>weekly</changefreq>
<priority>0.5</priority>
<image:image>
<image:loc>https://www.example.com/globalassets/images/image-one.jpg</image:loc>
</image:image>
<image:image>
<image:loc>https://www.example.com/globalassets/images/image-two.jpg</image:loc>
</image:image>
</url>
<url>
<loc>https://localhost:5000/en/test-page-two/</loc>
<lastmod>2023-07-07T14:44:30+01:00</lastmod>
<changefreq>weekly</changefreq>
<priority>0.5</priority>
<image:image>
<image:loc>https://www.example.com/globalassets/images/image-three.jpg</image:loc>
</image:image>
<image:image>
<image:loc>https://www.example.com/globalassets/images/image-four.jpg</image:loc>
</image:image>
</url>
</urlset>
</code></pre>
<h2>Conclusion</h2>
<p>The end result is that we can generate XML Sitemaps with image elements. Some consideration needs to be made around your own implementation and how you want to manage images. Do you want your SEO team to be able to curate this or do you want it to be automated through some custom logic? This could be enhanced futher to include video elements and news elements. More details around these XML Sitemap variants can be found here:<span> </span><a href="https://moz.com/learn/seo/xml-sitemaps">https://moz.com/learn/seo/xml-sitemaps</a>.</p>
<h3>Limitations</h3>
<p>There are some additional considerations to be made in terms of the size of XML Sitemaps here, especially if you start adding all of the media types. Here are some limitations extrapolated from google’s developer documentation (which is worth a read around best practices):<span> </span><a href="https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap">https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap</a></p>
<ul>
<li>Maximum XML Sitemap file size: 50MB</li>
<li>Maximum number of URL nodes per sitemap: 50000</li>
<li>Maximum number of Image nodes per URL node: 1000</li>
<li>Maximum number of News nodes per URL node: 1000</li>
<li>Maximum number of Video nodes per URL node: 1000? (This is based on other limits, but was not overtly declared on google’s guidance)</li>
</ul>2023-07-31T08:20:14.0000000ZBlog postMaking Content Recommendations easy for content editors<h2>The Problem</h2>
<p>One of our clients had purchased the Content Recommendations module for use within their newly build CMS 12 corporate site. Our challenge was that the main content team lacked development expertese and would outsource functionality like embedded content to external parties. On top of this, the client had a desire for consistency in design across the system. In it's default implementation, the addition of content recommendations across the system would require content editors to make changes to the handlebars scripts for every instance of the block.</p>
<h2>The Solution</h2>
<p>Our solution for this was to create a Custom Content Recommendations Block that obfuscates a number of the options on the default Content Recommendations Block and added additional properties that would allow them to render Content Recommendations as if it were the same design as another block within the site. The key properties that I hid in this case were the Number of Recommendations and Recommendations Template properties.</p>
<pre class="language-csharp"><code>// Display and ContentType attributes omitted for brevity.
public class CustomContentRecommendationsBlock : ContentRecommendationsBlock
{
public virtual string? Title { get; set; }
public virtual string? Subtitle { get; set; }
public virtual bool OmitCardDescriptions { get; set; }
public virtual string? ReadMoreText { get; set; }
public virtual ContentReference? FallBackImage { get; set; }
[ScaffoldColumn(false)]
public override int NumberOfRecommendations
{
get { return 4;}
set { _ = value; }
}
[ScaffoldColumn(false)]
public override string? RecommendationsTemplate
{
get { return "Template is in the razor file."; }
set { _ = value; }
}
}</code></pre>
<p>The razor file itself was then created to conditionally render elements within the Content Recommendations script tag on the server side in accordance with the designs by our creative team. To handle recommendations which lacked a main image, a fallback image was rendered server side within the <code>{{^main_image_url}}</code> handlebars tag. Markup with <code>{{^main_image_url}}</code> is then only rendered by the content recommendations code when the <code>main_image_url</code> is null.</p>
<pre class="language-csharp"><code>@model CustomContentRecommendationsBlock
<script class="idio-recommendations" type="text/x-mustache" data-api-key="@Model.DeliveryApiKey" data-rpp="@Model.NumberOfRecommendations">
<div class="container">
<div class="cards-container">
@if (!string.IsNullOrWhiteSpace(Model.Title) || !string.IsNullOrWhiteSpace(Model.Subtitle))
{
<div class="block__intro">
@if (!string.IsNullOrWhiteSpace(Model.Title))
{
<h2>@Html.PropertyFor(x => x.Title)</h2>
}
@if (!string.IsNullOrWhiteSpace(Model.Subtitle))
{
<p>@Html.PropertyFor(x => x.Subtitle)</p>
}
</div>
}
<div class="cards-rows">
<div class="cards" data-component="Cards">
{{#content}}
<div class="card" data-item>
<!-- Teaser Card -->
<!-- Image -->
{{#main_image_url}}
<div class="card__image">
<img src="{{main_image_url}}?width=560&height=299&quality=90&rmode=crop" alt="{{title}}">
</div>
{{/main_image_url}}
{{^main_image_url}}
@if (!Model.FallbackImage.IsNullOrEmpty())
{
<div class="card__image">
<img src="@Url.ImageUrl(Model.FallBackImage, 560, 299)" alt="@Model.FallBackImage.GetImageAltText()">
</div>
}
{{/main_image_url}}
<!-- Category -->
{{#topics}}
<div class="card__category">{{title}}</div>
{{/topics}}
<!-- Content -->
<div class="card__content">
<h4>{{title}}</h4>
@if (!Model.OmitCardDescriptions)
{
<p>{{abstract}}</p>
}
<a href="{{link_url}}" class="solid-arrow-link" title="{{title}}" data-label_1="{{title}}">@Model.ReadMoreText</a>
</div>
</div>
{{/content}}
</div>
</div>
</div>
</div>
</script></code></pre>
<p>There were additional concerns that had to be addressed, the first being that the design of the block only allowed for a single category (Topic) to be rendered for each content card. In this case we addressed this by using CSS styles to render hide off all but the first category.</p>
<h3>Alternative Solution</h3>
<p>Another approach to the solution would have been for us to look at overriding the default value assigned to the RecommendationsTemplate property so that when new Content Recommendations block was created, it would retain the ability for the content editor to customize the layout of the content recommendations. This was an approach we chose not to go with in this situation as it still presented non-technical content editors with a technical property that they were not comfortable using. Our chosen approach also allowed for functionality such as the fall back image to be updated centrally and immediately affect all custom content recommendation blocks within the site.</p>
<h2>Client Expectations vs Reality</h2>
<p>Within the CMS, the editor has the ability to prioritise categories that are displayed on cards shown on other blocks and they have the ability to provide an optional Teaser Title and Teaser Description against a page that is used across the site for that page that is different to standard meta data. The client's expectation was that all of the content recommendations would render the exact same content and categories as if the teaser content had been curated by themselves on a regular block within the site. We had to explain how Content Recommendations worked:</p>
<ul>
<li>That Content Recommendations is based on a scan of the fully rendered page</li>
<li>That Content Recommendations does not have direct access to the raw CMS data.</li>
<li>That it would not be a live replication of changes within the CMS.</li>
<li>That Content Recommendations come from the cloud service and not directly from the CMS.</li>
</ul>
<p>Ultimately the client understood this and is now using the custom content recommendations block across their live site. In our next phase of Content Recommendations, we want to look at pushing additional meta data into Content Recommendations that matches the teaser data defined by the content editor and then hopefully retrieve and display this data within the results from Content Recommendations.</p>2023-07-07T12:18:20.0000000ZBlog postBuild it Once (A proposal for CMS 12 builds)<h2>Introduction</h2>
<p>The following is based on a 30 minute presentation performed by myself at Optimizely North in Manchester on the 1st March 2023. Some of this content is based on question and answer sections performed on the day as well as observing builds that I have contributed to that have origins both internal and external to the agency that I am currently with. It should be noted that this is the proposition of an approach to help reduce the duplication of effort and to allow developers to focus on what is truely unique to a client.</p>
<h2>The Problem</h2>
<p>As Agencies we build sites for multiple customers and commonly end up building a lot of the same components over and over again. Most agencies have considered at least one solution to how we can save our development teams from repeating the same tasks with every single build. Solutions including:</p>
<ul>
<li>Having a starter solution that all client builds start from.
<ul>
<li>Optimizely have similar solutions such as Alloy, Quicksilver and Foundation, however these may not fit in with coding standards or architectural standards of individual agencies.</li>
</ul>
</li>
<li>Having a folder of pre-built common components that are copied into a new build that are then modified for the specific client</li>
</ul>
<p>These are essentially a copy and paste situations and do ultimately save on some time within a new website build and as part of this presentation and now blog, I attempt to offer another possible solution if we consider a change in how we build Optimizely websites.</p>
<h2>The Technology</h2>
<p>Optimizely CMS 12 has now been available to the community for 18+ months and as part of the shift to .NET 6+, we have a new development tools available that we can use to componentise our builds. A personal favourite of mine is the <a href="https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-7.0&amp;amp;amp;tabs=visual-studio">Razor Class Library</a> (RCL) which I have used now to build two different plugins for Optimizely CMS 12. A Razor Class Library is a standard class library that can also contain Razor files and static assets within it's own wwwroot folder. These can in turn be packaged as their own nuget package or dll that contains it's own razor files and static assets that can be added to any other build.</p>
<p>The great thing about Razor Class Libraries is that if you do not specify a layout file for your razor files within the library, the layout file from the website consuming the Razor Class Library will be used instead. And if you provide a Razor file on the same folder structure as that contained within the Razor Class Library, the razor file from the consuming website is used in place of the razor file in the razor class library. This allows you to optionally replace the render for any given component packaged within the Razor Class Library.</p>
<p><em>For example:</em></p>
<p>In my <a href="https://github.com/GeekInTheNorth/opti-north-feb-2023">demo build</a> for this topic I structured the code into three separate projects:</p>
<ul>
<li>OptiNorthDemo.Core
<ul>
<li>This project contained common assets that would theoretically be utilized by all product based projects.</li>
</ul>
</li>
<li>OptiNorthDemo.News
<ul>
<li>This project contained components that made up a news feature including:
<ul>
<li>A News Article Page</li>
<li>A News Listing Page</li>
<li>News Listing and filtering logic</li>
</ul>
</li>
<li>This project could then be expanded to contain additional News features:
<ul>
<li>Releated News Block</li>
<li>Front end News Listing component built using the preferred framework of your agency (e.g. React)</li>
</ul>
</li>
</ul>
</li>
<li>OptiNorthDeno
<ul>
<li>This project was the base website for the demo which then referenced OptiNorthDemo.News and OptiNorthDemo.Core as nuget packages.</li>
</ul>
</li>
</ul>
<p>This solution contains a Razor file on the path of <strong>OptiNorthDemo.News/Views/NewsArticlePage/Index.cshtml</strong> and when I ran the solution the razor file from that path was used to render the article. When I then added a razor file on the path of <strong>OptiNorthDemo/Views/NewsArticlePage/Index.cshtml</strong>, the razor file from the <strong>OptiNorthDemo</strong> project was used instead while all of the existing business logic and controller logic from the <strong>OptiNorthDemo.News</strong> project facilitated the program flow.</p>
<h2>The Proposition</h2>
<p>If we analyze all that we build across all of the websites we currently manage / develop, we should be able to identify common themes or features. We should then be able to identify what makes these individual features work well and design a content structure and business logic structure that should fulfil the needs of most if not all usages of that feature. We should then fully build out that feature and manage it as a product. </p>
<p>Going back to our news example again, a single Razor Class Library would reference our core package and then contain the News Article Page, News Listing page, a Related News Block and all of the core business logic that makes it work e.g. Optimizely Search and Navigation queries, API endpoints and frontend listing and search components.</p>
<p>In order to make this work, we need to think of our content structures in a more Atomic Content way. This means less fixed fields and page flow and more thought about flexible content block usage. We also need to think about minimising the usage of Content Type restrictions to targeting interfaces that allow specific functional categories of blocks. For example, we can think of blocks as "Hero Blocks" for use at the top of pages, "Content Blocks" as core page content and as "Related Blocks" as additional content that could follow core page content. All of these would have to be declared in a core project that all of our feature would use. e.g.</p>
<pre class="language-csharp"><code>namespace OptiNorthDemo.Core.Blocks;
using EPiServer.Core;
using EPiServer.Shell;
/// <summary>
/// Used to define a standard content block to be allowed in main content areas.
/// This combined with <see cref="ContentBlockUiDescriptor"/> simplify these declarations.
/// </summary>
public interface IContentBlock : IContentData
{
}
/// <summary>
/// Used to help Optimizely CMS UI Recognize the <see cref="IContentBlock"/> interface.
/// This allows us to simplify which blocks are allowed in main content areas.
/// </summary>
[UIDescriptorRegistration]
public class ContentBlockUiDescriptor : UIDescriptor<IContentBlock>
{
}</code></pre>
<p>Going back to our News Page example, we would inherit a base set of page properties from the core project and then apply our content area restrictions based on interfaces defined within the core project but implemented either in additional packages or directly within a client specific build.</p>
<pre class="language-csharp"><code>[ContentType(DisplayName = "News Article Page", Description = "A flexible news article page.", GUID = "DADC30C2-7F68-45F3-B279-FD4446B9B3CA", GroupName = GroupNames.Content)]
public class NewsArticlePage : SitePageData
{
// Some other news article specific fields...
[Display(
Name = "Article Content",
Description = "A content area that allows blocks that have been specifically designed as core content.",
GroupName = GroupNames.Content,
Order = 110)]
[AllowedTypes(typeof(IContentBlock))]
public virtual ContentArea? ArticleContent { get; set; }
[Display(
Name = "Additional Content",
Description = "A content area that allows blocks that have been specifically designed as related content.",
GroupName = GroupNames.Content,
Order = 120)]
[AllowedTypes(typeof(IRelatedContentBlock))]
public virtual ContentArea? AdditionalContent { get; set; }
}</code></pre>
<p>As agencies it is common to sell development time. The dream here with this approach is to allow us to sell Value and Time. So lets imagine that a client comes in and as part of their discovery they understand that they need an Optimizely Site, that it comes with Case Studies, News, Events, Products, General Content etc. As part of applying that cost we turn around to the client and we give them the something closer to the following list of made up numbers:</p>
<ul>
<li>Case Studies: £20,000 package plus 3 days for customization</li>
<li>News: £20,000 package plus 3 days for customization</li>
<li>Products: 20 days develop and build (product properties vary wildly between business types)</li>
</ul>
<p>The end result being less time spent developing the common stuff and being able to either improve profit margins or do more for our clients with their budgets.</p>
<h3>Problems with this approach</h3>
<p>It is not expected that that this would be achieveable to fulfill for all possible agencies to use a single feature. Each agency will have it's own coding standards, it's own preferred list of plugins they like to use within each of their builds, it's own preferred architectural structures and frontend libraries. e.g. different agencies might have frontend teams that specialise in React, Angular, Vue etc. It is also expected that this would only work if you are adopting a more Atomic content structure with minimal content type and block type restrictions.</p>
<h4>1. Who looks after this and how do we stop it going out of date?</h4>
<p>To keep a product or feature up to date, it needs to be allocated a Product Owner, someone who is responsible for the product or feature and ensuring it is not forgotten. After it's initially been built, keeping the module up to date can either be factored in to the additional needs of a specific client or the needs of keeping packages up to date.</p>
<h4>2. What if a client leaves and our nuget feed is internal?</h4>
<p>For any given feature, this would require the nuget reference is removed from the website project and the matching version of the project is added to the solution. This would mean that you should version each "release" of a given feature and ensure that the relevant commit within the repository is correctly tagged with the release version to make this task as easy as possible.</p>
<h4>3. What if I need to change the structure of the markup for a specific build?</h4>
<p>This would be a simple case of creating a new razor file on the same path but within the client specific website.</p>
<h4>4. What if there are properties that client does not need that I want to hide?</h4>
<p>It is possible to create an <strong>EditorDescriptor</strong> that is decorated with the <strong>EditorDescriptorRegistration</strong> attribute and then use this to hide properties from the CMS editor. In the following code snippet I have created a base <strong>EditorDescriptor</strong> called <span><strong>HideDefaultFieldsEditorDescriptor</strong> and then created additional classes which inherit from <strong>HideDefaultFieldsEditorDescriptor</strong> and simply have the correct target field types applied. This logic is executed when a field is rendered within the CMS interface and then sets it's visibility to false if it is within a given list of hidden page and properties.</span></p>
<pre class="language-csharp"><code>[EditorDescriptorRegistration(EditorDescriptorBehavior = EditorDescriptorBehavior.PlaceLast, TargetType = typeof(ContentArea))]
public class HideDefaultContentAreasEditorDescriptor : HideDefaultFieldsEditorDescriptor
{
}
[EditorDescriptorRegistration(EditorDescriptorBehavior = EditorDescriptorBehavior.PlaceLast, TargetType = typeof(DateTime?))]
public class HideDefaultDateTimesEditorDescriptor : HideDefaultFieldsEditorDescriptor
{
}
public class HideDefaultFieldsEditorDescriptor : EditorDescriptor
{
public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
{
base.ModifyMetadata(metadata, attributes);
var contentType = metadata.FindOwnerContent()?.GetOriginalType()?.Name;
var propertyName = metadata.PropertyName;
if (ShouldHideField(contentType, propertyName))
{
metadata.ShowForEdit = false;
}
}
private static bool ShouldHideField(string? contentType, string? propertyName)
{
var hiddenFields = new List<Tuple<string, string>>
{
new("NewsArticlePage", "AdditionalContent"),
new("NewsArticlePage", "DisplayPublishedDate")
};
return hiddenFields.Any(x =>
string.Equals(x.Item1, contentType, StringComparison.OrdinalIgnoreCase) &&
string.Equals(x.Item2, propertyName)
);
}
}</code></pre>
<h2>In Summary</h2>
<p>With the advent of .NET 6+, CMS 12 and the concept of Atomic Content, are we now truely in a place where we can conceptualize content features as packages that are built once and installed into multiple clients and then customized to match their design? With the power of Razor Class Libraries we are now able to create extensible collections of content features, the question does remain if we are able to make that next leap forward into selling value.</p>
<h2>References</h2>
<ul>
<li><a href="https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-7.0&amp;amp;amp;tabs=visual-studio">https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-7.0&tabs=visual-studio</a></li>
<li><a href="https://github.com/GeekInTheNorth/opti-north-feb-2023">https://github.com/GeekInTheNorth/opti-north-feb-2023</a></li>
</ul>2023-03-05T17:37:45.0000000ZBlog post404 Error on Static Assets Within an Optimizely plugin<h2>Background</h2>
<p>With the move to CMS 12 and .NET 5/6, developers are now able to build Plugins and Extensions using Razor Class Libraries (RCL). These are a fantastic option as it allows you to bundle up any client side scripts, styles and razor files into the same compiled dll as your buisness logic. The structure of the Razor files and static files within an RCL is the same structure as what you would expect to see within a Web project.</p>
<p>The biggest benefit is that it makes it very clean to install and remove said plugin as it does not require any zip files to be deployed into a modules folder and really compartmentalizes your plugin. To date I have built two different plugins which utilize Razor Class Libraries:</p>
<ul>
<li><a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler">Stott.Optimizely.RobotsHandler</a> currently at v2.1.0</li>
<li><a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">Stott.Security.Optimizely</a> currently in early access at 0.4.0</li>
</ul>
<h2>The Problem</h2>
<p>I was contacted by <a href="/link/5341f632537c4b0ab6b8fb651bd310f8.aspx?userId=fd64fb7a-ba91-e911-a968-000d3a441525">Praveen Soni</a> on the Optimizely Community slack about an issue they were encountering. In development the <a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler">Stott.Optimizely.RobotsHandler</a> module was working as anticipated, however when it deployed into DXP they were receiving a 404 error on the following file: </p>
<pre class="language-markup"><code>https://example.dxcloud.episerver.net/_content/Stott.Optimizely.RobotsHandler/RobotsAdmin.js </code></pre>
<p>Praveen and I chatted some more, we talked about the requirements within the startup.cs file, I got them to share their error logs in hopes of trying to understand why this javascript file from the Razor Class Library was not being served.</p>
<p>I later stumbled upon this article that resonated with the issue that we were encountering: <a href="https://dev.to/j_sakamoto/how-to-deal-with-the-http-404-content-foo-bar-css-not-found-when-using-razor-component-package-on-asp-net-core-blazor-app-aai">How to deal with the "HTTP 404 '_content/Foo/Bar.css' not found" when using Razor component package on ASP.NET Core Blazor app</a> and this led me back to this article on the microsoft website <a href="https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-6.0&amp;amp;tabs=visual-studio">Create reusable UI using the Razor class library project in ASP.NET Core</a> </p>
<h2>The Solution</h2>
<p>If your Razor Class library includes Razor Pages, then the following methods need to called with the the Startup.cs of the consuming application:</p>
<pre class="language-csharp"><code>services.AddRazorPages();
app.MapRazorPages();</code></pre>
<p>If your Razor Class library includes static files like .css and .js files, then a call to <strong>UseStaticWebAssetts()</strong> must be used in the Program.cs of the consuming application:</p>
<pre class="language-csharp"><code>public static class Program
{
public static void Main(string[] args) => CreateHostBuilder(args).Build().Run();
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureCmsDefaults()
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
webBuilder.UseStaticWebAssets();
});
}</code></pre>
<p>Now here is the fun part: if the <strong>ASPNETCORE_ENVIRONMENT</strong> environment variable is set to <strong>Development</strong>, then .NET automatically includes a call to <strong>UseStaticWebAssets()</strong>, if it is set to any other value, then you have to manually add this to your code! It is this final part of the puzzle which explains why the code worked perfectly in some environments but failed in others.</p>2022-09-23T08:07:09.0000000ZBlog postUnit Testing with Dynamic Data Store in CMS 12 - Part 2<h2>Background</h2>
<p>In the previous article of this series,<span> </span><a href="/link/2e3e343bbab64aeebee0526bfa2ac366.aspx">Unit Testing Optimizely CMS 12 Dynamic Data Store - Part 1</a>, an introduction was given to what the Dynamic Data Store is, and an approach was given for unit testing by mocking the<span> </span><code>DynamicDataStore</code><span> </span>object.</p>
<p>In this article we are covering a different approach where we abstract away the usage of the Dynamic Data Store behind an interface with minimal logic.</p>
<h2>Approach</h2>
<p>Developers who are familiar with Entity Framework (EF) or Unit of Work (UOW) pattern may see some familiarity with this approach, and EF was indeed my inspiration here.</p>
<p>For this example, I am using a custom data object which implements the<span> </span><code>IDynamicData</code><span> </span>interface required for use with Dynamic Data Store:</p>
<pre class="language-csharp"><code>public class MyCustomDataObject : IDynamicData
{
public Identity Id { get; set; }
public string UniqueText { get; set; }
public string SomeOtherText { get; set; }
}</code></pre>
<p><span>Next we add an interface for data context, and since this will potentially expose multiple data collections, we also add an interface for operations on a data collection:</span></p>
<pre class="language-csharp"><code>public interface IDdsContext
{
IDdsEntityCollection<MyCustomDataObject> MyCustomDataObjects { get; }
}
public interface IDdsEntityCollection<TModel>
where TModel : IDynamicData
{
IOrderedQueryable<TModel> Items();
IEnumerable<TModel> AllItems();
TModel Get(Identity identity);
IEnumerable<TModel> Find(string propertyName, object propertyValue);
Identity Save(TModel entity);
}</code></pre>
<p><span>Next we need to add a implementation of the <code>IDdsEntityCollection<TModel></code> to facilitate data operations against a singular data type. As you will see below, each of the implemented methods is as light weight as possible. If you are using additional methods within the Dynamic Data Store, then you will need to extend this interface and implementation.</span></p>
<pre class="language-csharp"><code>public class DdsEtityCollection<TModel> : IDdsEntityCollection<TModel>
where TModel : IDynamicData
{
private DynamicDataStore _dynamicDataStore;
public DdsEtityCollection(DynamicDataStoreFactory dynamicDataStoreFactory)
{
_dynamicDataStore = dynamicDataStoreFactory.CreateStore(typeof(TModel));
}
public IOrderedQueryable<TModel> Items()
{
return _dynamicDataStore.Items<TModel>();
}
public IEnumerable<TModel> AllItems()
{
return _dynamicDataStore.LoadAll<TModel>() ?? Enumerable.Empty<TModel>();
}
public TModel Get(Identity identity)
{
return _dynamicDataStore.Load<TModel>(identity);
}
public IEnumerable<TModel> Find(string propertyName, object propertyValue)
{
return _dynamicDataStore.Find<TModel>(propertyName, propertyValue);
}
public Identity Save(TModel entity)
{
return _dynamicDataStore.Save(entity);
}
}</code></pre>
<p><span>Now we have an implementation of <code>IDdsEntityCollection<TModel></code>, we can now implement <code>IDdsContext</code>. In this example, the implementation of <code>IDdsEntityCollection<TModel></code> is not instantiated until it is actually required by the consuming code.</span></p>
<pre class="language-csharp"><code>public class DdsContext : IDdsContext
{
private DynamicDataStoreFactory _dataStoreFactory;
public DdsContext(DynamicDataStoreFactory dataStoreFactory)
{
_dataStoreFactory = dataStoreFactory;
}
private IDdsEntityCollection<MyCustomDataObject> _myCustomDataObjects = null;
public IDdsEntityCollection<MyCustomDataObject> MyCustomDataObjects
{
get
{
if (_myCustomDataObjects == null)
{
_myCustomDataObjects = new DdsEtityCollection<MyCustomDataObject>(_dataStoreFactory);
}
return _myCustomDataObjects;
}
}
}</code></pre>
<p><span>Now we can update the repository we created in <a href="/link/2e3e343bbab64aeebee0526bfa2ac366.aspx">Part 1</a> of this series, stripping out the Dynamic Data Store objects and injecting the <code>IDdsContext</code> instead.</span></p>
<pre class="language-csharp"><code>public class MyCustomDataObjectRepository
{
private readonly IDdsContext _context;
public MyCustomDataObjectRepository(IDdsContext context)
{
_context = context;
}
public void Save(Guid id, string uniqueText, string someOtherText)
{
var matchingRecord = _context.MyCustomDataObjects.Find(nameof(MyCustomDataObject.UniqueText), uniqueText).FirstOrDefault();
if (matchingRecord != null && !matchingRecord.Id.ExternalId.Equals(id))
{
throw new EntityExistsException($"An entry already exists for the unique value of '{uniqueText}'.");
}
var recordToSave = Guid.Empty.Equals(id) ? CreateNewRecord() : _context.MyCustomDataObjects.Get(Identity.NewIdentity(id));
recordToSave.UniqueText = uniqueText;
recordToSave.SomeOtherText = someOtherText;
_context.MyCustomDataObjects.Save(recordToSave);
}
private static MyCustomDataObject CreateNewRecord()
{
return new MyCustomDataObject { Id = Identity.NewIdentity() };
}
}</code></pre>
<p><span>Finally, we can write the same unit tests again, however we are now mocking interfaces inside of our repositories instead of mocking the implementations of the Dynamic Data Store.</span></p>
<pre class="language-csharp"><code>[TestFixture]
public class MyCustomDataObjectRepositoryTests
{
private Mock<IDdsEntityCollection<MyCustomDataObject>> _mockDataCollection;
private Mock<IDdsContext> _mockContext;
private MyCustomDataObjectRepository _repository;
[SetUp]
public void SetUp()
{
_mockDataCollection = new Mock<IDdsEntityCollection<MyCustomDataObject>>();
_mockContext = new Mock<IDdsContext>();
_mockContext.Setup(x => x.MyCustomDataObjects).Returns(_mockDataCollection.Object);
_repository = new MyCustomDataObjectRepository(_mockContext.Object);
}
[Test]
public void GivenUniqueTextExistsAgainstAnotherEntity_ThenAnEntityExistsExceptionShouldBeThrown()
{
// Arrange
var uniqueText = "i-am-unique";
var someOtherText = "some-other-text";
var existingRecord = new MyCustomDataObject
{
Id = Guid.NewGuid(),
UniqueText = uniqueText,
SomeOtherText = "original-other-text"
};
_mockDataCollection.Setup(x => x.Find(It.IsAny<string>(), It.IsAny<object>()))
.Returns(new List<MyCustomDataObject> { existingRecord });
// Assert
Assert.Throws<EntityExistsException>(() => _repository.Save(Guid.Empty, uniqueText, someOtherText));
}
}</code></pre>
<h2>Summary</h2>
<p>This approach to unit testing with the Dynamic Data Store did the following.</p>
<ul>
<li>Created a data collection interface and implementation using generics for operations on the<span> </span><code>DynamicDataStore</code><span> </span>object for a given type.</li>
<li>Created an interface and implementation of a data context which exposed only interfaces for the data collections.</li>
<li>Injected the interface data context into repositories instead of the Dynamic Data Store.</li>
</ul>
<h2>Which Approach</h2>
<p>When deciding which approach to take, consider just how many operations and data types you will be using with the Dynamic Data Store. Consider whether all of the scaffolding of the data context approach in this article out weighs your usage of the Dynamic Data Store. Remember the<span> </span><a href="https://en.wikipedia.org/wiki/KISS_principle">KISS</a><span> </span>and<span> </span><a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY</a><span> </span>principals and I'm sure you'll get the right solution for your project.</p>
<p>Finally, if you are finding you are heavily using the Dynamic Data Store, consider using your own tables using Entity Framework or any other Object Relational Mapper (ORM). You will have better performance with data tables which are designed to suit your data needs.</p>2022-05-26T11:03:27.0000000ZBlog postUnit Testing with Dynamic Data Store in CMS 12 - Part 1<h2>Background</h2>
<p>If you've never heard of it, the<span> </span><a href="https://docs.developers.optimizely.com/content-cloud/v12.0.0-content-cloud/docs/dynamic-data-store">Dynamic Data Store (DDS)</a><span> </span>which is a component that offers an API and infrastructure for CRUD operations of custom data objects. It allows developers to access and store data without needing to provision custom tables or databases using either classes or property bags which are stored within shared tables contained in the CMS database.</p>
<p>Optimizely also use the same functionality for some of their own features. For example, Optimizely Search & Navigation comes with a feature known as Best Bets which allows content editors to provide search suggestions for given search terms. Each Best Bet has it's own entry inside of the Dynamic Data Store.</p>
<p>This article is the first of two articles showing developers how they can unit test with the Dynamic Data Store, each with it's own separate technical approach. Both approaches are valid, but the choice in approach may come down to how many different operations you are under taking with the Dynamic Data Store. Part 1 deals with the direct mocking of the Dynamic Data Store objects while <a href="/link/1970091e3424453ca0593f0a35f15fa8.aspx">Part 2</a> deals with abstraction of the Dynamic Data Store behind multiple interfaces.</p>
<h2>The Repository Under Test</h2>
<p>Lets assume we have a custom data object that we want to store in the Dynamic Data Store as follows:</p>
<pre class="language-csharp"><code>public class MyCustomDataObject : IDynamicData
{
public Identity Id { get; set; }
public string UniqueText { get; set; }
public string SomeOtherText { get; set; }
}</code></pre>
<p>The object<span> </span><code>MyCustomDataObject</code><span> </span>has an Identity property in order to meet the<span> </span><code>IDynamicData</code><span> </span>interface which is the minimum requirement for storage within the Dynamic Data Store. The UniqueText property should be unique to that instance of the<span> </span><code>MyCustomDataObject</code>, the<span> </span><code>SomeOtherText</code><span> </span>is just additional information to be stored with that record.</p>
<p>A repository that handles the saving of<span> </span><code>MyCustomDataObject</code><span> </span>records may look something like this:</p>
<pre class="language-csharp"><code>public class MyCustomDataObjectRepository
{
private readonly DynamicDataStore _dataStore;
public MyCustomDataObjectRepository(DynamicDataStoreFactory dataStoreFactory)
{
_dataStore = dataStoreFactory.CreateStore(typeof(MyCustomDataObject));
}
public void Save(Guid id, string uniqueText, string someOtherText)
{
var matchingRecord = _dataStore.Find<MyCustomDataObject>(nameof(MyCustomDataObject.UniqueText), uniqueText).FirstOrDefault();
if (matchingRecord != null && !matchingRecord.Id.ExternalId.Equals(id))
{
throw new EntityExistsException($"An entry already exists for the unique value of '{uniqueText}'.");
}
var recordToSave = Guid.Empty.Equals(id) ? CreateNewRecord() : _dataStore.Load<MyCustomDataObject>(Identity.NewIdentity(id));
recordToSave.UniqueText = uniqueText;
recordToSave.SomeOtherText = someOtherText;
_dataStore.Save(recordToSave);
}
private static MyCustomDataObject CreateNewRecord()
{
return new MyCustomDataObject { Id = Identity.NewIdentity() };
}
}</code></pre>
<h2>Unit Testing</h2>
<p>In order to unit test the repository behaviour, we need to mock the Dynamic Data Store. Optimizely does not provide any interfaces to assist with the writing of unit tests and we have to mock implementations instead. </p>
<p>The mocking of implementations can come with it's own complications. With a mock behaviour of 'strict', the mocked object will behave like the true implementation and will throw exceptions as expected. With a mock behaviour of 'loose', no exceptions will be thrown and default values will be returned as necessary. The default mock behavior of any mocked object is actually the strict behaviour.</p>
<p>The strict mock behavior makes unit testing of the Dynamic Data Store impossible with exceptions being thrown during the set up of the test. So in the following setup method, I have mocked the<span> </span><code>StoreDefinition</code>, the<span> </span><code>DynamicDataStore</code><span> </span>and the<span> </span><code>DynamicDataStoreFactory</code><span> </span>with a loose mock behavior. This is done by supplying the behavior in the mock constructor. The additional parameters applied to the mock constructors are default types which fulfil the constructor of the implementation being mocked.</p>
<pre class="language-csharp"><code>[TestFixture]
public class MyCustomDataObjectRepositoryTests
{
private Mock<DynamicDataStoreFactory> _mockDynamicDataStoreFactory;
private Mock<DynamicDataStore> _mockDynamicDataStore;
private Mock<StoreDefinition> _mockStoreDefinition;
private MyCustomDataObjectRepository _repository;
[SetUp]
public void SetUp()
{
_mockStoreDefinition = new Mock<StoreDefinition>(
MockBehavior.Loose,
string.Empty,
new List<PropertyMap>(0),
null);
_mockDynamicDataStore = new Mock<DynamicDataStore>(
MockBehavior.Loose,
_mockStoreDefinition.Object);
_mockDynamicDataStoreFactory = new Mock<DynamicDataStoreFactory>();
_mockDynamicDataStoreFactory.Setup(x => x.CreateStore(typeof(MyCustomDataObject)))
.Returns(_mockDynamicDataStore.Object);
_repository = new MyCustomDataObjectRepository(_mockDynamicDataStoreFactory.Object);
}
}</code></pre>
<p><span>At this point we are now free to write unit tests as easily as we would do when mocking interfaces. In the following test example, an existing record is created and is set to be the result of the mocked </span><code>Find</code><span> method against the </span><code>DynamicDataStore</code><span>. When we try to save a record with a matching uniqueText, the desired outcome is that an </span><code>EntityExistsException</code><span> is thrown and our assertion is constructed to prove that.</span></p>
<pre class="language-csharp"><code>[Test]
public void GivenUniqueTextExistsAgainstAnotherEntity_ThenAnEntityExistsExceptionShouldBeThrown()
{
// Arrange
var uniqueText = "i-am-unique";
var someOtherText = "some-other-text";
var existingRecord = new MyCustomDataObject
{
Id = Guid.NewGuid(),
UniqueText = uniqueText,
SomeOtherText = "original-other-text"
};
_mockDynamicDataStore.Setup(x => x.Find<MyCustomDataObject>(It.IsAny<string>(), It.IsAny<object>()))
.Returns(new List<MyCustomDataObject> { existingRecord });
// Assert
Assert.Throws<EntityExistsException>(() => _repository.Save(Guid.Empty, uniqueText, someOtherText));
}</code></pre>
<h2>Summary</h2>
<p>In order to unit test against the Dynamic Data Store, you must do the following in order to write unit tests as normal:</p>
<ul>
<li>Mock the<span> </span><code>StoreDefinition</code><span> </span>with<span> </span><code>MockBehavior.Loose</code>.</li>
<li>Mock the<span> </span><code>DynamicDataStore</code><span> </span>with<span> </span><code>MockBehavior.Loose</code><span> </span>and pass in the mock of the<span> </span><code>StoreDefinition</code>.</li>
<li>Mock the<span> </span><code>DynamicDataStoreFactory</code><span> </span>with either mock behavior and set up the<span> </span><code>CreateStore</code><span> </span>method to return the mocked<span> </span><code>DynamicDataStore</code>.</li>
</ul>
<p>To be continued in <a href="/link/1970091e3424453ca0593f0a35f15fa8.aspx">Part 2</a>...</p>2022-05-26T11:01:24.0000000ZBlog postA Robots.Txt Handler for Optimizely CMS 12<h2>Stott.Optimizely.RobotsHandler v1.0.1 Released</h2>
<p>Stott.Optimizely.RobotsHandler is a new robots.txt handler for Optimizely CMS 12 that fully supports multi-site builds with potentially different robots.txt content to be delivered by site. This package is inspired by work previously delivered with <a href="https://github.com/made-to-engage/MadeToEngage.RobotsTxtHandler"><span>POSSIBLE.RobotsTxtHandler</span></a> which was built for CMS 11. Stott.Optimizely.RobotsHandler has been built from the ground up initially as a learning exercise building on lessons learned in my previous post: <a href="/link/aa901c2390b44fce99cfd6b8838262d5.aspx">Extending The Admin Interface in Optimizely CMS 12</a>.</p>
<h2>The Interface</h2>
<p>The interface is built using a standard .NET 5.0 MVC Controller with a Razor view with a small supporting JS file that is compiled as a Razor Class Library. The benefit of building this as a Razor Class Library is that Nuget only needs to provide the DLL keeping your solution otherwise clean of any artefacts from the package. </p>
<p>The UI is a single page using Bootstrap 5.0 and JQuery that renders a complete list of all sites configured within the CMS instance.</p>
<p><img src="/link/21722c8257fd45bba76d45ce8bb116c7.aspx?1639608020667" width="1101" height="298" /></p>
<p>The content of the robots.txt for any site is shown in a modal dialog and saved via an API call that stores the robots.txt content into the Dynamic Data Store. Custom tables have not been used as the expection is that there will be a 1-to-1 relationship between sites and their robots.txt content.</p>
<p><img src="/link/f74a5cdd73924c8db7ce706a355fe946.aspx" /></p>
<h2>Installation & Configuration</h2>
<p>Installation is straight forward, the <strong>Stott.Optimizely.RobotsHandler</strong> package can be installed either from the Optimizely nuget feed or from the nuget.org feed. You will then need to add the following lines to the Startup class in your .NET 5.0 solution:</p>
<pre class="language-csharp"><code>public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
services.AddRobotsHandler();
}</code></pre>
<p>The call to services.AddRazorPages() is a standard .NET 5.0 call to ensure razor pages are included in your solution.</p>
<p>The call to services.AddRobotsHandler() sets up the dependency injection requirements for the RobotsHandler solution and is required to ensure the solution works as intended. This works by following the Services Extensions pattern defined by microsoft.</p>
<h2>Resolving robots.txt content</h2>
<p>A standard controller is configured to respond to requests to <a href="http://www.example.com/robots.txt">www.example.com/robots.txt</a>. When recieving the request, the controller interogates the domain of the request and uses this to resolve the relevant site and the returns the robots.txt content for that site. If not content has been previously defined for the site, the the default content will be returned as follows:</p>
<pre class="language-markup"><code>User-agent: *
Disallow: /episerver/
Disallow: /utils/</code></pre>
<h2>Contributing and Licencing</h2>
<p>Stott.Optimizely.RobotsHandler has been built and uses the MIT licence. If you find any defects with the package, then please log them as issues on the the repositories <a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler/issues">issues</a> page. If you would like to contribute to changes for the solution, then feel free to clone the repository and submit a pull request against the develop branch.</p>2021-12-15T22:38:34.0000000ZBlog postAdding Secure Headers in Optimizely CMS 12<p>I have previously blogged about this in a pure .NET 5.0 context on my own blog here: <a href="https://stotty.azurewebsites.net/article/secure_headers_in__net_5_0">Secure Headers in .NET 5.0</a>. In this version of this post I have adapted the solution to work with an Optimizely CMS Build.</p>
<p>I have been building .NET 5.0 websites for personal projects as well as reviewing the move from .NET 4.8 to .NET 5.0 by Optimizely and seeing the evolution of the CMS solution. In any website build it is best practice to remove any headers that your website may produce which expose the underlying technology stack and version. This is known as information leakage and provides malicious actors with information that allows them to understand the security flaws in the hosting technologies utilized by your website. It is also best practice to provide headers which instruct the user's browser as to how your website can use third parties and be used by third parties in order to offer the best protection for the user.</p>
<p>.NET 5.0 and .NET Core 3.1 follow a common pattern in how you build websites. Web.config is meant to be a thing of the past with configuration of the site moving to appsettings.json and code. A good place to add security headers to your requests is to create a security header middleware. However the routing of the CMS content does not pass through this middleware so I've fallen back to Action Attributes:</p>
<pre class="language-csharp"><code>namespace MyProject.Features.Security
{
using Microsoft.AspNetCore.Mvc.Filters;
public class SecurityHeaderActionAttribute : ActionFilterAttribute
{
public override void OnResultExecuting(ResultExecutingContext context)
{
base.OnResultExecuting(context);
context.HttpContext.Response.Headers.Add("X-Frame-Options", "SAMEORIGIN");
context.HttpContext.Response.Headers.Add("X-Xss-Protection", "1; mode=block");
context.HttpContext.Response.Headers.Add("X-Content-Type-Options", "nosniff");
context.HttpContext.Response.Headers.Add("Referrer-Policy", "no-referrer");
context.HttpContext.Response.Headers.Add("Content-Security-Policy", "default-src 'self'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: https:; frame-src 'self' https://www.youtube-nocookie.com/;");
}
}
}</code></pre>
<p><span>I did find that I couldn't remove the server and x-powered-by headers using this method. As it turns out, these are added by the hosting technology, in this case IIS. The only way to remove these headers was to add a minimal web.config file to the web solution that contained just enough configuration to remove these headers.</span></p>
<pre class="language-markup"><code><?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<httpProtocol>
<customHeaders>
<remove name="X-Powered-By" />
</customHeaders>
</httpProtocol>
<security>
<requestFiltering removeServerHeader="true" />
</security>
</system.webServer>
</configuration></code></pre>
<p><span>I spent a good while looking for this solution, almost every solution I could find was based on hosting within Kestrel rather than IIS. If you are hosting with Kestrel, then you can remove the server header by updating your CreateHostBuilder method in program.cs to set the options for Kestrel to exclude the server header.</span></p>
<pre class="language-csharp"><code>public static IHostBuilder CreateHostBuilder(string[] args, bool isDevelopment)
{
return Host.CreateDefaultBuilder(args)
.ConfigureCmsDefaults()
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
webBuilder.UseKestrel(options => { options.AddServerHeader = false; });
});
}</code></pre>2021-11-19T09:06:03.0000000ZBlog postOptimizely Search Wildcard Queries and Best Bets<p>In a recent client build, I have been tasked with updating their search to use wild card searches. I had read a number of posts pointing to the same solution as detailed by <span>Joel Abrahamsson's 2012 blog post, </span><a href="http://joelabrahamsson.com/wildcard-queries-with-episerver-find/">Wildcard Queries with Episerver Find</a> and Drew Null's post <a href="/link/1a47337598024ccea1e43e86b1f5586c.aspx">Episerver Find Wildcard Queries and Best Bets</a>. These solutions included building an extension method that built a bool query wrapping a wild card query. This included complications in how to get best bets to work with wildcards.</p>
<p>While the solution did work, after reviewing the performance of the query and the structure of the query being sent to Optimizely Search and Navigation, I discovered that the solution was actually much simpler and did not need any new scaffolding of custom query building. The For method has overloads which exposes the QueryStringQuery object that allows you to customise the query behaviour.</p>
<pre class="language-csharp"><code>private ITypeSearch<T> GetQuerySearch<T>(
string query,
bool isWildCardSearch) where T : MyVariant
{
var specificQuery = isWildCardSearch ? $"*{query}*" : query;
return _findClient.Search<T>()
.For(query, options =>
{
options.Query = specificQuery;
options.AllowLeadingWildcard = isWildCardSearch;
options.AnalyzeWildcard = isWildCardSearch;
options.RawQuery = query;
})
.InField(f => f.FieldOne, _settings.FieldOneBoost)
.InField(f => f.FieldTwo, _settings.FieldTwoBoost)
.InField(f => f.FieldThree, _settings.FieldThreeBoost)
.InField(f => f.FieldFour)
.InField(f => f.FieldFive)
.InField(f => f.FieldSix)
.InField(f => f.FieldSeven)
.InField(f => f.FieldEight)
.UsingSynonyms()
.UsingAutoBoost(TimeSpan.FromDays(_settings.AutoBoostTimeSpanDays))
.ApplyBestBets()
.FilterForVisitor();
}</code></pre>
<p>By passing in the wild card version of the query string into options.Query and setting options.AllowLeadingWildcard and options.AnalyzeWildcard to true was all I needed for wildcard search to be functional. I also passed in the unaltered query into options.RawQuery but this was not required in order to make Best Bets work.</p>
<p>The main downside to this approach is that synonym functionality no longer worked. The query with the wildcards would never match a synonym but it would work with best bets. I resolved this by using a Multi Search query and passed in the unaltered query and then the wild card query. In Multi Search, each result set is returned in the same order in which it has been defined and they are packaged in a single API call. It was then a simple case of selecting the first result set with at least one match.</p>
<pre class="language-csharp"><code>var searchResult _findClient.MultiSearch<DentalVariantProjectionModel>()
.Search<MyVariant, MyProjectionModel>(x => GetQuerySearch(query, false))
.Search<MyVariant, MyProjectionModel>(x => GetQuerySearch(query, true))
.GetResult();
var resultToUse = searchResult.FirstOrDefault(x => x.TotalMatching > 0) ?? searchResult.First();</code></pre>
<p>Performance wise, the difference in sending two queries in a multi search request was negligable compared to a sending a single query.</p>2021-11-19T08:46:10.0000000ZBlog postSetting Up Search & Navigation in .NET 5.0<p>UPDATE: The documentation has now been updated and can be found here: <a href="/link/5d022ec58a134858bd1e8341bad44f10.aspx">https://world.optimizely.com/documentation/developer-guides/search-navigation/getting-started/creating-your-project/</a></p>
<p>Optimizely CMS for .NET 5.0 is a very exciting thing. Recently the .NET Core Preview documentation was archived and some of that documentation was merged into the live developer guides. Optimizely have a huge amount of developer documentation and it's going to take a while for this content to be updated for .NET 5.0. Sadly the current documentation for Optimizely Search and Navigation is still focused on the .NET 4.x world</p>
<p>1. Add the EPiServer.Find.CMS nuget package to your .NET 5.0 solution.</p>
<p>2. Generate a new Search and Navigation index at <a href="https://find.episerver.com/">https://find.episerver.com/</a></p>
<p>3. Configure the index details in app.config...</p>
<p>When you create the index, you will be shown this snippet to add to your web.config:</p>
<pre class="language-markup"><code><configuration>
<configSections>
<section
name="episerver.find" type="EPiServer.Find.Configuration, EPiServer.Find" requirePermission="false"/>
</configSections>
<episerver.find
serviceUrl="https://demo01.find.episerver.net/RXQGZ5QpXU9cuRSN2181hqA77ZFrUq2e/"
defaultIndex="yourname_indexname"/>
</configuration> </code></pre>
<p>You will instead add this to appsettings.json like so:</p>
<pre class="language-javascript"><code>{
"EPiServer": {
"Find": {
"ServiceUrl": "https://demo01.find.episerver.net/RXQGZ5QpXU9cuRSN2181hqA77ZFrUq2e/",
"DefaultIndex": "yourname_indexname"
}
}
}</code></pre>
<p>4. Configure your startup.cs to include the find configuration:</p>
<pre class="language-csharp"><code>public void ConfigureServices(IServiceCollection services)
{
services.AddCmsAspNetIdentity<ApplicationUser>();
services.AddMvc();
services.AddCms();
services.AddFind();
}</code></pre>
<p>You should now have everything you need to write your search queries as normal:</p>
<pre class="language-csharp"><code>var searchResult = _findClient.Search<SitePageData>()
.For(request.SearchText)
.UsingSynonyms()
.ApplyBestBets()
.Skip(skip)
.Take(pageSize)
.GetContentResult();</code></pre>2021-10-01T15:13:11.0000000ZBlog post