Blog

My blog is now running using Optimizely CMS!

Tue, 22 Jul 2025 18:35:14 Z

It's official! You are currently reading this post on my shiny new Optimizely CMS website.

In the past weeks, I have been quite busy crunching every items to transfer my originally developed website from Orchard CMS to Optimizely CMS. It was quite the experience and also, a lot of new opportunities are now on the horizon.

Now what?

During this experience, I was able to take my time to tackle certain architectural challenges that we're often facing when creating a new Optimizely CMS website. So in the upcoming days/weeks, I will be able to talk about these, but here's a sneak peek on the topics I'd like to talk about:

What's the right project structure, or at least, best suggested structure, when building the project with a multi site setup in mind.
Creation & announcement of a new NuGet feed that will ease the multi site setup for developers.
For those interested, I have also developed a custom RSS feed integration for Optimizely CMS that I plan on publishing. You can see it in action on this blog: https://www.davidhome.net/rss/.
GitLab pipelines. I have fully automated builds & deployments of the website using this technology. I'm normally accustomed to use Azure DevOps, but for this personal project, it was a great opportunity to learn something different using my own GitLab instance.
Maybe an open topic on the mediator pattern? I've used the library MediatR for my blog.

Stay tuned & happy coding!

Optimizely Content Graph - Sync Computed Getter Properties like with Search & Navigation

Fri, 18 Oct 2024 04:00:00 Z

Recently, I have been re-writing my blog using Optimizely CMS. During this process, I wanted to try new released technologies offered by Optimizely. Today, I'm going to talk a bit about my experience with Content Graph.

Of course, I thought about using Search & Navigation, but I think it was beneficial that I learned something that will eventually, to my opinion, replace it entirely.

With Search & Navigation, the majority of Optimizely developers are well aware that you can synchronize not only properties meant for the content type itself, but also the ones that are computed, meaning only a getter has been used. The following example demonstrate that (see FirstPublishedDate):

If you use Search & Navigation, this property is getting indexed and can be used on any query. It also means you can order your result with that computed field and do a bunch of cool tricks, such as including different ways to represent a certain element from the content type in a fashion consumable by the Search & Navigation C# client. Complex types aren’t really its force, so we often add getter only properties to return a more simplified, but useful, data format.

So, under Content Graph, I was under the impression that I could do the same thing, but alas, no, you can't for the moment. But Optimizely did confirmed to myself via a support request they have plans to add something that would allow developers to customize and add the ability to extend the data synchronization of content types. In the meantime, I have concocted a very... but very hackish workaround that allow you to synchronize getter properties. Before moving forward with the solution, a little explanation is in order to understand a bit more what you can/can't do:

The schedule job "Optimizely Graph content synchronization job" is the main responsible to do the following:

Scan for all existing content types and synchronize them to Content Graph. It's using their definitions to know the structure your content should have under its own engine.
- By the way, you can also use their endpoints to synchronize content types completely unrelated to the CMS: https://docs.developers.optimizely.com/platform-optimizely/v1.4.0-optimizely-graph/docs/synchronize-content-types. Very useful in scenarios where you need content from different external sources, but all available in the same place. Super powerful and allow the leverage of the engine to do extremely useful searches.
Then scans for all existing content in the CMS and synchronize all of its data under Content Graph. This is the step that interests us

While digging for a solution to extend my content type and allow the synchronization of getter only properties, I have realized the following must be respected:

Your property cannot be a getter only, you still have to put a setter. It's because otherwise the property is not considered a real CMS property and thus is getting ignored during the indexation. A real property will appear under "CMS -> Settings -> Content Type" menu.
So I simply added a setter using this.SetPropertyValue() to get over this limitation.

Once you get your property synchronized to Optimizely database comes the part where the indexation job of Content Graph is still ignoring it. While reading the decompiled code of Optimizely, I learned that the current business logic is only relying on the data stored within the CMS database, which means that in the end all defined elements in the code is entirely ignored, since the job is only directly pulling the data inside the internal content type tables.

So, well, this is where I come with the idea to build a dynamic type. I had to create a dynamic assembly which was allowed to interact with "internal" types of the "Optimizely.ContentGraph.Cms.NetCore" assembly. In the end, I had to create IL code so that my desired behavior could be added to the synchronization job. To keep that brief, if you want the solution, here's my GitHub repository with a small example. The dynamic type is inheriting from "ContentGraphContentConverter" and is replacing the original type under the IoC container. Under the "Convert" method, instead of directly returning the model, I'm calling the extension AddReadonlyProperties, which then allow me to customize the return value.

Happy coding!

GetNextSegment with empty Remaining causing fuzzes

Sun, 07 Jul 2024 04:00:00 Z

Optimizely CMS offers you to create partial routers. This concept allows you display content differently depending on the routed content in the URL. Of course, a more in-dept explanation can be found at the following URL: https://docs.developers.optimizely.com/content-management-system/docs/example-of-news-partial-routing. All in all, this concept also existed in the previous version of the CMS, but it differed a bit than it is currently.

See, when we migrated a customer from .NET Framework to .NET Core, AKA CMS 11 to 12, we encountered a memory leak that we couldn't really put our hand on at first sight. The solution heavily used those partial routers. Our issue also often occurred on DXP and not on our development machine, which was even weirder. Until we remembered that the application is automatically warmed up when running under DXP. This led us to find the source of the problem, the partial routers, but more specifically on the part when we get the next value of the URL segment.

As explained in the CMS 12 documentation, you can use from an UrlResolverContext the method GetNextSegment to get that information. It returns a Segment, which contains what's "next" and the "remaining path". Our code, since it was originally developed for CMS 11, used at the time the old API, a method "GetNextValue", probably from a similar service which I don't reminder the name and was looping around it until Optimizely code returned an empty segment. It all makes sense right? Here's the decompiled code from CMS 11:

As you can see, CMS 11 was simply returning an empty "next" and "remaining" SegmentPair if the remaining path was empty. Our code was relying on this information, well, specifically the property "Remaining" of the segment pair. I'm sure at this point you're probably realizing why we were having memory leaks. Indeed, under CMS 12, this piece of code changed and caused infinite loops in ours, concatenating string to infinity and beyond. The change itself is very inexplicable I would say, even myself don't understand why Optimizely decided to make it that way, it feels more like an unwanted error than anything else. Here's a snapshot of the decompiled code, this will speak for itself:

It, hum, well, reassign the remaining path if it's empty, but also have the same check just after, a condition, which at this point, will never be met, that simply does what we would expect.

We informed Optimizely of this quirk, though unfortunately didn't ended up being fixed. Our code now has different checks and also a failsafe to avoid looping indefinitely. I hope that with this post can save you time diagnosing similar problems on your end.

How NDepend can quickly help you find code quality issues and resolve them

Fri, 26 Jan 2024 05:00:00 Z

NDepend has been around for quite a long time. If you are unaware of what it does, you should be checking it. It's an analysis tools which helps you find inconsistencies and discrepancies in your C# source code. I've been trying it out recently and helped me found certain issue which I wasn't aware of.

To be clear, there is indeed other available solution and it's up to your team to decide which fits best with you. In this case, NDepend runs independently from any IDE, but you can install an integration plugin inside Visual Studio. This can give the leverage/advantage to avoid loading any IDE to obtain a report. Unfortunately, there is no plugin/extension support under JetBrains Rider, my personal IDE of choice, like there is under Visual Studio. I hope their team can implement one, that would be greatly valuable.

Dashboard

Once a solution analysis is completed, you will be greeted with the dashboard tab:

