Blog posts by MilosR

Beginner's Guide for Optimizely Backend Developers

Wed, 10 Dec 2025 09:36:47 GMT

Developing with Optimizely (formerly Episerver) requires more than just technical know‑how. It’s about respecting the editor’s perspective, ensuring performance, and applying conventions that make content management sustainable. Below are some of the most common mistakes that beginner Optimisely developers make that I have collected from number of different projects I had a chance to work on in the last couple of years.

Respect Editorial Settings

Always account for languages, publish status, access rights, and personalization settings.
Don’t rely solely on ContentRepository to fetch content — editors can apply rules in edit mode that must be respected.
In multilingual implementations, be sure to return correct language, taking care of fallback settings that editor can set.
Use Search & Navigation APIs to retrieve lists of pages, applying filters for deleted or unpublished content, and excluding restricted pages like 404s.
Also be prepared to have a fallback strategy in case Search & Navigation API is not accessible.
Take care of all LinkItem properties when rendering link on the page like title and target.

Caching Strategies

Cache global settings and common page elements to improve performance.
Always tend to cache view models, never Optimizely data models, to avoid unnecessary memory consumption.
Take care of cache invalidation strategy.

Modeling Content Types

Think from the editor’s perspective when designing page types and blocks.
Make sure to provide smooth editing experience.
Apply SOLID programming principles
Take care on usage of base classes, interfaces and inheritance.
When modeling content types and properties always ask following questions:
- is it going to be reusable?
- is it going to contain one or more items?
- is it global or site related?
- is it required or optional?
- can it have a default value?
- is it localizable?
- is it searchable?
- what can be validation rules?
Use ContentArea when you need:
- Personalization
- Grouping blocks
- Applying grid settings
Use XHtmlString when you need rich text editing capability, but be aware that XHtmlString is also a container for all other content types, similar as ContentArea it supports personalization
Use blocks when you need reusable content or when you need to apply personalization in ContentArea.
Use block as property type to group more properties, that also makes those properties easy editable in page preview mode
Avoid nesting more than two levels of blocks to prevent performance and indexing issues.
For dynamic content nesting, prefer IList<BlockType> property with BlockType defined as AvailableInEditMode = false.
Learn and leverage out‑of‑the‑box property selections.
Remember: any change to a content type model mutates the database, except attribute values like DisplayName or validation rules.
Property removed from the code is NOT removed from the database, be sure to clean up those properties from Admin mode.
When you need to validate input from editor, use validation attribute instead of Saving event.
Determine carefully which content types can be nested within others, and specify which blocks are permitted in the Content Area.
Avoid creating circular references between content types, as this can lead to infinite loops and cause problems with Find indexing.

Scheduled Jobs

Scheduled jobs behave differently when run manually versus automatically.
When manually triggered, that means you are logged in and it will use your user principal.
Ensure the correct user principal is set when running scheduled job automatically and when accessing protected content.
Monitor for job stopped signals during execution to handle interruptions gracefully.
Be sure to disable Scheduled Jobs in the development environment to avoid jobs running in the background without notice.

Site and Domain Awareness

The current domain in the URL determines the active site.
Review site settings carefully: a site with * in its host list will respond to all domains pointing to that server.

Rich Text Editing

Configure TinyMCE options: fonts, styles, plugins, allowed blocks, and personalization features.
Understand the relationship between XHtmlString and ContentArea:

- XHtmlString is a flexible container for any content, renders as a TinyMCE editor.
- ContentArea inherits from XHtmlString and renders just as a content container.

Property Management

Properties can define type, default values, and attributes such as UIHint, Validation, Localization, Display, and rendering options.
Control how properties are rendered and their visibility in edit mode.
Use events carefully, casting to the lowest possible type (e.g., interface) to ensure correctness.

Find Indexing

Take care on content that needs to be indexed, add necessary indexing conventions.
Take care when setting up development environment not to use Optimizely DXP indexing service URL, otherwise content from you local DB might end up there.

Conclusion

Optimizely development is not just about writing code — it’s about creating a seamless experience for editors, ensuring performance, and applying conventions that scale. By respecting editorial settings, caching wisely, modeling content thoughtfully, and configuring tools like TinyMCE, developers can deliver solutions that empower both content creators and end users.

Upgrade Optimizely CMS From v11 to v12

Mon, 13 May 2024 09:04:37 GMT

Why Upgrade?

There are many improvements implemented in version 12, but most importantly is that the whole framework is migrated from .Net Framework 4 to .NET 6.

Upgrade also contains significant security, performance and headless improvements, while Optimizely framework APIs remains the same so existing code won't break and there is no DB migration involved, except for user tables which need to migrate from AspNet Identity scheme to OpenId.

