Matrix42 ESM Platform Migration Guide

Overview

As part of the Matrix42 strategy “Cloud Your Way” the Enterprise Service Management Platform (ESMP) is undergoing a fundamental modernization to support deployment within Linux containers.

This document outlines:

The target architecture and transformation goals
Key delivery milestones
Planned breaking changes
Guidance for adapting existing extensions to ensure compatibility with the modernized platform

Target Architecture

Goals

Modern Technology Adoption: Introduce current and widely adopted technologies to enhance development speed, talent acquisition, security, and compliance.
Optimized Deployment: Transition to a containerized, Linux-based architecture for efficient operations, cost reduction, and zero-downtime maintenance.
Improved Reliability: Isolate background processes to increase system stability and maintainability.
Scalability & Security: Enable future scalability and enhance security through sandboxed execution environments.
Flexible Cloud Support: Ensure deployment compatibility across public and private clouds using immutable containerized applications

Target Architecture

Key Changes:

Introduction of the Functional Worker process, replacing legacy components: HostCommon, HostScheduler, and Worker.
Applications run on .NET Core:
- Compiled for Windows (on-premises)
- Compiled for Linux (containerized deployments)
All backend custom logic now runs in sandboxes (on Functional Worker).
The Application Server becomes immutable—unchanged during extension installations.
All legacy components incompatible with .NET Standard are removed or replaced.

Deployments

Classical On-Premise (Windows)

Windows-based installations remain supported.
All Matrix42 services compiled with .NET Core for Windows.
Functional Worker runs as a Windows Service.

Private Cloud

Each release includes Linux Docker Images for Kubernetes-based deployment (BYOK model).
Delivered images:
- ESM Services
- ESM Setup
- ESM Functional Worker
Includes deployment scripts and automation recipes.

Public Cloud

Operated in Azure Kubernetes Services (AKS) using Linux containers.

Implementation Plan

Transition Strategy

Use .NET Standard as an interim compatibility bridge for existing extensions.
Target eventual migration to .NET 9+ once ecosystem readiness is ensured.

Legacy Component Removal

The original product uses a bunch of components and technologies which are not compatible with .NET Core, therefore they planned to be removed or replaced

Component	Change Version	Replacement
Microsoft WCF	12.1.2	Replaced with Web API
Access Database Engine	12.1.2
AutoMapper.dll	12.1.3	Updated to version 10.1.1.0
.NET Remoting	Q2/2026	Web API, Queue
.NET Framework	Q2/2026	.NET Core

Migration Roadmap by Release

Release 12.1.3

Changes

Core assemblies (Contracts, Data Layer, Behaviors, Engines) migrated to .NET Standard 2.0.
New SQL API introduced for non-DataLayer operations.
Replaced System.Data.SqlClient with Microsoft.Data.SqlClient for cross-platform compatibility.
Enhanced hosting support for resolving multiplatform dependencies.
New Middleware Behaviors model introduced. See more details on Middleware Behaviours
Scripted Web Operations and Scripted Diagnostic Rules running on Functional Worker (not in Web Server anymore)

Required Actions

Use the new SQL API for database transactions.
Rebuild and republish extensions if breaking changes are detected.
Set MinimalRequiredVersion=12.1.3 in updated packages.
Optionally target .NET Standard.
Begin adopting the New Middleware Behaviors model. See more details on Middleware Behaviours
Replace Business Engines call to Web Services

Business Engines

In earlier versions, the first generation of Service Layer–hosted services were run within the HostCommon process and declared in the Application as Engines. These services could be invoked from any other application process using code like:

using update4u.SPS.Engines;
EngineProxy.GetWorker(typeof(IInventoryDemandsWorker)).RemoveInvalidInventoryDemands();

This approach has been deprecated and removed as of version Q4/2025.

If your Extension relies on this pattern, you should now either use the corresponding Web API, or access the relevant business components directly.

Release Q4/2025

Changes

Legacy HostCommon and HostScheduler removed.
Background Engines moved to Functional Worker
Nearly all core assemblies now use .NET Standard.
Background tasks (excluding Workflow Engine) executed in .NET Core Functional Worker (Linux).
Extensions run in sandboxed environments.
Introduction of an agnostic API controller for Web API in sandboxed packages.
Introduction of an agnostic API for Engines.
PowerShell 7 Execution Engine
All Powershell script executed only in sandboxed container (Functional Worker), not on Web Server container