Here lies a general overview of the quality of the whole solution that you have analyzed. This gives a great quick shot of the elements you could get your hand onto if your goal is to refactor the code to make it more maintainable. You can personalize the rules and change them to your likings. For example, in my previous screenshot, there is one critical rule that flags I'm using a type within another type which have both different namespaces. The debt explanation is interesting. Of course, you can always decide to ignore it, but it gives an interesting point of view regarding the fact that some developers are using folders within a project to "organize" classes, which can lead to this kind of rule alert. Of course, everything is to take with a grain of salt, as I agree with someone from the comments of this Stack Overflow thread, these kind of alerts can be opinion based. An interesting thing that NDepend's team could be adding inside their analysis program is rule categorization; Opiniated ones versus the others by example. It could help to quickly address undiscussable items and leave any development team to discuss the other opiniated points and see whether they need to be addressed.

Dependency Graph

I think the most interesting feature of NDepend is the dependency graph. It's so incredibly useful to quickly identify areas of your code that aren't supposed to inherit another project within your solution. This can otherwise, to my opinion, often lead to solutions having classes/elements heavily coupled/entangled together. Based on the same project that I have used to create my first screenshot, here is an example of the graph:

As you can realize in the previous screenshot, there is a design pattern here that I often follow in projects:

The website is the main "referrer" of projects, meaning that nothing should be referencing the website.
- The exception are the unit tests. You can also realize the only additional reference of the test projects are the "Models" projects. Nothing else.
The "Bootstrappers" projects serve only the purpose to add inside the IoC container the necessary services that are consumable by all "Contracts" projects.
Each consumable "Contracts" projects comes in pair with a minimum of an additional "concrete" implementation project. These projects, as previously mentioned, only contain the implementation your contracts, which will then be consumed by the website.
Almost everything consumes the "Models". This is again, by design. Models are the basically "the end of the road", it should generally refer nothing else.

I will be doing another blog post about the design pattern I personally follow in projects.

NDepend quickly identified a discrepancy in my project: There is a direct reference from the website to the database library and this is not normal. Double clicking on the arrow gives me the following:

With that, I can easily remove the three direct references from my code and refactor to use my repository pattern implementation. It's one of many example that can clearly help you and your team to identify elements such as this one.

Metrics

The "Metrics" tab is again another great example of the tool usefulness; From there you can view "heated" areas of your code which has strong cyclomatic complexity. Here in my example, the following method is considered a bit more complex:

Double clicking it opens the file in your preferred IDE and points your cursor directly to the method. If you're interesting to have different insights, you can also change the metric data type to something else:

Closure

There is also a CI/CD integration that you can install. Obviously, the goal is to obtain those analysis directly from your build pipelines so that you can act preventively on any code quality depreciation. If you're interested, you can also view certain sample reports at the following URL: https://www.ndepend.com/sample-reports/. For Optimizely solutions, CD/CI can come super handy because such projects can quickly become a burden maintainability wise.

Optimizely Content Cloud CMS Apps (Add-ons) - Tips & Tricks

Mon, 22 Jan 2024 05:00:00 Z

Developing an Optimizely CMS Add-on can be a bit tricky. There is a lot of advantages of doing it, but building it right can be a bit tedious. You have probably already seen the following documentation page about the subject itself, but it feels like a lot of details are missing to make it right. You will also quickly realize there is a lot of historical elements which makes the process a bit more complicated/confusing. In this blog, we will unravel everything so that you can successfully build yours!

I will be assuming that your project is currently using .NET 6.0, but the process is the same if the target framework changes. You can also add conditional dependencies based on the target framework, which then the command dotnet pack will automatically handle when bundling your library. I will also assume that you are already mastering how packing your library to .nupkg file(s) works.

1. Adjustements inside the project file

First of all, create a new solution with a library project using your preferred IDE, then edit the .csproj file. Your file should look like the following in the end:

<Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
  
  <ItemGroup>
		<!--    These are package example. Install those you need. -->
    <PackageReference Include="EPiServer.CMS.AspNetCore.Mvc" />
    <PackageReference Include="EPiServer.CMS.Core" />
    <PackageReference Include="EPiServer.CMS.UI.Core" />
  </ItemGroup>

  <ItemGroup>
    <Content Remove="module.config" />
    <None Include="module.config">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </None>
    <Content Remove="packages.lock.json" />
    <None Include="packages.lock.json">
      <CopyToOutputDirectory>Never</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

As you can also realize, I'm using CPM. This will greatly simplify the dependency management along the way.

Couple of things to highlight here:

Super important to change the SDK attribute on the "Project" node to "Microsoft.NET.Sdk.Razor".
Inside the first PropertyGroup node, add AddRazorSupportForMvc and set it "true".
Make sure to add a FrameworkReference node which will be including the Microsoft.AspNetCore.App reference. Necessary for having the ASP.NET Core web references, which normally the SDK Microsoft.NET.Sdk.Web includes by default.
The last, but not least, make sure to remove & ignore any files you want to exclude from your .nupkg file. In our example, and you will probably need it too, we want to prevent both "module.config" and "packages.lock.json" file to be inside the file package.

2. Custom MSBuild instructions

There is a couple of adjustments to make so that MSBuild is helping up ease the bundling:

Assuming your projects are hierarchically structured in the following directory pattern: [root]/src/projectname/projectname.csproj, create a Directory.Build.props file in the "src" folder with the following content:

<Project>
  <PropertyGroup>
    <NoWarn>NU1507</NoWarn>
    <RestorePackagesWithLockFile>True</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>

Assuming the same structure, create under the "src" folder the file Directory.Packages.props with the following content:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>
  <ItemGroup>
		<!--    These are package example. Install those you need. -->
    <PackageVersion Include="EPiServer.CMS.AspNetCore.Mvc" Version="[12.4.0, 13.0.0)" />
    <PackageVersion Include="EPiServer.CMS.Core" Version="[12.4.0, 13.0.0)" />
    <PackageVersion Include="EPiServer.CMS.UI.Core" Version="[12.4.0, 13.0.0)" />
  </ItemGroup>
</Project>

Inside the project folder, where the .csproj file resides, create a new file entitled Directory.Build.props with the following content:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ClientResources Include="$(ProjectDir)ClientResources\**\*"/>
    </ItemGroup>
    <PropertyGroup>
        <TmpOutDir>$([System.IO.Path]::Combine($(ProjectDir), 'tmp'))</TmpOutDir>
        <NoWarn>NU1507</NoWarn>
        <RestorePackagesWithLockFile>True</RestorePackagesWithLockFile>
    </PropertyGroup>
    <ItemGroup>
        <Content Include="$(MSBuildProjectName).zip">
            <Pack>true</Pack>
            <PackagePath>contentFiles\any\any\modules\_protected\$(MSBuildProjectName)</PackagePath>
            <BuildAction>None</BuildAction>
            <PackageCopyToOutput>true</PackageCopyToOutput>
        </Content>
        <Content Include="msbuild\CopyZipFiles.targets" >
            <Pack>true</Pack>
            <PackagePath>build\$(MSBuildProjectName).targets</PackagePath>
        </Content>
    </ItemGroup>
</Project>