Since it is now .Net Core native that also means it is OS agnostic and can be hosted on platforms other than Windows, like Linux for example.

How To Upgrade?

Suggested way is to use Optimizely Upgrade Assistant that will backup current solution and upgrade project to desired .NET Core version. The assistant will also try to migrate backend code and views, but that should be taken with caution. Developer needs to manually migrate from web.config to appsettings.json settings style, migration from global.asax to startup.cs, migration from OWIN and ASP.NET authentication to OpenID authentication, migration of block controllers to components, dependency injection, logging, JSON serialization etc.

WebForms are no longer supported, which means MVC is the preferred way to render content.

Upgrading from .Net Framework 4 to .NET 6 means that some of the NuGet packages used are no longer compatible and need either updating them to their .Net Core versions (and hoping they have compatible APIs) or replacing them with other packages or even rewriting some of the functionalities. That can't be predicted as every solution is specific and must be carefully analyzed before giving any estimations.

Most importantly, take backups of both solution and DB before taking any actions. Prepare a new environment for testing of upgraded solution where all functionalities can be checked before replacing the old solution.

Step By Step Guide

I have tested Optimizely Upgrade Assistant on a simple project with few page types and blocks.

First step is to install Assistant using .NET CLI tool by running command from Command Prompt:

dotnet tool install -g upgrade-assistant

This will install Microsoft Upgrade assistant from .Net Framework to .NET Core.

Second step is to download Optimizely extension from Upgrade Assistant GitHub: https://github.com/episerver/upgrade-assistant-extensions/releases

Unpack files into temporary folder like: C:\Temp\EPi.Source.Updater.1.0.33

Then, run the command to upgrade startup project:

upgrade-assistant upgrade {projectName}.csproj --extension C:\Temp\EPi.Source.Updater.1.0.33 --ignore-unsupported-features

After completing upgrade procedure you’ll end up with lot of dependency issues (both old Episerver packages and new ones mixed), unresolved code issues, project not structured up to .Net Core standards (no wwwroot folder, static files are still in the project root), Program.cs and Startup.cs need adjustments, code from Global.asax.cs not migrated…

So, there is a lot of work to do for such a small project. Alternatively, instead of running upgrade assistant, I would start by creating a new solution with empty Optimizely CMS project based on .NET 6 (using Optimizely Visual Studio project template). Then, gradually transfer code from the old solution to the new one. Copy static files to wwwroot folder, copy backend files. Install missing NuGet packages but with their .Net Core versions. Some packages will have different APIs so you’ll need to update method signatures, or even rewrite some portions of code completely if the method is no longer supported.

Keep in mind that .Net Core have a different dependency injection mechanism, logging, exception filters, JSON handling, block controllers are now components etc.

There is no magic wand for this process and must be done manually. At the end, after the project is successfully building, migrate DB users using script located in EPi.Source.Updater.1.0.33 folder.

Should I Upgrade?

That decision needs to be taken by answering some questions:

do I plan further development of current solution? If yes, then you should consider upgrading
am I satisfied with the performance of the current solution? If not, then you should consider upgrading
is investment in upgrading going to bring considerable value to the company? If yes, then you should consider upgrading

References

https://learn.microsoft.com/en-us/aspnet/core/migration/proper-to-2x/?view=aspnetcore-6.0

https://github.com/episerver/upgrade-assistant-extensions

https://docs.developers.optimizely.com/content-management-system/docs/upgrading-to-content-cloud-cms-12

https://docs.developers.optimizely.com/content-management-system/docs/upgrade-assistant

https://world.optimizely.com/resources/videos/video/?vid=300437

https://www.youtube.com/watch?v=Fvys7G2Vdvc

Optimizely Unit Testing Using CmsContentScaffolding Package

Fri, 26 Apr 2024 09:49:47 GMT

Introduction

Unit tests shouldn't be created just for business logic, but also for the content and rules defined for content creation (available content types, validations etc.). That way Optimizely solution becomes resilient to content type and rule changes.

Usually there is a local development DB or test DB that is used continuously and, as test content is created in Optimizely and backend development is continuously changing content types and validation rules, it rarely gets verified as if content is created from scratch. That can lead to false thinking that test content represents realistic picture of what client will be able to create, but those issues will start popping up on staging environment as soon as client starts with content creation.

The benefit you get with content unit tests is verification of desired site structure and validation rules as soon as change is introduced and always starts with empty DB from scratch, verification that controller output model contains all data needed. In order to easily outline content structure there is a library called CmsContentScaffolding that uses simple fluent syntax. It can create complete site structure, easily create large number of pages and prepare content for testing.

