Один день из жизни Optimizely OMVP: миграция Optimizely

Грэм Карр | январь 2026 г.

Поскольку Optimizely CMS 13 теперь доступна в предварительной версии, разработчикам расширений необходимо понимать, какие изменения необходимы, чтобы их пакеты были совместимы с новой версией. В этом посте я расскажу о конкретных изменениях, которые я внес для миграции. Расширения OptiGraph — надстройка Optimizely CMS для управления синонимами, закрепленными результатами, веб-перехватчиками и настраиваемыми источниками данных в Optimizely Graph.

Обзор изменений CMS 13

Прежде чем углубляться в технические детали, стоит понять масштабы этой миграции. В отличие от обширного обновления CMS 11 до CMS 12 (которое включало переход с .NET Framework на .NET), миграция с CMS 12 на CMS 13 значительно проще. Основные изменения включают в себя:

• Требование .NET 10 – CMS 13 нацелена на .NET 10.
• Устаревшие API – Несколько устаревших API были помечены как устаревшие.
• Новая модель приложения – SiteDefinition заменен на более гибкую настройку приложения.
• Помощники тегов пользовательского интерфейса оболочки – Новый элемент заменяет устаревшие помощники навигации

Шаг 1. Обновите целевую платформу

Первое и самое фундаментальное изменение — обновление целевой платформы с .NET 8 до .NET 10.

До (CMS 12):

net8.0

После (CMS 13):

net10.0

Шаг 2. Обновите ссылки на пакеты NuGet.

Все пакеты Optimizely необходимо обновить до версии 13.x. Вот что изменилось в основном проекте расширения:

До (CMS 12):

После (CMS 13):

Для примера сайта CMS потребуются дополнительные пакеты:

Шаг 3. Обновите global.json

Если ваше решение использует global.json файл, чтобы закрепить версию SDK, обновите его до .NET 10:

{
  "sdk": {
    "version": "10.0.102",
    "rollForward": "latestMinor"
  }
}

Шаг 4. Обработка устаревших API

В CMS 13 признаны устаревшими некоторые API, которые обычно использовались в расширениях. Вот что нужно искать и как это исправить:

Ссылка на страницу → Ссылка на содержимое

Если ваше расширение использует Ссылка на страницузамените его на Ссылка на контент:

// Before
PageReference pageRef = new PageReference(123);

// After
ContentReference contentRef = new ContentReference(123);

PageData.PageLink → ContentLink

// Before
var link = pageData.PageLink;

// After
var link = pageData.ContentLink;

Общий параметр IContentTypeRepository

Общий аргумент был удален из IContentTypeRepository:

// Before
IContentTypeRepository _pageTypeRepository;

// After
IContentTypeRepository _contentTypeRepository;

Изменения местоположения сервиса

Расположение сервиса через InitializationEngine.Locate и context.Locate.Advanced.GetInstance() сейчас устарело. Используйте внедрение конструктора с IServiceProvider вместо:

// Before (obsolete)
var myService = context.Locate.Advanced.GetInstance();

// After (preferred)
public class MyClass
{
    private readonly IMyService _myService;

    public MyClass(IServiceProvider serviceProvider)
    {
        _myService = serviceProvider.GetRequiredService();
    }
}

Кончик: Проверьте предупреждения компилятора в вашей IDE — они помогут вам узнать обо всех устаревших API-интерфейсах в вашей кодовой базе.

Шаг 5. Обновите стартовую конфигурацию

CMS 13 требует некоторой дополнительной настройки в вашем Стартап.cs:

Добавить поддержку групп посетителей

services.AddCmsAspNetIdentity()
        .AddCms()
        .AddAdminUserRegistration(x => x.Behavior = RegisterAdminUserBehaviors.Enabled | RegisterAdminUserBehaviors.LocalRequestsOnly)
        .AddVisitorGroups()  // Required in CMS 13
        .AddEmbeddedLocalization();

Настройка совместимости базы данных

services.Configure(options =>
{
    options.UpdateDatabaseCompatibilityLevel = true;
});

Шаг 6. Обработка изменений компонентов Blazor (.NET 10)

Если ваше расширение использует компоненты Blazor (как это делает OptiGraphExtensions), вам может потребоваться добавить это свойство в ваш потребляющий проект. .csproj:

true

Это гарантирует правильное включение статических веб-ресурсов из библиотек классов Razor, на которые имеются ссылки.

Шаг 7. Обновите страницы макета администратора с помощью новых вспомогательных тегов пользовательского интерфейса оболочки

В CMS 13 представлен новый способ интеграции страниц администрирования с навигацией Optimizely Shell с помощью вспомогательных функций тегов. Если у вашего расширения есть пользовательские страницы администрирования, вам необходимо обновить файлы макета.

Добавьте вспомогательную функцию тега EPiServer.Shell.UI.

В вашем файле макета администратора (например, _LayoutBlazorAdminPage.cshtml), добавьте новую вспомогательную ссылку на тег:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, EPiServer.Shell.UI

EPiServer.Shell.UI Вспомогательная библиотека тегов предоставляет новые пользовательские элементы для интеграции с оболочкой CMS.

Замените вспомогательные методы навигации элементом навигации по платформе

До (CMS 12):

@Html.CreatePlatformNavigationMenu()

    @RenderBody()

После (CMS 13):

    @RenderBody()

Новый Элемент — это вспомогательный элемент тега, который отображает панель навигации платформы Optimizely. Ключевые моменты, на которые следует обратить внимание:

1. Фиксированное позиционирование – элемент создает фиксированную панель навигации вверху страницы.
2. Требуется смещение содержания – Вы должны добавить отступ сверху: 56 пикселей (или что-то подобное) в вашу оболочку контента, чтобы предотвратить его скрытие за фиксированной навигацией.
3. Исправление прокрутки – CSS оболочки может быть установлен переполнение: скрыто на теле, поэтому вам может потребоваться переопределить это:

html, body {
    overflow: auto !important;
    height: auto !important;
}

Полный пример макета

Вот полный пример макета администрирования, совместимого с CMS 13:

@using EPiServer.Framework.Web.Resources
@using EPiServer.Shell.Navigation
@using EPiServer.Shell.UI.Helpers.Internal

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, EPiServer.Shell.UI




    

    
    @ClientResources.RenderResources("ShellCore")
    @ClientResources.RenderResources("ShellCoreLightTheme")

    

    


    @Html.AntiForgeryToken()
    
    

        @RenderBody()