Still in the project folder, create the file Directory.Build.targets and add the following content:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="CreateCmsAddOnZip" BeforeTargets="Build">
    <Copy SourceFiles="$(ProjectDir)module.config" DestinationFolder="$(TmpOutDir)\content"/>
    <Copy SourceFiles="@(ClientResources)" DestinationFiles="@(ClientResources -> '$(TmpOutDir)\content\$(PackageVersion)\ClientResources\%(RecursiveDir)%(Filename)%(Extension)')"/>

    <!-- Update the module config with the version information -->
    <XmlPoke XmlInputPath="$(TmpOutDir)\content\module.config" Query="/module/@clientResourceRelativePath" Value="$(PackageVersion)"/>
  </Target>
  <Target Name="ZipClientResources" BeforeTargets="Build" AfterTargets="CreateCmsAddOnZip" DependsOnTargets="CreateCmsAddOnZip">
    <ZipDirectory SourceDirectory="$(TmpOutDir)\content" DestinationFile="$(ProjectDir)$(MSBuildProjectName).zip" Overwrite="true"/>
  </Target>
  <Target Name="CleanupTmpOutDir" BeforeTargets="Build" AfterTargets="ZipClientResources" DependsOnTargets="ZipClientResources">
    <RemoveDir Directories="$(TmpOutDir)"/>
  </Target>
</Project>

You will also have to add the file CopyZipFiles.targets to a new "msbuild" folder under the root of the project directory:

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
  <ItemGroup>
    <CmsAddOnZips Include="$(MSBuildThisFileDirectory)..\contentFiles\any\any\modules\_protected\**\*.zip"/>
  </ItemGroup>

  <Target Name="CopyCmsAddOnZip" BeforeTargets="Build">
    <Copy SourceFiles="@(CmsAddOnZips)" DestinationFolder="$(MSBuildProjectDirectory)\modules\_protected\%(RecursiveDir)"/>
  </Target>
</Project>

To summarize, these customizations will do the following to your project each time you will be compiling:

Adds CPM, as previously mentioned.
Adds NuGet lock files, super useful for your DevOps pipeline.
Automatically compile views.
Automatically generates module the zip file with all necessary elements in it that will be packaged within your .nupkg file.
- This file contains the recommended structure & content that you can find in the Optimizely CMS addon documentation.

3. Minimum required configuration

See the "module.config" file like the definition of your addon. Without it, Optimizely will use the default values from the class ShellModuleManifest, which unfortunately omit a very important detail; The assembly’s name of your addon. Without it, Optimizely won't be able to load yours at boot. Create it where the .csproj file resides with the following content:

<?xml version="1.0" encoding="utf-8"?>
<module loadFromBin="false" name="Your.Assembly.Name" viewEngine="Razor" clientResourceRelativePath="$version$" tags="EPiServerModulePackage">
  <assemblies>
		<!-- Change the assembly name with yours -->
    <add assembly="Your.Assembly.Name" />
  </assemblies>
  <clientModule>
    <moduleDependencies>
			<!-- Adjust accordingly -->
      <add dependency="CMS" type="RunAfter" />
    </moduleDependencies>
  </clientModule>
</module>

Add an extension method on the interface "IServiceCollection" and add at least the following piece of code:

public static IServiceCollection AddMyAddon(this IServiceCollection services)
    {
        // Add services here.
        return services
                // Super required, otherwise your addon won't load when the site loads.
            .Configure<ProtectedModuleOptions>(
            pm =>
            {
                if (!pm.Items.Any(i => i.Name.Equals(ModuleName, StringComparison.OrdinalIgnoreCase)))
                {
                    pm.Items.Add(new ModuleDetails { Name = ModuleName });
                }
            });
    }

4. Controllers & Views

Probably the most undocumented/unclear part for Optimizely CMS addons. The instructions around views doesn't exactly explain how they can be used or how the routing works within your library. If you're looking at existing addons, e.g., Geta.NotFoundHandler, the majority of developers are handling it slightly differently. This page explains how to structure your files in a manner that the module will automatically include them for you, but I was unable to make it work. Maybe because it should be exclusively a razor page and not a simple razor view dependent on a Controller. Fortunately, you can make it work with a controller, but with a little additional tweaking:

Create a new Route Attribute. We will use it to customize the routes to our controllers. Here's an example:

using EPiServer.Shell;
using Microsoft.AspNetCore.Mvc.Routing;

namespace Playground.Mvc;

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
public class ModuleRoute : Attribute, IRouteTemplateProvider
{
    private readonly string _controllerName;
    private readonly string _actionName;

    public string Template => Paths.ToResource(typeof(ModuleRoute), $"{_controllerName}/{_actionName}");
    public int? Order { get; set; } = 0;
    public string Name { get; set; }

    public ModuleRoute(string controllerName, string actionName)
    {
        _controllerName = controllerName;
        _actionName = actionName;
    }
}

Decorate your controller actions with your newly created route attribute. e.g.:

    [HttpGet]
    [ModuleRoute("Default", "Index")]
    public IActionResult Index()
    {
        return View();
    }

Create a new menu provider class including all paths to your actions in your addons. e.g.:

using EPiServer.Framework.Localization;
using EPiServer.Shell;
using EPiServer.Shell.Navigation;
using Playground.Controllers;

namespace Playground.Optimizely;

[MenuProvider]
public class AddonMenuProvider : IMenuProvider
{
    private readonly LocalizationService _localizationService;

    public AddonMenuProvider(LocalizationService localizationService)
    {
        _localizationService = localizationService;
    }

    public IEnumerable<MenuItem> GetMenuItems()
    {
        yield return new UrlMenuItem(_localizationService.GetString("/myaddon/gadget/title", "My Addon"), "/global/cms/myaddon",
            Paths.ToResource(GetType(), $"Default/{nameof(DefaultController.Index)}"))
        {
            SortIndex = 0,
            Alignment = 0,
            IsAvailable = _ => true
        };

        yield return new UrlMenuItem(_localizationService.GetString("/myaddon/index/menu", "Home"), "/global/cms/myaddon/index",
            Paths.ToResource(GetType(), $"Default/{nameof(DefaultController.Index)}"))
        {
            SortIndex = 10,
            Alignment = 0,
            IsAvailable = _ => true
        };

        yield return new UrlMenuItem(_localizationService.GetString("/myaddon/secondaction/menu", "Second Action"), "/global/cms/myaddon/secondaction",
            Paths.ToResource(GetType(), $"Default/{nameof(DefaultController.SecondAction)}"))
        {
            SortIndex = 20,
            Alignment = 0,
            IsAvailable = _ => true
        };
    }
}

By doing so, you are generating routes which will point directly on your addon controller. Say by example you have the "DefaultController" class with the "Index" action, well then, the action under your browser should look as the following: ~/EPiServer/MyAddon/Default/Index. This also convenientely allow you to use razor helpers such as Html.BeginForm, since the MVC routing system knows these belongs to your addon with a custom template.

It is very important to respect the actions defined within your IMenuProvider implementation, otherwise the custom routing attribute won't be working just right. As you can see, a certain minimum level of structure has been established in this file, which makes actions from the controller to work correctly. The third parameter of the constructor of UrlMenuItem is exactly where the magic happens. The recommendation is indeed to keep using the helper, Paths.ToResource and add the additional segment manually. This consequently creates the same path as previously described in the last paragraph and will match it with the available controller action. A menu item is essentially an element that will appear under the Backoffice, when navigating under ~/EPiServer.

I hope this will be super helpful to people reading this blog! You can view a starter code example over there: https://github.com/ddprince17/Optimizely-CMS-Addon-Playground.

Secure your SMTP configuration - Configuration Builders

Sun, 21 Jan 2024 05:00:00 Z

In .NET Framework, we are all aware of the famous <network> node under the Web.config file. This has been the facto way to configure your SMTP settings since, well, a long time. In .NET, the story is quite different, as the approach is way cleaner as it previously was, there is no enforced structure or way to configure your settings, you decide, by yourself, how you would like these settings to exist within, either your appsetting.json file or any configuration provider you might have added to your solution.