CmsContentScaffolding Package

Added as a Nuget package and registered service dependency using: services.AddCmsContentScaffolding();, followed with IApplicationBuilder extension method appBuilder.UseCmsContentScaffolding(builderOptions: o => {}, builder: b => {});. There are two sections: builderOptions (provides global options like language used, site host, site name, publish or just create page drafts, users and roles...) and builder that exposes methods for content creation. You can create multiple sites by using another section of appBuilder.UseCmsContentScaffolding(builderOptions: o => {}, builder: b => {});. Builder have two main methods UseAssets(ContentReference.SiteBlockFolder) and UsePages(ContentReference.RootPage) which serves as a starting points from where content creation starts.

Additionally, there is a package with helper methods for fake texts, images and videos, called CmsContentScaffolding.Shared.Resources.

UseCmsContentScaffolding method has many options and can look like this:

app.UseCmsContentScaffolding(
builderOptions: o =>
{
o.Language = CultureInfo.GetCultureInfo("sr");
o.StartPageType = typeof(StartPage);
o.BuildMode = BuildMode.Append;
},
builder: b =>
{
var teaser2Ref = ContentReference.EmptyReference;
var teaser3Ref = ContentReference.EmptyReference;
var articlePageRef = ContentReference.EmptyReference;

b.UseAssets(ContentReference.SiteBlockFolder)
.WithFolder("Folder 1", l1 =>
{
l1
.WithFolder("Folder 1_1", l2 =>
{
l2.WithBlock<TeaserBlock>("Teaser 1", out teaser2Ref, x =>
{
x.Heading = "Teaser 1 Heading";
x.Text = ResourceHelpers.Faker.Lorem.Paragraph();
x.Image = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 2", ".png", ResourceHelpers.GetImageStream());
});
})
.WithMedia<VideoFile>(x => x.Name = "Test video", ResourceHelpers.GetVideoStream(), ".mp4")
.WithBlock<TeaserBlock>("Teaser 3", out teaser3Ref, x =>
{
x.Heading = "Test";
x.Text = ResourceHelpers.Faker.Lorem.Paragraph();
x.Image = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 2", ".png", ResourceHelpers.GetImageStream());
});
})
.WithContent<ContentFolder>(x => x.Name = "Folder1")
.WithContent<ImageFile>(x => x.Name = "Image 1");

b.UsePages(ContentReference.RootPage)
.WithStartPage<StartPage>(p =>
{
p.Name = "Home Page";
p.MainContentArea
.AddExistingItems(teaser2Ref, teaser3Ref)
.AddItem<TeaserBlock>("Start Page Teaser", b =>
{
b.Heading = ResourceHelpers.Faker.Lorem.Slug();
b.Text = ResourceHelpers.Faker.Lorem.Paragraph();
b.Image = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 2", ".png", ResourceHelpers.GetImageStream());
});
}, CultureInfo.GetCultureInfo("sv"), t =>
{
t.Name = "Start Page [SV]";
}, l1 =>
{
l1
.WithPage<ArticlePage>(out articlePageRef, p =>
{
p.Name = "article1";
p.MetaTitle = ResourceHelpers.Faker.Lorem.Slug();
p.TeaserText = ResourceHelpers.Faker.Lorem.Paragraph();
p.MainBody
.AddStringFragment(ResourceHelpers.Faker.Lorem.Paragraphs())
.AddContentFragment(PropertyHelpers.GetOrAddMedia<ImageFile>("Image 1", ".png", ResourceHelpers.GetImageStream()))
.AddStringFragment(ResourceHelpers.Faker.Lorem.Paragraphs());
p.PageImage = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 1", ".png", ResourceHelpers.GetImageStream());
p.MainContentArea
.AddItem<JumbotronBlock>("Jumbotron Block", b =>
{
b.ButtonText = ResourceHelpers.Faker.Lorem.Slug();
b.ButtonLink = new Url(ResourceHelpers.Faker.Internet.Url());
b.Heading = ResourceHelpers.Faker.Lorem.Slug();
})
.AddItem<ImageFile>(options: i =>
{
i.Name = "Test Image";
i.ContentLink = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 1", ".png", ResourceHelpers.GetImageStream());
})
.AddExistingItem(teaser3Ref);
})
.WithPages<ArticlePage>(p =>
{
p.Name = "Article 33";
p.MetaTitle = ResourceHelpers.Faker.Lorem.Slug();
p.TeaserText = ResourceHelpers.Faker.Lorem.Paragraph();
p.MainBody.AddStringFragment(ResourceHelpers.Faker.Lorem.Paragraphs(10));
p.MainContentArea.AddExistingItem(teaser2Ref);
}, 100);
})
.WithPages<ArticlePage>(p =>
{
p.Name = ResourceHelpers.Faker.Lorem.Slug(2);
p.MainContentArea
.AddItems<TeaserBlock>(b =>
{
b.Heading = ResourceHelpers.Faker.Lorem.Slug();
b.Text = ResourceHelpers.Faker.Lorem.Paragraph();
b.Image = PropertyHelpers.GetOrAddMedia<ImageFile>("Image 1", ".png", ResourceHelpers.GetImageStream());
}, 10);
}, 10)
});