Required Actions

Migrate custom Middleware Behaviors to the new model.
Ensure full sandbox compatibility for all extensions.
Compile and publish extensions targeting .NET Standard.
Begin adopting the agnostic API controller for custom logic.
Begin migrating Powershell scripts from version 2 to version 7
Make sure the Powershell scripts not rely on Application Server (Web Server Container) infrastructure

Release Q2/2026

Changes

Web Server now runs on .NET Core.
Custom code executes only within Functional Worker sandboxes.
Agnostic Workflow Activities API introduced.

Required Actions

Implement workflow activities using the new agnostic API.

Release Q2/2026

Changes

Workflow Engine fully migrated to .NET Core Functional Worker.
Only PowerShell 7 supported executed on .NET Core Functional Worker.
.NET Framework Functional Worker is discontinued
All assemblies compiled and delivered on .NET Core

Migration Instructions

.NET Framework Assemblies Migration

All assemblies delivered with Extensions must be compiled on .NET Standard 2.0:

<TargetFramework>netstandard2.0</TargetFramework>

It is recommended to start migration with the internal release November 2025, which will also be shipped to partners. This release already contains all standard assemblies compiled for .NET Standard.

Packaging

During the transition until release 26.2, the platform will operate in a hybrid mode, supporting both legacy and new approaches.
To avoid incompatibility issues when installing packages across different product versions, we recommend delivering two separate Extension versions during this period:

Legacy Extension
"MaximumRequiredProductVersion": 24.5
(for older product versions, still using .NET Framework assemblies)
New Extension
"MinimalRequiredProductVersion": 26.1
(containing .NET Standard assemblies for the new approach)

Web Services

Custom Web Services registered in the Web Service Repository with implementations delivered in non-standard assemblies (i.e., not included in the distributive) will no longer run on the Application Web Server (w3wp/m42svc) after the migration.
Instead, execution moves to the Functional Worker process.

The system automatically creates virtual endpoint on the Web Server during initialization, ensuring that services remain accessible at the same endpoint as before.

Timelines

November 2025 – New Web Service model available in internal release for partners
26.1 – New Web Service model publicly available
26.2 – Custom Web Services only run on Functional Worker. Non-migrated services will stop working

To Do

Update custom Web Services to inherit from Matrix42.QueueProxy.WebApi.ApiController instead of System.Web.Http.ApiController.

Behaviors

Execution of custom CRUD operation behaviors is moved from the Web Application process to the Functional Worker in the new architecture.

Timelines

12.1.3 – New Middleware Behaviors model introduced
26.2 – Non-migrated custom Behaviors will no longer work

To Do

Rework custom Behaviors to inherit from Matrix42.Behaviors.Contracts.CustomGenericBehavior. See mode details in Data Object CRUD operations Middleware
Update the project to compile on .NET Standard 2.0.

PowerShell

PowerShell is widely used for customization in the product. Historically, PowerShell 2.0 has been the execution engine. However, PowerShell 2.0 is outdated and it cannot be executed on Linux. Therefore, all PowerShell scripts are be migrated to PowerShell 7, with execution delegated entirely to the Functional Worker.

From release 26.1, PowerShell scripts used in Scripted Web Service Operations, Scripted Diagnostic Rules, and Workflow scripts with directive (#ps-execution-engine=7) are running on the .NET Core Functional Worker by Powershell 7 engine.
Scripts triggered by Workflow Activity “Invoke PowerShell Activity” without directive (#ps-execution-engine=7) run on the .NET Framework Functional Worker.

Timelines

26.1 – PowerShell 7 Engine introduced on .NET Core Functional Worker.
Option to explcitly execute Invoke Powershell Activity scrtipt on Powerhsell 7 engine with diective #ps-execution-engine=7
26.2 – Workflow Engine runs on .NET Core. PowerShell scripts run exclusively on PowerShell 7.

To Do

Migrate scripts to PowerShell 7.
Use the following directive in Workflow scripts to enforce PowerShell 7 execution:
```
#ps-execution-engine=7 
```
Ensure scripts do not rely on relative paths, as execution folder changes in the new architecture.

Workflow Engine

Timelines

26.1 – Workflow Engine runs in .NET Framework Functional Worker (based on Workflow Foundation)
26.2 – Workflow Engine runs in .NET Core Functional Worker (based on CoreWF)