For example, under a Optimizely CMS 12 and higher solution, you would have to add configuration under the "EPiServer.Cms.Smtp.Network" section. But in the end, this structure is something established by Optimizely, nothing prevents you to add them elsewhere (even though I would not recommend to duplicate configuration under multiple different nodes).

In previous version of Optimizely (lower than version 12), since we're using .NET Framework, we must use the Web.config structure to be able to have our SMTP settings properly setup. The thing though is that we had to put the password cleartext right inside this section. There was also no way to use configuration transformation as it usually works with the appSettings and connectionStrings sections. Until we found a way to move those settings inside the appSettings section.

We deploy our solutions to DXP. So naturally speaking, we have no control over the infrastructure where the application is hosted, but we have a way, just before sending the package to Optimizely, to transform the configuration. Under Azure DevOps, there's a task, File Transform v2, which does exactly what we want. We store our secrests inside variable groups and let the configuration transformation task to do its magic (variable substitution). So, this step covers like 90% of our cases, we can safely store secrets, but unfortunately, like I said, this only works for the appSettings section. What about the smtp section then? I'd tell you "Configuration builders". There are already existing config builders in the wild, the one we use the most is the AzureKeyVaultConfigBuilder, but mainly for development purpose, as we still don't want to expose secrets, even for that.

But I can hear ya, like at a 100 miles, with your question: "But Dave, what does this change for the SMTP configuration?" I'm glad you're asking! See, you can add existing config builder, but you can also create a new one. So, since I want the SMTP configuration to be loaded from the appSettings, I'll create a class that will do the following:

public class SmtpConfigurationBuilder : ConfigurationBuilder
    {
        public override ConfigurationSection ProcessConfigurationSection(ConfigurationSection configSection)
        {
            if (!(configSection is SmtpSection smtpSection) || smtpSection.Network == null) 
                return base.ProcessConfigurationSection(configSection);

            smtpSection.Network.Host = ConfigurationManager.AppSettings["smtp-host"];
            smtpSection.Network.UserName = ConfigurationManager.AppSettings["smtp-userName"];
            smtpSection.Network.Password = ConfigurationManager.AppSettings["smtp-password"];
            smtpSection.Network.Port = ConfigurationManager.AppSettings["smtp-port"].ToInt(defaultValue: 587);
            smtpSection.Network.EnableSsl = ConfigurationManager.AppSettings["smtp-enableSsl"].ToBoolean();

            return base.ProcessConfigurationSection(configSection);
        }
    }

This will instruct whatever that uses my config builder to execute only when the current section is a SMTP section and that the Network node isn't null. To have that work under your Web.config, you'll have to add three additional items:

Look for the "configSections" node and add the following at the end:

  <section name="configBuilders" type="System.Configuration.ConfigurationBuildersSection, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" restartOnExternalChanges="false" requirePermission="false" />

Just after the "configSections" node, add the following:

  <configBuilders>
  	<builders>
  		<add name="SmtpConfigurationBuilder" type="Full.Namespace.Of.My.Class.SmtpConfigurationBuilder, Assembly.Name" />
  	</builders>
  </configBuilders>

If you have multiple config builder, take a good attention of the ordering, as I think it has importance when they are loaded.

And finally, replace your SMTP node with something like so:

  <system.net>
  	<mailSettings>
  		<smtp from="donotreply@example.com" configBuilders="SmtpConfigurationBuilder" />
  	</mailSettings>
  </system.net>

So, with that, you have a way to load all you SMTP configuration directly from your appSettings. Isn't that great? Assuming you're using Azure DevOps to build and deploy your solutions, you can now easily leverage the variable substitution to change your SMTP settings just before sending the package to Optimizely for a deployment.

Another thing to point out, as you can see, you can add multiple config builders. We do that on our side, only for our development environments, to protect any sensitive information, by using the AzureKeyVaultConfigBuilder. This setup can work in pair, meaning that, say, you have both AzureKeyVaultConfigBuilder and the SmtpConfigurationBuilder, you can use the first config builder to load the secrets from your key vault, then ask your SMTP builder to load these for your SMTP configuration. It can be extremely useful for a lot of different applications.

IDX21323 - RequireNonce is true, Nonce was null

Sun, 01 Oct 2023 04:00:00 Z

We have multiple clients configured with Azure Active Directory (Microsoft Entra) for requiring authentication when accessing their website. The majority of them is only for protecting the backoffice (CMS admin), but we have certain of them that uses it for protecting the whole site.

There is existing Optimizely documentation that allow you to setup your site to use AAD authentication, but it doesn't talks about the famous issue certain people are having when signing in to the website; "IDX21323 - RequireNonce is true, Nonce was null". I might come with a surprise, but this issue will be occurring systematically under all DXP environments if you do not ask Optimizely to change a setting under Cloudflare for you. The problem is described there: https://support.optimizely.com/hc/en-us/articles/7492181419789-Nonce-Error-Using-OpenIdConnect-for-Authentication-with-DXC.

The solution though is something that doesn't seems to ring a bell for certain people. As of the time of writing, it says "to bypass the origin cache control", but in contrary, the mentioned page rule is enabling Cloudflare to respect the origin cache control header. You see, it is not entirely respecting cache-control directive from the origin server, by default. Organizations with an enterprise plan with Cloudflare are all having the rule disabled by default. Something which is hard to understand as Cloudflare's documentation doesn't really give up insights on that matter except in the previous thread. It means that even if you've decided to put any custom cache-control directives within your application, Cloudflare will ignore some of them or will behave differently.

This default setup can cause a couple of different issues:

Signing in under certain URLs/paths, the Nonce cookie isn't setup during the authentication, thus causing the IDX21323 issue.
Leaving certain assets "publicly" available after someone has loaded it once, even though it should require authentication, because it isn't validating it once the Edge has cached the asset.
Breaking images because the Edge has cached the authentication redirection action, a http 302 status code.
Preventing your application to set request cookies. Cloudflare will sometimes, under specific scenarios, completely discard the cookie before sending the response to the client.

Don't get me wrong, caching is important, but you need to adapt certain rules depending on what your website is. For intranet sites by example, it's important that the caching doesn't break the experience nor expose certain privately accessible assets. There's a couple of tricks you can apply right up front, by example, when using the extension method AddOpenIdConnect, you can control the Cache-Control header only when redirecting to the authentication provider.

All in all, though, take a good attention of how your website is behaving when hosted under Optimizely DXP, especially when you are protecting certain areas, more than the CMS backoffice itself. Normally any Optimizely CMS solution will include right out of the box optimized cache control headers, especially for assets, but keep in mind that Cloudflare will react differently with them since the page rule "Origin Cache-Control" is not enabled by default (for enterprise customers only).

Optimizely Commerce Business Foundation custom entity model - To add on Quan Mai's blog :)

Sat, 01 Jul 2023 04:00:00 Z

Quan Mai is right, there is another official way to load organizations and contacts under Optimizely Commerce using the famous static class BusinessManager. Though, there's more you can do about it. Have you ever wonder if you could personalize the data access on custom properties using your own class instead of using, e.g., Organization.Properties["MyCustomProperty"]? Yes, me too, and in this blog post, I'm going to show you it's possible!

For readability simplicity, I'll concentrate the discussion around the organizations, but keep in mind the same personalization principle applies for all other Business Foundation entities. Our journey will start under a configuration file; baf.data.manager.config. This file lists a couple of Business Foundation entities with their associated RequestHandler. You see here, the default configuration for an Organization is the following type: Mediachase.Commerce.Customers.Handlers.OrganizationRequestHandler, Mediachase.Commerce. If you have Jetbains Rider, you can easily find the class by searching everywhere, usually CTRL + T with the Visual Studio key binding and include non solution items. For those who are using dotPeek by example, you need to decompile the dll Mediachase.Commerce.dll which is under the NuGet package EPiServer.Commerce.Core.

