Sandboxed Extensions

OVERVIEW

Beginning with version 26.1, the platform introduces a new extension model — Sandboxed Extensions — designed to significantly improve product security, maintainability, and deployment reliability.
Custom assemblies and scripts no longer execute inside the Web Application process. Instead, all extension logic runs in isolated processes managed by the Functional Worker.

Starting from version 26.2, the platform supports only Sandboxed Extensions. Updating an instance to 26.2 will be blocked if any non-sandboxed extension is still installed.

Key Capabilities

Universal Deployment

Extensions implemented on .NET Core or .NET Standard include their own runtime dependencies, ensuring they run consistently across all supported deployment models without additional adjustments.

Zero-Downtime Installation

Sandboxed Extensions do not modify the Web Application or interact with active processes. Installation does not require application restarts and does not cause downtime.

Automatic Assembly Version Isolation

The Functional Worker automatically detects third-party assembly version conflicts. If a conflict occurs, it launches a dedicated process that loads only the required version, ensuring safe and isolated execution.

Secure and Isolated Execution

All custom logic executes within a controlled sandbox environment, preventing unintended side effects on the platform and improving overall system security.

Package Structure

Sandboxed Extension packages retain the general structure of classical extensions, with one major difference—the way assemblies and related resources are included.

Assemblies must be built in Self-Contained Deployment (SCD) mode on .NET, including the runtime for:

Windows (win-x64) for installations running on Windows Servers
Linux (linux-x64) for installations running in containerized environments

The package.json file must contain the property:

"Sandboxed": true

This explicitly identifies the extension as a Sandboxed Extension.

Example reference: Imagoverum Fleet Management

internal Matrix42: https://matrix42.visualstudio.com/DW...leetManagement
external: download the ImagoverumFleetManagement.zip

Installation

The main difference between Classical and Sandboxed extensions is how files are deployed.

Classical extensions copied files directly into the application folders (svc, bin), which caused several issues:

Security vulnerabilities
Required application restarts
Single-version assembly limitations
Risk of breaking product functionality

Sandboxed Extensions avoid these issues by keeping application folders immutable and storing all extension files in isolated storage locations, depending on the environment.

Resource	Deployment Model	Storage Location
Assemblies	Windows Server / VM	%AppFolder%\InstalledPackages\{packageID}\{version}
	Private Cloud (K8s)	S3-compatible blob storage in Cluster container
	Public Cloud	Azure Storage Account
Workspaces	All	ESM Web Server "WM" folder. Under construction: Move out of the application folder
Images	All	ESM Web Server "WM" folder. Under construction: Move out of the application folder

During installation, each deployed assembly and included runtime is registered in the database table DWPExtensionAssemblyClass, enabling dynamic discovery and correct runtime loading during execution.

Execution

All logic delivered with a Sandboxed Extension—whether script-based or assembly-based—is executed by the Functional Worker in an isolated process.
The main application process (M42Services) remains unaffected.

For each execution task, the Worker Dispatcher determines the required assemblies and spawns a process with the appropriate runtime environment.

Development Guidelines

The most universal and reliable approach to developing Sandboxed Extensions is to avoid custom assemblies when possible. The Matrix42 ESM platform provides rich low-code capabilities that often eliminate the need for compiled code:

Reporting Toolkit
Scripted Web Operations
Scripted System Diagnostic Rules
Workflow Designer with Scripted Actions and Functions
OpenAPI-based external integrations
Product APIs (Public REST and Internal) accessible from scripts

Extension Project Development

If a use case requires complex custom logic, custom assemblies may still be implemented.
For such scenarios, we recommend using the Matrix42 Extension Scaffolder, which provides:

Preconfigured solution structure
.NET Core project templates
Predefined folder layout
Preconfigured Azure DevOps pipeline templates
Automatic packaging logic

Matrix42 Scaffolder Extension:

Matrix42 internal: https://matrix42.visualstudio.com/DW...sionScaffolder
External: M42ExtensionScaffolder.zip

How to use the Scaffolder

Download the package or clone the Git repository (Matrix42 internal).
Edit the appsettings.json file in Matrix42.Extensions.Scaffolder.Console to configure:
- Project folder
- Required runtimes
- Desired components
Run Matrix42.Extensions.Scaffolder.Console.exe.
Open the generated Visual Studio solution and build.

Developing Individual Components

Since Sandboxed Extensions run in an isolated environment (Functional Worker), custom logic must follow supported customization patterns to ensure compatibility across platforms.

Business Engines

Logic executed on a defined schedule in a fully asynchronous, isolated process.
.NET Business Engine classes must inherit from:

class Matrix42.Engines.EngineController

Web Services

Extensions can expose custom web services on the Enterprise Web Server using:

class Matrix42.QueueProxy.WebApi.ApiController

Configuration Item Behaviour

Inject custom logic into CRUD operations for specific CIs (ideal for validations or rules).
Behavior classes must inherit from:

class Matrix42.Behaviors.Contracts.CustomGenericBehavior