It allows you to create assets structure, reuse created content by fetching it's references, create translated versions, create sub items without limit, create many content items of the same type using total parameter which can be any number between 1 and 10000, multiple sites with specific users and roles assigned etc.

Package is open source and can be found on this URL: https://github.com/milosranko/CmsContentScaffolding

Unit Test Fundamentals

We can identify five important points when it comes to creating unit tests:

Defining a unit test
Should be automated and repeatable
Should be easy to implement and read using AAA pattern (Arrange, Act, Assert)
Should be fully isolated
Cleanup resources after tests are finished

We will first initialize test using dedicated unit test DB (special SQL Server user should be created with sa rights to create and delete DB), then we will seed content using CmsContentScaffolding, write tests and clean up resources (including DB) after tests are finished.

Unit test can be performed using contentLoader to get desired content and verify it is created invoking controller action.

Example

In this example we will see how test method can look like when implemented using triple A principle and when controller method is invoked. We verify that the output view model is having expected state.

[TestMethod]
public void StartPageController_ShouldReturnIndexViewModel()
{
//Arrange
var contentLoader = ServiceLocator.Current.GetRequiredService<IContentLoader>();
var siteDefinitionRepository = ServiceLocator.Current.GetRequiredService<ISiteDefinitionRepository>();
var siteDefinition = siteDefinitionRepository
.List()
.Where(x => x.GetHosts(CultureInfo.GetCultureInfo("sr"), false).Any())
.Single();
var startPage = contentLoader.Get<StartPage>(siteDefinition.StartPage);
var _controller = new StartPageController();

//Act
var res = (ViewResult)_controller.Index(startPage);

//Assert
Assert.IsNotNull(res);
Assert.IsInstanceOfType(res.Model, typeof(PageViewModel<StartPage>));
Assert.IsNotNull(((PageViewModel<StartPage>)res.Model).CurrentPage.MainContentArea);
}

Conclusion

Constant verification of implemented code is crucial for continuous software development. In Optimizely CMS framework content and site structure are crucial components and must be maintained and constantly verified in order to avoid unwanted issues when you less expect them. I have used CmsContentScaffolding library on last project and found it very helpful, either as a unit test helper or to quickly scaffold site structure and perform manual tests and investigate bugs.

I would like to ask you to check it out and leave a comment on this blog post.

https://github.com/milosranko/CmsContentScaffolding

Appendix

CmsContentScaffolding package can be also used to outline products catalog in Optimizely Customized Commerce solution.

Example:

app.UseCmsContentScaffolding(
    builderOptions: o =>
    {
        o.SiteName = "Demo";
        o.Language = CultureInfo.GetCultureInfo("en");
        o.SiteHost = "https://localhost:5000";
        o.BuildMode = BuildMode.Append;
        o.StartPageType = typeof(StartPage);
    },
    builder: b =>
    {
        b.UseAssets(referenceConverter.GetRootLink())
        .WithContent<CatalogContent>(x =>
        {
            x.Name = "Catalog 1";
            x.DefaultCurrency = "EUR";
            x.DefaultLanguage = "en";
            x.WeightBase = "kgs";
            x.LengthBase = "cm";
        }, l1 => l1.WithContent<FashionNode>(x => x.Name = "Men", l2 =>
                    l2.WithContent<FashionNode>(x => x.Name = "Shoes", l3 =>
                        l3.WithContent<FashionProduct>(x => x.Name = "Product 1", l4 =>
                            l4
                            .WithContent<FashionVariant>(v => v.Name = "Variant 1")
                            .WithContent<FashionVariant>(v => v.Name = "Variant 2"))
                        .WithContent<FashionProduct>(x => x.Name = "Product 2")
                        .WithContent<FashionProduct>(x => x.Name = "Product 3")
                 ).WithContent<FashionNode>(x => x.Name = "Accessories", l3 =>
                    l3
                    .WithContent<FashionProduct>(x => x.Name = "Product 1")
                    .WithContent<FashionProduct>(x => x.Name = "Product 2")
                    .WithContent<FashionProduct>(x => x.Name = "Product 3")
                 )
            )
        );
    });