The OrganizationRequestHandler inherits CustomerRequestHandlerBase and this is where we'll be finding what we're looking for. There's a method CreateEntityObject, which has the following one liner:

return new CustomerEntityFactory().Create<EntityObject>((object) new KeyValuePair<string, PrimaryKeyId?>(metaClassName, primaryKeyId));

If you look closely, inside the class CustomerEntityFactory, you can find how Business Foundation is creating its instance of classes that it will be returning to you after pulling the data. This is also why you can use "OfType" when using BusinessManager. The class is quite basic, for any known entity, use the following new instance of class to build my entity:

EntityObject IFactoryMethod<EntityObject>.Create(object obj)
    {
      KeyValuePair<string, PrimaryKeyId?> keyValuePair = obj != null ? (KeyValuePair<string, PrimaryKeyId?>) obj : throw new ArgumentNullException(nameof (obj));
      EntityObject entityObject = (EntityObject) null;
      switch (keyValuePair.Key)
      {
        case "Contact":
          entityObject = (EntityObject) CustomerContact.CreateInstance();
          break;
        case "Address":
          entityObject = (EntityObject) CustomerAddress.CreateInstance();
          break;
        case "Organization":
          entityObject = (EntityObject) Organization.CreateInstance();
          break;
        case "CreditCard":
          entityObject = (EntityObject) CreditCard.CreateInstance();
          break;
      }
      if (entityObject != null && keyValuePair.Value.HasValue)
        entityObject.PrimaryKeyId = new PrimaryKeyId?(keyValuePair.Value.Value);
      return entityObject;
    }

Naturally, this was my entry point to personalize how the organizations could be loaded. There are three things you need to do:

Create your own entity.
Create a new entity factory.
Create a new request handler.

1. Create your own entity

We're personalizing our Organization entity with additional properties, we want them to be accessible without having to call Properties["MyProperty"]. So here, we'll create a new model, say, MyOrganization, that will be inheriting from Mediachase.Commerce.Customers.Organization:

using System;
using System.Collections.Generic;
using Mediachase.BusinessFoundation.Data;
using Mediachase.Commerce.Customers;
using Mediachase.Commerce.Customers.Request;

namespace MyNamespace
{
    public class MyOrganization : Organization
    {
        public string MyInternalOrgNumber
        {
            get => (string) this[nameof(MyInternalOrgNumber)];
            set => this[nameof(MyInternalOrgNumber)] = value;
        }
    }
}

In the previous example, I want developers to be able to access our custom property "MyInternalOrgNumber" from this object. This is basically the same as calling Organization.Properties["MyInternalOrgNumber"]. Don't forget from on now, to use your custom class, you need to cast it to "MyOrganization". You can do that in the application layer responsible to obtain data from BusinessManager. What we did in our project, was to create a service that was the data layer abstraction between our application and Business Foundation. Any calls on the CustomerContext, e.g., CustomerContext.Current.GetOrganizations() can be also casted to "MyOrganization" (as far as I remember™️).

2. Create entity factory

You still have the class CustomerEntityFactory decompiled? Go back there and copy it, because it will almost be the same in your implementation:

using System;
using System.Collections.Generic;
using MyEntityModelsNamespace;
using Mediachase.BusinessFoundation.Common;
using Mediachase.BusinessFoundation.Data;
using Mediachase.BusinessFoundation.Data.Business;
using Mediachase.Commerce.Customers;

namespace MyNamespace
{
    public class MyEntityFactory : AbstractFactory, IFactoryMethod<EntityObject>
    {
        /// <summary>Creates the specified obj.</summary>
        /// <param name="obj">The obj.</param>
        /// <returns></returns>
        EntityObject IFactoryMethod<EntityObject>.Create(object obj)
        {
            var keyValuePair = (KeyValuePair<string, PrimaryKeyId?>?) obj ?? throw new ArgumentNullException(nameof(obj));
            var key = keyValuePair.Key;
            EntityObject entityObject = key switch
            {
                ContactEntity.ClassName => CustomerContact.CreateInstance(),
                AddressEntity.ClassName => CustomerAddress.CreateInstance(),
                OrganizationEntity.ClassName => new MyOrganization(),
                CreditCardEntity.ClassName => CreditCard.CreateInstance()
                _ => default
            };

            if (entityObject != null && keyValuePair.Value.HasValue)
                entityObject.PrimaryKeyId = keyValuePair.Value.Value;

            return entityObject;
        }
    }
}

3. Create request handler

For an organization, as I've previously mentioned, by default it's using Mediachase.Commerce.Customers.Handlers.OrganizationRequestHandler, Mediachase.Commerce as the type. Our class then, will look like that:

using System.Collections.Generic;
using Mediachase.BusinessFoundation.Data;
using Mediachase.BusinessFoundation.Data.Business;
using Mediachase.Commerce.Customers.Handlers;

namespace MyNamespace
{
    public class MyOrganizationRequestHandler : OrganizationRequestHandler
    {
        protected override EntityObject CreateEntityObject(string metaClassName, PrimaryKeyId? primaryKeyId)
        {
            return new MyEntityFactory().Create<EntityObject>(new KeyValuePair<string, PrimaryKeyId?>(metaClassName, primaryKeyId));
        }
    }
}

The final touch; Change the configuration under the file baf.data.manager.config to point it to your new request handler. In our example, the file should have the following line instead of the default one for the organization:

<add metaClass="Organization" method="*" type="MyNamespace.MyOrganizationRequestHandler, MyAssemblyName" />

Final thoughts

Maybe it might be a bit overkill to do that just to be able to use your own class for the entities, but in the end, it helped a lot. Looking for a reference is easier; we can easily find who is using a certain custom property and whatnot. Also, it enhances a bit the readability. One other potential advantage of the approach would be for new developers, especially junior, usually not accustomed with the certain level of complexity Business Foundation entails.

Beware of multiple enumeration of IEnumerable

Fri, 17 Feb 2023 05:00:00 Z

We've all been there, one day or another, debugging a performance issue in production. It's hard to predict and especially difficult to find when it's our first time. Fortunately, though, there is a lot we can do to prevent such issues and today we'll talk about the IEnumerable interface in C#.

If you're using ReSharper or Rider from JetBrains, you're probably already aware of the famous warning: "Possible multiple enumeration of IEnumerable". Microsoft did finally also implemented the warning: https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1851. It's something, I would say, a lot of developers are easily overlooking. Though, indeed, like mentioned inside JetBrains' article, not every warning, in a sense, are truly by definition a mark of something is wrong in the code. It's a reminder that it shouldn't be ignored and be taken seriously.

I'm still often being asked today: "But Dave, what does it mean, why do I have this warning? What can I do to resolve it?" These are all legitimate questions. To help you understand why it's important, I'll take an example using Entity Framework. Assuming we have the following DbContext & table:

public class ExampleDbContext : DbContext
{
    public virtual DbSet<User> Users { get; set; }
}

public class User
{
    public long Id { get; set; }
    public string FullName { get; set; }
    public string PhoneNumber { get; set; }
}

And the following service:

public interface IExampleService
{
    IEnumerable<User>? GetUsers();
}

public class ExampleService : IExampleService
{
    private readonly ExampleDbContext _exampleDbContext;

