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.

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

Assemblies must be built in Self-Contained Deployment (SCD) mode on NET 8 or netstandard2.0. 

.NET Standard can be an appropriate choice if the target assembly needs to run both in modern .NET (Core) processes — such as the Functional Worker on Linux — and in legacy Windows processes that are still running on the .NET Framework, such as the Workflow Engine.

For .NET projects, it is recommended to use the default project configuration, which produces portable DLLs that can be executed across all supported environments.

In rare cases where the project references OS-specific APIs or uses native dependencies, the functionality may be delivered as separate platform-specific (RID-specific) assemblies. To enable this, specify the target runtime identifiers in the .csproj file:

<RuntimeIdentifiers>win-x64;linux-x64</RuntimeIdentifiers>

Portable assemblies must be placed in the ..\Assemblies folder.
RID-specific assemblies must be placed in ..\Assemblies\{rid}.

At runtime, when resolving assemblies, the system prioritizes RID-specific assemblies for the current runtime over portable assemblies.

Example:

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

If your custom assembly logic depends on business components hosted in the Dependency Container and declared in other assemblies, you must describe these dependencies in a *.dll.host.config file. This instructs the system to correctly initialize the sandbox process for executing your custom logic.
For more details, see the section “Dependency Container Components”.

Package Description

The package.json file must contain the property:

"Sandboxed": true
"MinimalRequiredProductVersion": "26.1.0"

This explicitly identifies the extension as a Sandboxed Extension.

Sandboxed Extensions are supported starting from version 26.1. Therefore, explicitly specifying the MinimalRequiredVersion is mandatory to prevent the extension from being installed on earlier versions that do not support sandboxing.

Example reference:  Imagoverum Fleet Management 

• internal Matrix42: https://matrix42.visualstudio.com/DWP/_git/ImagoverumFleetManagement
• external: Download 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.

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) are 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/DWP/_git/M42ExtensionScaffolder 
• External: M42ExtensionScaffolder.zip

How to use the Scaffolder

1. Download the package or clone the Git repository (Matrix42 internal).
2. Edit the appsettings.json file in Matrix42.Extensions.Scaffolder.Console to configure:
   1. Project folder
   2. Required runtimes
   3. Desired components
3. Run Matrix42.Extensions.Scaffolder.Console.exe.
4. 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.WebApi.Contracts.ApiController

For more details about custom web services development, see “Develop and Register Web Service”

Configuration Item Behavior

Inject custom logic into CRUD operations for specific CIs (ideal for validations or rules).

Behavior classes must inherit from:

class Matrix42.Behaviors.Contracts.CustomGenericBehavior