Add-ons Installation and Management - Optimizely CMS 12

Exam Area: Content Area 2 – Installation, Operation & Configuration (20%)
Reference: https://docs.developers.optimizely.com/content-management-system/docs/installing-add-ons

---

1. What Are Add-ons?

Add-ons (also called Apps) are NuGet packages that extend the functionality of Optimizely CMS.

Sources for Add-ons:

• Optimizely App Marketplace: https://marketplace.optimizely.com
• NuGet.org
• Optimizely NuGet feed: https://nuget.optimizely.com

---

2. Installing an Add-on

# Via .NET CLI
dotnet add package EPiServer.Forms --version 5.*
dotnet add package EPiServer.Find --version 14.*

# Via NuGet Package Manager in Visual Studio
# Search → Install → Restore

---

3. Registering Add-on Services

Most add-ons require service registration in Program.cs:

// Example: Optimizely Forms
builder.Services.AddEpiserverForms();

// Example: Optimizely Find/Search
builder.Services.AddFind();

// Example: TinyMCE (included in EPiServer.CMS.TinyMce)
builder.Services.AddTinyMce();

---

4. module.config for Add-ons

Some add-ons require a module.config entry:

<?xml version="1.0" encoding="utf-8"?>
<module>
  <assemblies>
    <add assembly="EPiServer.Forms" />
    <add assembly="EPiServer.Forms.UI" />
  </assemblies>
</module>

---

5. Add-on Upgrade Process

Checking compatibility:

1. Review the add-on release notes
2. Check the version matrix (CMS version vs. Add-on version)
3. Backup before upgrading

# Update an add-on
dotnet add package EPiServer.Forms --version 5.x.x

# Check for outdated packages
dotnet list package --outdated

# Build to check for breaking changes
dotnet build

---

6. Common Add-ons

---

7. Files Installed by Add-ons

Add-ons typically install into:

• NuGet packages → packages/ folder
• Static files → wwwroot/ (client resources)
• Views → Embedded in the assembly
• Database → Schema updates

// Add-ons can use IInitializableModule for initialization
[InitializableModule]
[ModuleDependency(typeof(ServiceContainerInitialization))]
public class FormsInitialization : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        // Initialize forms
    }
    
    public void Uninitialize(InitializationEngine context) { }
}

---

8. Dependency Management

NuGet version resolution:

<!-- In .csproj, pin version if needed -->
<PackageReference Include="EPiServer.CMS" Version="[12.5.0]" />  <!-- Exact -->
<PackageReference Include="EPiServer.Forms" Version="5.*" />      <!-- Minor range -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.*" />   <!-- Patch range -->

Resolving conflicts:

# Check dependency tree
dotnet list package --include-transitive

# If conflict, pin the version

---

9. Developing Custom Add-ons

// Add-on must have ModuleDependency attribute in AssemblyInfo
[assembly: ModuleDependency(typeof(EPiServer.Web.InitializationModule))]

// Add-on project structure:
// MyAddon/
// ├── ClientResources/   (JS, CSS)
// ├── Models/
// ├── module.config
// └── MyAddon.csproj

---

10. Script Injection to Enable Add-ons

// Add-ons inject scripts into the CMS UI
// module.config
<clientResources>
  <add name="MyAddonScript" 
       path="ClientResources/Scripts/addon.js" 
       resourceType="Script" />
</clientResources>

// Or via code in initialization
public class MyAddonInit : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        // Inject client resources
        var requiredResources = context.Locate.Advanced
            .GetInstance<IRequiredClientResourceList>();
        requiredResources.RequireScript("~/ClientResources/addon.js")
                         .AtFoot();
    }
}

---

Review Questions

1. How are add-ons installed? (Via NuGet packages)
2. Where is the Optimizely App Marketplace? (marketplace.optimizely.com)
3. How do you inject an add-on's scripts into the CMS UI? (Via module.config or IRequiredClientResourceList)
4. Can add-ons modify the database? (Yes, via schema migrations during initialization)
5. What is the first step when upgrading an add-on? (Check compatibility and create a backup)