    public ExampleService(ExampleDbContext exampleDbContext)
    {
        _exampleDbContext = exampleDbContext;
    }
    
    public IEnumerable<User>? GetUsers()
    {
        return _exampleDbContext.Users;
    }
}

Here is an example I've already seen in the past which is a code smell:

// Assuming IExampleService is injected in the IoC container. 
IExampleService exampleService = default;

var myUsers = exampleService.GetUsers();

if (myUsers.Any())
{
    foreach (var myUser in myUsers)
    {
        // do something per user.
    }
}

Normally, under JetBrains Rider or ReSharper, you would see the following error underlining the variable "myUsers":

In our previous example, we're asking Entity Framework to do two database queries, one for letting us know how many users we have and the second one to give all users. The reason this part of the code is behaving like this is because of the way IEnumerable reacts when being called. Contrary to what we expect it would do, IEnumerable types are lazily loading what's inside when requested to do so. They are "Enumerating" their content one by one when only strictly requested. And when I say strictly when only requested, it's because that's kind of the case. See, for the following line of code:

var myUsers = exampleService.GetUsers();

It will technically do "nothing". Try it under your debugger. You can put a breakpoint inside the ExampleService and you will never break to this point getting past the variable assignation. You will though if you forcibly load the IEnumerable in your debugger. When you ask the IEnumerable to give you if there is "Any" objects inside it, it will execute the enumeration, thus the underlying concrete code responsible to load the content within it. Same as for the majority, if not all, Linq extensions (Where, Select, Sum, Aggregate, etc.). So, all in all, since we call "Any" and that we iterate over our enumerable in a foreach loop, we're enumerating our IEnumerable twice, thus asking Entity Framework to give our users twice, causing two SQL queries. I think you can see where I'm going with that.

In the past, I've resolved production performance issues by simply enumerating first with "ToArray" or "ToList". There was occasions where I've found bit of code doing N+1 requests against the database.

So, if we want to prevent that, with the previous example, we could have done something as the following to prevent multiple enumerations:

// Assuming IExampleService is injected in the IoC container. 
IExampleService exampleService = default;

var myUsers = exampleService.GetUsers();
var users = myUsers as User[] ?? myUsers.ToArray();

if (users.Any())
{
    foreach (var myUser in users)
    {
        // do something per user.
    }
}

Since the variable users is the result of an enumeration of my IEnumerable, doing further manipulation of the array only plays with the in-memory values.

Some are asking me if they should be using IEnumerable at all. As much as I understand the concern, its usage still depends on what you do inside your code. It's not bad per se, it's just that you shouldn't be using it systematically for everything. See, for our previous example, there's two additional ways I see you could expose your users through the ExampleService. You could decide, design wise, to allow additional queries to be done against this API call, so in this case I would put an IQueryable<User> return type. This explicitly tell your consumer, hey be aware that you need to conclude the query with a "ToArray" or something like that. Alternatively, you could simply return an array of User or, if you want to be cool, a IReadOnlyCollection<User>. Using this method assumes that by consuming your API, you shouldn't have to do another enumeration afterwards, so the in-memory list of users is enough.

Optimizely DXP & Application Insights | Instrumentation Key VS Connection String

Fri, 17 Feb 2023 05:00:00 Z

You might be aware of the news, Microsoft is deprecating usage of the Instrumentation key–based data injestion. It has been almost one year since its announcement, but it made me thing about one thing while working with the solution of one of our clients: Optimizely DXP (Digital Experience Cloud).

When a client is subscribing to DXP, they are entitled to have a fully managed infrastructure in the Cloud to host their application, including 3 different environments:

Integration
PreProduction
Production

It's important to know that, for each environment, a different database and most notably Application Insights instance is used. This in fact the reason learning about the announcement of Microsoft made me think, but what if we're using the Connection String instead of the Instrumentation Key inside my solution?

So, some of you are already aware that we're able to view the configuration of the App Service of Integration. That lead me to find that currently speaking, only the environment variable APPINSIGHTS_INSTRUMENTATIONKEY is being used to configure the link between your application and Application Insights. Assuming this is the same setting for all environments, I realized that I cannot have a connection string configured on my local development environment - And anyway, Microsoft is pretty much straight forward about that:

Don't use both APPINSIGHTS_INSTRUMENTATIONKEY and APPLICATIONINSIGHTS_CONNECTION_STRING. Use of APPLICATIONINSIGHTS_CONNECTION_STRING is recommended.

Even though they recommend usage of a connection string, we cannot, because DXP environments are configured using the instrumentation key. So, long story short, don't use the connection string on your development machine, or at least, remove it using transformations during the deployment. If you keep using a connection string, you will have trouble with your telemetry data - Either everything will go inside your development App Insights, or your app might simply trace nothing anymore. I did not test my previous statement, but I'm confident this is what will happen.

Optimizely CMS & Commerce .NET Core migration - Tips & Tricks

Tue, 07 Feb 2023 05:00:00 Z

Last September, we had an extraordinary opportunity to share our findings and experience migrating our first Optimizely solution to .NET Core. This event occured at the Optimizely Dev Meetup in Montreal. I was presenting alongside my colleagues Pierre Vignon and Eric. So, as the title suggests, our goal was to give tips & tricks on the migration of an Optimizely solution to .NET Core. This effort obviously came with some challenges!

Here is a vague overview of the steps the process involves:

Preparation
Project conversion
Project runtime stabilizations
1. First boot stabilizations
2. Runtime stabilizations
3. Deployment pipelines
Regression fixes
Quality assurance
Go live

Preparation

You will need to plan the time required to do the migration:

Implies you will prepare your team and your client of preferably freezing other development efforts during the migration
Prepare your people: You should have a consistent team of developers, not planned to switch between projects during the migration
Limit the size of the team: You can't have that many people at the same time on the migration itself. Sure, you could give a development boost at the end, but you could also be a victim of some pitfalls related to this method, by example, duplicating the efforts; Having more than one developer working on the same thing without knowledgeably be aware of it.
Migrating a Commerce site? Plan for the removal of Commerce Manager; It's no longer existing in .NET Core.
Make an inventory of your project dependencies - You need to quickly find any dependencies requiring a replacement. Your dependency tree should be as simple as possible to minimize the complexity when migrating from packages.config to PackageReference. So, the elements to verify on this point are the following:
1. Project dependency hierarchy
2. NuGet package dependencies
Have yourself a recent database backup of production. Please make sure to make data sanitization first to avoid having personally identifiable information.
1. We did this mistake and fell into the trap. We had a very old development database that was way too different than production. This caused one of our database migrations to fail because of a schema difference when we have deployed thereafter on PreProduction

Lessons & learned: The most overlooked part of this section were the dependencies of our solution. We learned at the project runtime stabilization step that some modules/plugins/dependencies weren't compatible anymore under .NET, so we had to find alternatives. Some of which weren't available except by re-implementing them from scratch. This is by far one of the biggest bottlenecks of a migration. We had to put our own efforts to migration certain plugins, e.g., a color picker.

Optimizely also switched of image processing plugin from .NET Fx to .NET. It's now referring ImageSharp. You will have to consider changing all transformation logics inside your solution to something else, preferably using ImageSharp.Web.

Project conversion

You will have to convert all projects to the new csproj format. This process can be simplified using the .NET Upgrade Assistant. Refer to the Optimizely documentation for more information. They also have created an extension over the upgrade assistant which is going to help you during the migration.

The goal of this step is to convert all projects of the solution as quickly as possible to the newest format. Keep in mind this operation can only be done by a single developer or by pair programming if necessary. You can't have two developers on such major changes, you will simply end up with Git conflicts while trying to merge. So, typically, a single developer per project is recommended on this phase. Centralize your efforts on the migration, but not on making sure the site is compiling, it's expected not to compile after the first time the upgrade assistance as been ran.

As soon as all csproj are converted, you can easily share the rest of the conversion with all developers. From that point, you will have a lot of compilation errors. Here's a simple representation of items you need to check per project:

Simplify the referenced packages.
1. Only add those who are necessary, they rest should be including implicitly (Transitive dependency). Up until recently, you had to manage this per project, but now, with the centralized package management, you can make sure the same package versions are used within the whole solution.
Replace .NET Fx specific libraries to their .NET variants. E.g., Remove Microsoft.AspNet.Mvc and make sure only Microsoft.AspNetCore.Mvc is installed, either implicitly, or explicitly if desired
Clean stale code - Remove everything that you don't need, avoid unnecessary conversion work on something that isn't being used at all.
1. This effort should be taken up front, since the beginning of the creation of the project. Leaving stale code inside a solution is just a way to confuse other developers and make everyone loose time unnecessarily.
2. If you want to keep a code snippet, you should save it inside a Wiki note instead for further reference. In my opinion, your code repository isn't the place to save code snippets hidden in comments.
Make all the required remaining adjustment to make the project compile (not the solution, just the project).
Ensure all unit and integration tests passes as early as possible. This will help you quickly find any further regressions if applicable.

Developers has the habit to comment some part of the code when testing any changes, they've made. It's sure is a usual development style some people use, but do not take this reflex to comment everything just to reach your goal to compile the project. This is totally counter intuitive and you might even end forgetting critical parts to be migrated later.

As for database migrations, we followed Microsoft's recommendations and removed all past migrations. The only thing that left was the database context and the database models. Technically speaking, they are already deployed to production, so they are no longer necessary anyway. Adding more migration will simply create a difference with the existing schema and your modification.

Project runtime stabilizations

First boot stabilizations

Once all projects are compiling, you will then probably face a lot of runtime exceptions, especially at the first boot. Here are the commonly found issues we faced during our migration:

Configuration issues. Web.config/app.config is no longer a thing under .NET. You will have to migrate your configuration and you might face issues in relation to this.
IoC issues. You will probably forget to register a service or two. This happens, but it's quite simple to resolve usually speaking.
MVC issues. Due to the nature of the migration and especially the fact the core MVC library changed, you might face issues with your views, your customizations around it and surely refactor a lot of @helper usage
Your app is hosted in DXP? Prepare yourself to fix certain environment related hurdles, because it will be running under Linux. E.g., adjusting file paths, properly respecting their case.
Database migrations: You might face hiccups with them. To this point, it's best to test your migrations with the command line dotnet ef. You'll find all necessary resources to debug what's causing the hitches.

Runtime stabilizations

After the first successful boot, you will surely face other complications that will require your team's attention. Notably:

Broken CSS styling
Broken JavaScript
Broken pages, e.g., certain content type could be causing a crash, but only at runtime

Keep a good attention of your browser developer console, you'll probably find a couple of errors here and there, mainly responsible because the default JSON serializer is now using camel case instead of pascal case under .NET Fx.

It's very important at this phase that all developers work conjointly to find as much bugs as possible. Stack them as much as you can into the backlog. It's expected there will be a lot, so at least you can track their progress and present them to your QA team once you will reach the quality assurance phase.

DevOps Automations

In parallel, another person can work on adjusting your DevOps automations. Typically, the biggest part that will require many efforts will be the application compilation itself. Since we're switching from .NET Fx to .NET, it's best to switch using the .NET CLI under your scripts. Another thing to keep in mind; If you're deploying in DXP, make sure every package name are unique, otherwise you will receive an error stipulating the package has already been uploaded. In .NET, Optimizely prevents duplicates. The advantage though is that you can reuse an existing package to re-make a deployment without the need to re-upload it first.

In summary:

Use .NET CLI
Do not get mixed up with old *.config configuration and the newest appsettings.json one. The old configuration isn't working anymore. If you prefer, you could simply delete these old files in your repository to prevent any confusions.
- Setup your configuration transformations if necessary. You can customize them per environment by creating an additional file inside your solution, e.g., appsettings.Integration.json
DXP: Package your application using linux-x64 architecture
DXP: Make sure your application is referring the mandatory CMS and Commerce Cloud packages.
DXP: Package version must always be unique. If you intend to use an existing version, simply leverage the name of the package already uploaded to start a new deployment.

Regression fixes

To this point, you've gathered an enormous quantity of bugs inside your backlog. You now want the full team to fix them all together. Obviously, you will want all majorly impacting bugs to be fixed first, especially the ones causing crashes, until you reach certain nebulous bugs where you can't even tell if they've been provoked by the migration or if it was already there to begin with.

Couple of things to keep in mind:

Use each of you team members strength to tackle the bugs. This will fasten the correction and will ultimately give you more time on the most complicated ones.
You will have to replace and/or backport any unsupported plugins, if necessary
Find & fix any Backoffice related issues (under ~/Episerver/Cms). We had some troubles at the time, but I doubt it will be the case today.
Since your DevOps automation should be already working to this point, our recommendation is to deploy as many iterations of the site as possible. This will allow your team to quickly find more bugs as other items are being fixed in parallel.
By the end of this adventure, you will want to simulate production installations to prepare yourself for the Go-Live. Goal here is to make sure the current production database state is still handling the migrations and the switch to .NET transparently. If your application is hosted under DXP, you can easily leverage the available "Project Migration" tab under the Optimizely PaaS portal to restore as much time as you want your existing .NET Fx production environment to your .NET production one.

Quality Assurance

You're near the end. Your team of developers has found and fix every possible bug, now it's turn for your QA team to double check the stability of the whole site. They should get back to the reported bugs inside the backlog and verify every one of them to make sure they're fixed. In any case, they can reopen them if any issue arises. Also, very important they make a full regression testing, independently of the number of bugs logged or not, they want to verify every part of the site, even the most unused sections.

Your QA team will then decide together whether the stability of the site is worthy for production or not. In all scenarios, they will probably log more bugs inside the backlog for the developers to look for them afterwards. If they decide the site is ready to be released, a code freeze should be put in place to prevent any further change that could cause unwanted regressions. If in contrary they find the site too unstable for their taste, they should put the developers precisely on priority items that are blocking the release to production. Other nonessential and non critical bugs that can be fixed after, should be postponed.

In the meantime, another of your team member should have already started communications with Optimizely's team to prepare for the Go-Live. A release plan should detail every expected step your team needs to take for it. You also want to coordinate your DNS switch to your newest .NET application instance.

Go-Live

You've tested over and over, and your QA team is satisfied with the stability of your site, you are now ready for Go-Live. Even thought you've made your best to test everything, you should still expect things can go wrong during the procedure. Fortunately, if in any ways something goes bad, you can still use the old production environment, which should still be intact.

A general idea of the steps to take:

Keep old .NET Fx environments intact
Put maintenance page on .NET Fx production environnement
Deploy to new .NET production environment
Verify stability and every key element, e.g., capable of taking an order
Switch DNS to new .NET production environment
Monitor traffic & logs in case you missed something very important and that you need to make a hotfix

Conclusion

All in all, I loved the experience, it was quite a challenge! The things all developers loved the most during this adventure was the speed the site took to load. It's so fast, it's extremely unrecognizable from the .NET Fx variant of the site. Optimizely also published some metrics on the subject and I'd say they aren't far fetched at all.

How I ended up fixing a bug using an IoC trick

Tue, 10 Jan 2023 05:00:00 Z

We did a first .NET Core migration of Optimizely for one of our client last year. We were one of the early adopters - As far as I know, I think we were told we were like the forth or fifth migration to be ever initiated as part of this effort. Optimizely first released their first stable .NET Core release back on Q4 2021 if my memory is correct. In Q1-2 of 2022 we then started to migrate our client and we did it successfully. The thing though, at the time we did the migration, only .NET 5 was targeted for certain Optimizely libraries, so had to do this migration in .NET 5, even though it was about to be EOL by the beginning of May 2022.

This lead us to migrate our client a second time when all libraries were targeting .NET 6 later on the same year. This is where we faced a major issue with some of the carts on the website. Not systematically all of them, but it was quite a deal breaker.

Under this solution, we have a custom IPayment, which was being used to secure different payment data. For simplifying my explanations, we'll call this custom payment a CustomPayment (ooohh super original). This CustomPayment was rarely used, thus the reason the problem wasn't occurring all the time. I ended up finding the root cause by these simple reproduction steps:

Create a new payment using the type CustomPayment with a call on IOrderGroupFactory.CreatePayment(orderGroup, typeof(CustomPayment));
Set the previously created payment inside the cart form payments of the user
Call IOrderRepository.Save(cart); with the user's cart now containing the CustomPayment

Thereafter, every following http request would provoke a crash. They were all caused by any call being made on OrderRepository.Load<ICart>([...]).

Upon further investigating the problem, I found out the source of the issue was coming from Optimizely's library, which leads me to find a behavioral change on how the payments are deserialized between version 14.2.0 and 14.6.0 of Episerver.Commerce.Core. When decompiling both versions of the class PaymentConverter, the method Create does things quite differently:

Version 14.2.0 and similar:

    private IPayment Create(JObject jObject, Type objectType)
    {
      string typeName = JToken.op_Explicit(jObject["ImplementationClass"]);
      if (string.IsNullOrEmpty(typeName))
        return this._paymentFactory.Service(objectType);

      Type type = Type.GetType(typeName);
      return type == (Type) null || typeof (Payment).IsAssignableFrom(type) && this._featureSwitch.Service.IsSerializedCartsEnabled() ? this._paymentFactory.Service(objectType) : this._paymentFactory.Service(type);
    }

Version 14.6.0:

 private IPayment Create(JObject jObject, Type objectType)
    {
      string str = JToken.op_Explicit(jObject["ImplementationClass"]);
      if (string.IsNullOrEmpty(str))
        return this._paymentFactory.Service(objectType);

      Type type = TypeResolver.GetType(str);
      return type == (Type) null ? this._paymentFactory.Service(objectType) : this._paymentFactory.Service(type);
    }

Explanation time! So under the working version, the variable type is indeed assignable from a Payment and the feature switch is enabled. Since this is the case, the condition is using the variable objectType, which at runtime, is assigned with the value EPiServer.Commerce.Order.Internal.SerializablePayment. The paymentFactory is a wrapper around the IoC ServiceProvider, so basically it creates an empty instance of a SerializablePayment. A SerializablePayment is registered elsewhere by Optimizely inside the IoC container, so this is why this is working.

As for the non-working version, the issue is quite evident. At the return statement, the variable type is never null, so it calls the second end of the condition, the paymentFactory with the variable type as parameter. As we have never registered our custom payment under the IoC container, this line will return null and will cause a crash elsewhere in Optimizely's code.

At first, I thought I could simply add our CustomPayment inside the IoC container, but that caused another issue in relation to the deserialization logic of Optimizely. The type must absolutely be compatible with a SerializablePayment. This, of course, isn't the case; our custom payment is only inheriting from Mediachase.Commerce.Orders.Payment. To counter this issue, I used a very obscure and a "I wouldn't recommend it" approach to resolve the problem. Before moving with the solution though, let me first tell you about type forwarding: As you're probably already aware, there's the existence of extension methods allowing you to "Forward" certain types to others under the IoC container, it is known to be available under the Optimizely libraries. It's also a practice other third party IoC containers have implemented, e.g., Windsor, which also has this forward type concept. All in all, the idea is quite straightforward: You want to have a certain service, to be registered under multiple different types. Any of the registered types will resolve the same service instance, based on its configured lifetime. This is what gave me the idea to resolve the issue like this:

// The following two lines are the equivalence of this call: services.Forward<SerializablePayment, CustomPayment>();
// Except that on the second line, I cast the instance as IPayment instead of a SerializablePayment.
// This is a hack, it will force Epi to use its in house object when deserializing a CustomPayment. 
var serviceDescriptor = services.First((Func<ServiceDescriptor, bool>)(s => s.ServiceType == typeof(SerializablePayment)));
// ReSharper disable once RedundantCast -> Keep it, important.
services.Add(typeof(CustomPayment), s => s.GetService<SerializablePayment>() as IPayment, serviceDescriptor.Lifetime);

Super sketchy, but it works. Like mentioned inside the comments, the code is inspired from the "Forward" extension method of Optimizely. It does the following:

Gets the service descriptor of the already registered SerializablePayment service.
Adds a new service of type CustomPayment which resolves to the existing SerializablePayment already registered within the IoC container.
- The trick is to cast the SerializablePayment as IPayment

Since both CustomPayment and SerializablePayment inherits from IPayment, this resolves our deserialization issue. At runtime, the call onto _paymentFactory.Service(type); will simply load a SerializablePayment, even though the value of the variable type is CustomPayment.

Edit: The bug has been fixed: https://world.optimizely.com/support/bug-list/bug/COM-16500.

Don't manually change the TLS version using ServicePointManager.SecurityProtocol

Tue, 10 Jan 2023 05:00:00 Z

Coming late to the game, but I've often saw, in the TLS 1.0 & 1.1 deprecation era, people disabling these protocols by simply doing the following:

System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12

Sure, it will work, but this line of code is far from ideal and is not friendly maintainability wise. Reasons around that:

You might have to write this line of code in a couple of different areas of your code
You will have to keep track of those areas for future updates (e.g., for the deprecation of TLS 1.2 by example)
It's not guaranteed third party libraries will work with the instruction

Microsoft recommends to do otherwise and I'll admit it's quite simpler this way than the other around. All in all, what you need inside your app configuration is the following:

<appSettings>
    <add key="AppContext.SetSwitch:Switch.System.Net.DontEnableSchUseStrongCrypto" value="false" />
    <add key="AppContext.SetSwitch:Switch.System.Net.DontEnableSystemDefaultTlsVersions" value="false" />
</appSettings>

This instructs your app to use the system recommended cyphers and TLS versions when your app is doing secure communications. So, without changing a single line of code, you're asking .NET to follow the system recommendations, not his.

Keep in mind, per the documentation of Microsoft, these settings will have an impact on certain .NET Fx targets:

For DontEnableSchUseStrongCrypto, applications compiled using a target framework lower than 4.6 are impacted
For DontEnableSystemDefaultTlsVersions, targets lower than .NET 4.7 are impacted

Otherwise, by default, these configurations are disabled. This means they use the recommended TLS version and strong cryptos.

Another thing to point out, certain third-party libraries, compiled using old .NET targets will also be impacted. Say, by example, you have added a NuGet package targeting only .NET 4.5, well these settings are also impacting your reference. If by any way it's using TLS, the library will also use the system recommended versions. By experience, this also applies even though your app is compiled using a recent .NET target (e.g., 4.7.2). So, if you're not specifying the flags and that you're referencing a third-party library compiled with an older target, you should also specify the flags, as the library otherwise will fallback in using the wrong TLS version and cyphers.